Crate tss_esapi

source · [−]
Expand description

TSS 2.0 Rust Wrapper over Enhanced System API

This crate exposes the functionality of the TCG Software Stack Enhanced System API to Rust developers, both directly through FFI bindings and through more Rust-tailored interfaces at varying levels of abstraction. Only platforms based on processors with a word size of at least 16 bits are supported.

Code structure

Our code structure is mostly derived from part 2 of the TPM2 TCG spec. For simplicity, however, we have reduced the depth of the import tree, so most (if not all) types are at most one level away from root.

Minimum supported Rust version (MSRV): We currently check with version 1.53.0 of the Rust compiler during CI builds.

Notes on code safety:

  • thread safety is ensured by the required mutability of the Context structure within the methods implemented on it; thus, in an otherwise safe app commands cannot be dispatched in parallel for the same context; whether multithreading with multiple context objects is possible depends on the TCTI used and this is the responsibility of the crate client to establish.
  • the unsafe keyword is used to denote methods that could panic, crash or cause undefined behaviour. Whenever this is the case, the properties that need to be checked against parameters before passing them in will be stated in the documentation of the method.
  • unsafe blocks within this crate need to be documented through code comments if they are not covered by the points of trust described here.
  • the TSS2.0 library that this crate links to is trusted to return consistent values and to not crash or lead to undefined behaviour when presented with valid arguments.
  • the Mbox crate is trusted to perform operations safely on the pointers provided to it, if the pointers are trusted to be valid.
  • methods not marked unsafe are trusted to behave safely, potentially returning appropriate error messages when encountering any problems.
  • whenever unwrap, expect, panic or derivatives of these are used, they need to be thoroughly documented and justified - preferably unwrap and expect should never fail during normal operation.
  • these rules can be broken in test-only code and in tests.

Logging

This crate uses the typical log crate for printing errors generated in method calls. If you would like to filter out these log messages, please check with your logger documentation on how to do that.

Additionally, the TSS library will also generate its own log messages and these can be controlled through environment variables as explained here.

Re-exports

pub use abstraction::transient::TransientKeyContext;
pub use tcti_ldr::TctiNameConf;
pub use tcti_ldr::TctiNameConf as Tcti;
pub use tss_esapi_sys as tss2_esys;

Modules

abstraction
attributes

Module for representation of attributes

constants
handles
interface_types

This module contains the different interface types defined in the TPM 2.0 specification.

structures
tcti_ldr

Wrapper around the TCTI Loader Library interface. See section 3.5 of the TCG TSS 2.0 TPM Command Transmission Interface(TCTI) API Specification.

traits
utils

Utility module

Structs

Context

Safe abstraction over an ESYS_CONTEXT.

Enums

Error
WrapperErrorKind

List of error types that might occur in the wrapper.

Type Definitions

Result

Main error type used by the crate to return issues with a method call. The value can either be a TSS-generated response code or a wrapper error - marking an issue caught within the wrapping layer.