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 - preferablyunwrap
andexpect
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
Module for representation of attributes
This module contains the different interface types defined in the TPM 2.0 specification.
Wrapper around the TCTI Loader Library interface. See section 3.5 of the TCG TSS 2.0 TPM Command Transmission Interface(TCTI) API Specification.
Utility module
Structs
Safe abstraction over an ESYS_CONTEXT.
Enums
List of error types that might occur in the wrapper.
Type Definitions
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.