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. At the moment, the abstracted functionality focuses on creating signing and encryption RSA keys, as well as signing and verifying signatures. Only platforms based on processors with a word size of at least 16 bits are supported.
The crate is expected to successfully compile and run using the nightly compiler and any other Rust compiler since 1.38.0.
The current version of the API does not offer any security or code safety guarantees as it has not been tested to a desired level of confidence. The implementation that is provided is suitable for exploratory testing and experimentation only. This test implementation does not offer any tangible security benefits and therefore is not suitable for use in production. Contributions from the developer community are welcome. Please refer to the contribution guidelines.
The modules comprising the crate expose the following functionalities:
- lib/root module - exposes the
Contextstructure, the most basic abstraction over the ESAPI, on top of which all other abstraction layers are implemented.
- utils - exposes Rust-native versions and/or builders for (some of) the structures defined in the TSS 2.0 specification; it also offers convenience methods for generating very specific parameter structures for use in certain operations.
- response_code - implements error code parsing for the formats defined in the TSS spec and exposes it along with wrapper-specific error types.
- abstraction - intended to offer abstracted interfaces that focus on providing different kinds of user experience to the developers; at the moment the only implementation allows for a resource-handle-free coding experience by working soloely with object contexts.
- tss2_esys - exposes raw FFI bindings to the Enhanced System API.
- constants - exposes constants that were ported to Rust manually as bindgen does not support converting them yet.
- thread safety is ensured by the required mutability of the
Contextstructure 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 responsability of the crate client to establish.
unsafekeyword 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.
unsafeblocks 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.
Mboxcrate is trusted to perform operations safely on the pointers provided to it, if the pointers are trusted to be valid.
- methods not marked
unsafeare trusted to behave safely, potentially returning appropriate erorr messages when encountering any problems.
panicor derivatives of these are used, they need to be thoroughly documented and justified - preferably
expectshould never fail during normal operation.
- these rules can be broken in test-only code and in tests.
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.
Module for representation of attributes
This module contains the different interface types defined in the TPM 2.0 specification.
Safe abstraction over an ESYS_CONTEXT.
Placeholder TCTI types that can be used when initialising a
List of error types that might occur in the wrapper.
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.