Tweak the docs some more.

Signed-off-by: Ionut Mihalcea <[email protected]>

Author: ionut-arm

tss-esapi/src/abstraction/transient/mod.rs

@@ -5,14 +5,7 @@
 //!
 //! This module presents an abstraction over the TPM functionality exposed through the core
 //! `Context` structure. The abstraction works by hiding resource handle management from the
-//! client. This is achieved by passing objects back and forth in the form of contexts. Thus, when
-//! an object is created, its saved context is returned and the object is flushed from the TPM.
-//! Whenever the client needs to use said object, it calls the desired operation with the context
-//! as a parameter - the context is loaded in the TPM, the operation performed and the context
-//! flushed out again before the result is returned.
-//!
-//! Object contexts thus act as an opaque handle that can, however, be used by the client to seralize
-//! and persist the underlying data.
+//! client.
 use crate::{
     attributes::{ObjectAttributesBuilder, SessionAttributesBuilder},
     constants::{tss::*, SessionType, Tss2ResponseCodeKind},
@@ -116,10 +109,10 @@ pub struct ObjectWrapper {
 /// Structure offering an abstracted programming experience.
 ///
 /// The `TransientKeyContext` makes use of a root key from which the other, client-controlled
-/// keyes are derived.
+/// keys are derived.
 ///
-/// The main goal of this abstraction is to make public key cryptography more accessible,
-/// focusing on asymmetric encryption and signatures in particular.
+/// This abstraction makes public key cryptography more accessible, focusing on asymmetric
+/// encryption and signatures in particular, by allowing users to offload object and session management.
 #[allow(clippy::module_name_repetitions)]
 #[derive(Debug)]
 pub struct TransientKeyContext {

tss-esapi/src/lib.rs

@@ -35,9 +35,26 @@
 //! at varying levels of abstraction.
 //! Only platforms based on processors with a word size of at least 16 bits are supported.
 //!
+//! # Relevant specifications
+//! This library is built with insight from Trusted Computing Group specifications. The specs most relevant
+//! here are:
+//! * the [Trusted Platform Module Library Specification, Family “2.0”, Level 00, Revision 01.59](https://trustedcomputinggroup.org/work-groups/trusted-platform-module/)
+//! * 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/)
+//!
+//! The different parts of the first spec mentioned above (henceforth called the TPM2 spec) can be
+//! referenced individually throughout the documentation of this crate, using their part number or name.
+//! For example,
+//! [Part 1, Architecture](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part1_Architecture_pub.pdf)
+//! could be referenced as "the Architecture spec" or "part 1 of the TPM2 spec".
+//!
+//! The second spec mentioned above will henceforth be called the ESAPI or ESys spec.
+//!
+//! Some parts of the code relate to features or functionality defined in other specifications (such as the
+//! [Marshaling/Unmarshaling API v1, rev7 spec](https://trustedcomputinggroup.org/resource/tcg-tss-2-0-marshalingunmarshaling-api-specification/)),
+//! and in such cases the specification should be linked and referenced in full.
+//!
 //! # Code structure
-//! Our code structure is mostly derived from
-//! [part 2 of the TPM2 TCG spec](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part2_Structures_pub.pdf).
+//! Our code structure is mostly derived from part 2 of the TPM2 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.
 //!

tss-esapi/src/utils/mod.rs

@@ -275,15 +275,15 @@ pub fn create_unrestricted_signing_ecc_public(
 /// Container for public key values
 #[derive(Debug, Clone, Serialize, Deserialize, Zeroize, PartialEq, Eq)]
 pub enum PublicKey {
-    /// RSA public modulus (see 27.5.3.4 in Architecture spec)
+    /// RSA public modulus (see 27.5.3.4 in the Architecture spec)
     ///
     /// This is the value extracted from the `unique` part of `TPMT_PUBLIC`.
     /// The exponent is not included here as the expectation is that the
     /// exponent is always pinned to 65537 (2^16 + 1).
     ///
     /// The modulus is in Big-Endian format.
     Rsa(Vec<u8>),
-    /// Public elliptic curve point (see 27.5.3.5 in Architecture spec)
+    /// Public elliptic curve point (see 27.5.3.5 in the Architecture spec)
     ///
     /// The x and y coordinates are given uncompressed.
     Ecc { x: Vec<u8>, y: Vec<u8> },