tss_esapi/
lib.rs

1// Copyright 2019 Contributors to the Parsec project.
2// SPDX-License-Identifier: Apache-2.0
3#![deny(
4    nonstandard_style,
5    dead_code,
6    improper_ctypes,
7    non_shorthand_field_patterns,
8    no_mangle_generic_items,
9    overflowing_literals,
10    path_statements,
11    patterns_in_fns_without_body,
12    unconditional_recursion,
13    unused,
14    unused_allocation,
15    unused_comparisons,
16    unused_parens,
17    while_true,
18    missing_debug_implementations,
19    //TODO: activate this!
20    //missing_docs,
21    trivial_casts,
22    trivial_numeric_casts,
23    unused_extern_crates,
24    unused_import_braces,
25    unused_qualifications,
26    unused_results,
27    missing_copy_implementations,
28    rustdoc::broken_intra_doc_links,
29)]
30#![allow(clippy::multiple_crate_versions)]
31//! # TSS 2.0 Rust Wrapper over Enhanced System API
32//! This crate exposes the functionality of the TCG Software Stack Enhanced System API to
33//! Rust developers, both directly through FFI bindings and through more Rust-tailored interfaces
34//! at varying levels of abstraction.
35//! Only platforms based on processors with a word size of at least 16 bits are supported.
36//!
37//! # Relevant specifications
38//! This library is built with insight from Trusted Computing Group specifications. The specs most relevant
39//! here are:
40//! * the [Trusted Platform Module Library Specification, Family “2.0”, Level 00, Revision 01.59](https://trustedcomputinggroup.org/work-groups/trusted-platform-module/)
41//! * the [TCG TSS 2.0 Enhanced System API (ESAPI) Specification, version 1.00, revision 14](https://trustedcomputinggroup.org/resource/tcg-tss-2-0-enhanced-system-api-esapi-specification/)
42//!
43//! The different parts of the first spec mentioned above (henceforth called the TPM2 spec) can be
44//! referenced individually throughout the documentation of this crate, using their part number or name.
45//! For example,
46//! [Part 1, Architecture](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part1_Architecture_pub.pdf)
47//! could be referenced as "the Architecture spec" or "part 1 of the TPM2 spec".
48//!
49//! The second spec mentioned above will henceforth be called the ESAPI or ESys spec.
50//!
51//! Some parts of the code relate to features or functionality defined in other specifications (such as the
52//! [Marshaling/Unmarshaling API v1, rev7 spec](https://trustedcomputinggroup.org/resource/tcg-tss-2-0-marshalingunmarshaling-api-specification/)),
53//! and in such cases the specification should be linked and referenced in full.
54//!
55//! # Code structure
56//! Our code structure is mostly derived from part 2 of the TPM2 spec.
57//! For simplicity, however, we have reduced the depth of the import tree, so most (if not all) types
58//! are at most one level away from root.
59//!
60//! Minimum supported Rust version (MSRV):
61//! We currently check with version 1.66.0 of the Rust compiler during CI builds.
62//!
63//! # Notes on code safety:
64//! * thread safety is ensured by the required mutability of the `Context` structure within the
65//!   methods implemented on it; thus, in an otherwise safe app commands cannot be dispatched in
66//!   parallel for the same context; whether multithreading with multiple context objects is possible
67//!   depends on the TCTI used and this is the responsibility of the crate client to establish.
68//! * the `unsafe` keyword is used to denote methods that could panic, crash or cause undefined
69//!   behaviour. Whenever this is the case, the properties that need to be checked against
70//!   parameters before passing them in will be stated in the documentation of the method.
71//! * `unsafe` blocks within this crate need to be documented through code comments if they
72//!   are not covered by the points of trust described here.
73//! * the TSS2.0 library that this crate links to is trusted to return consistent values and to
74//!   not crash or lead to undefined behaviour when presented with valid arguments.
75//! * the `Mbox` crate is trusted to perform operations safely on the pointers provided to it, if
76//!   the pointers are trusted to be valid.
77//! * methods not marked `unsafe` are trusted to behave safely, potentially returning appropriate
78//!   error messages when encountering any problems.
79//! * whenever `unwrap`, `expect`, `panic` or derivatives of these are used, they need to be
80//!   thoroughly documented and justified - preferably `unwrap` and `expect` should *never* fail
81//!   during normal operation.
82//! * these rules can be broken in test-only code and in tests.
83//!
84//! # Logging
85//! This crate uses the typical `log` crate for printing errors generated in method calls. If
86//! you would like to filter out these log messages, please check with your logger documentation
87//! on how to do that.
88//!
89//! Additionally, the TSS library will also generate its own log messages and these can be
90//! controlled through environment variables as explained
91//! [here](https://github.com/tpm2-software/tpm2-tss/blob/main/doc/logging.md#runtime-log-level).
92//!
93pub use abstraction::transient::TransientKeyContext;
94pub use context::Context;
95pub use error::{Error, Result, WrapperErrorKind};
96pub use tcti_ldr::TctiNameConf;
97// To replace painlessly the old Tcti structure, should maybe be deprecated at some point.
98pub use tcti_ldr::TctiNameConf as Tcti;
99
100pub use tss_esapi_sys as tss2_esys;
101pub mod abstraction;
102pub mod attributes;
103pub mod constants;
104mod context;
105mod error;
106pub mod handles;
107pub mod interface_types;
108pub mod structures;
109pub mod tcti_ldr;
110pub mod traits;
111pub mod utils;
tss_esapi/lib.rs

tss_esapi/
lib.rs
