Merge pull request #347 from ionut-arm/tkc-docs

Expand documentation around TransientKeyContext

Author: Superhepper

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},
@@ -56,7 +49,9 @@ pub enum KeyParams {
         scheme: RsaScheme,
         /// Public exponent of the key
         ///
-        /// If set to 0, it will default to 2^16 - 1
+        /// If set to 0, it will default to 2^16 - 1.
+        ///
+        /// (Note that the default value for [`RsaExponent`] is 0)
         pub_exponent: RsaExponent,
     },
     Ecc {
@@ -72,6 +67,9 @@ pub enum KeyParams {
 /// The `public` field represents the public part of the key in plain text,
 /// while `private` is the encrypted version of the private key.
 ///
+/// For information on public key formats, see the documentation of [`PublicKey`].
+/// The private part of the key should be treated as an opaque binary blob.
+///
 /// # Warning
 ///
 /// If the Owner hierarchy is cleared, any key material generated
@@ -94,6 +92,13 @@ impl KeyMaterial {
     }
 }
 
+/// Structure containing all the defining elements of a TPM key
+///
+/// - `material` identifies the numeric value of the key object
+/// - `params` identifies the algorithm to use on the key and other relevant
+/// parameters
+/// - `auth` identifies the optional authentication value to be used with the
+/// key
 #[derive(Debug, Clone)]
 pub struct ObjectWrapper {
     pub material: KeyMaterial,
@@ -104,13 +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.
 ///
-/// Currently, only functionality necessary for RSA key creation and usage (for signing,
-/// verifying signatures, encryption and decryption) is implemented. The RSA SSA
-/// asymmetric scheme with SHA256 is used for all created and imported signing keys.
-/// The RSA OAEP asymmetric scheme with SHA256 is used for all created and imported
-/// signing/encryption/decryption keys.
+/// 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 {
@@ -126,6 +128,10 @@ impl TransientKeyContext {
     /// If successful, the result contains the [KeyMaterial] of the key and a vector of
     /// bytes forming the authentication value for said key.
     ///
+    /// The following key attributes are always **set**: `fixed_tpm`, `fixed_parent`, `sensitive_data_origin`,
+    /// `user_with_auth`. The `restricted` attribute is **not set**. See section 8.3 in the Structures
+    /// spec for a detailed description of these attributes.
+    ///
     /// # Constraints
     /// * `auth_size` must be at most 32
     ///
@@ -170,7 +176,7 @@ impl TransientKeyContext {
 
     /// Load the public part of a key.
     ///
-    /// Returns the key context.
+    /// Returns the appropriate key material after verifying that the key can be loaded.
     pub fn load_external_public_key(
         &mut self,
         public_key: PublicKey,
@@ -190,8 +196,10 @@ impl TransientKeyContext {
 
     /// Encrypt a message with an existing key.
     ///
-    /// Takes the key as a parameter, encrypts the message and returns the ciphertext. A label (i.e.
-    /// nonce) can also be provided.
+    /// Takes the key as a set of parameters (`key_material`, `key_params`, `key_auth`), encrypts the message
+    /// and returns the ciphertext. A label can also be provided which will be associated with the ciphertext.
+    ///
+    /// Note: the data passed as `label` MUST end in a `0x00` byte.
     pub fn rsa_encrypt(
         &mut self,
         key_material: KeyMaterial,
@@ -228,8 +236,10 @@ impl TransientKeyContext {
 
     /// Decrypt ciphertext with an existing key.
     ///
-    /// Takes the key as a parameter, decrypts the ciphertext and returns the plaintext. A label (i.e.
-    /// nonce) can also be provided.
+    /// Takes the key as a set of parameters (`key_material`, `key_params`, `key_auth`), decrypts the ciphertext
+    /// and returns the plaintext. A label which was associated with the ciphertext can also be provided.
+    ///
+    /// Note: the data passed as `label` MUST end in a `0x00` byte.
     pub fn rsa_decrypt(
         &mut self,
         key_material: KeyMaterial,
@@ -266,7 +276,7 @@ impl TransientKeyContext {
 
     /// Sign a digest with an existing key.
     ///
-    /// Takes the key as a parameter, signs and returns the signature.
+    /// Takes the key as a set of parameters (`key_material`, `key_params`, `key_auth`), signs and returns the signature.
     pub fn sign(
         &mut self,
         key_material: KeyMaterial,

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/structures/attestation/attest.rs

@@ -27,7 +27,7 @@ pub struct Attest {
 }
 
 impl Attest {
-    /// Returns ttestation type
+    /// Returns attestation type
     pub const fn attestation_type(&self) -> AttestationType {
         self.attestation_type
     }
@@ -37,7 +37,7 @@ impl Attest {
         &self.qualified_signer
     }
 
-    /// Retirns the extra data specified by the caller.
+    /// Returns the extra data specified by the caller.
     pub const fn extra_data(&self) -> &Data {
         &self.extra_data
     }
@@ -121,6 +121,7 @@ impl TryFrom<TPMS_ATTEST> for Attest {
 impl Marshall for Attest {
     const BUFFER_SIZE: usize = std::mem::size_of::<TPMS_ATTEST>();
 
+    /// Produce a marshalled [`TPMS_ATTEST`]
     fn marshall(&self) -> Result<Vec<u8>> {
         let mut buffer = vec![0; Self::BUFFER_SIZE];
         let mut offset = 0;
@@ -153,6 +154,7 @@ impl Marshall for Attest {
 }
 
 impl UnMarshall for Attest {
+    /// Unmarshall the structure from [`TPMS_ATTEST`]
     fn unmarshall(marshalled_data: &[u8]) -> Result<Self> {
         let mut dest = TPMS_ATTEST::default();
         let mut offset = 0;

tss-esapi/src/structures/buffers/public.rs

@@ -119,6 +119,7 @@ impl TryFrom<Public> for PublicBuffer {
 impl Marshall for PublicBuffer {
     const BUFFER_SIZE: usize = std::mem::size_of::<TPM2B_PUBLIC>();
 
+    /// Produce a marshalled [`TPM2B_PUBLIC`]
     fn marshall(&self) -> Result<Vec<u8>> {
         let mut buffer = vec![0; Self::BUFFER_SIZE];
         let mut offset = 0;
@@ -151,6 +152,7 @@ impl Marshall for PublicBuffer {
 }
 
 impl UnMarshall for PublicBuffer {
+    /// Unmarshall the structure from [`TPM2B_PUBLIC`]
     fn unmarshall(marshalled_data: &[u8]) -> Result<Self> {
         let mut dest = TPM2B_PUBLIC::default();
         let mut offset = 0;

tss-esapi/src/structures/buffers/sensitive.rs

@@ -118,6 +118,7 @@ impl TryFrom<Sensitive> for SensitiveBuffer {
 impl Marshall for SensitiveBuffer {
     const BUFFER_SIZE: usize = std::mem::size_of::<TPM2B_SENSITIVE>();
 
+    /// Produce a marshalled [`TPM2B_SENSITIVE`]
     fn marshall(&self) -> Result<Vec<u8>> {
         let mut buffer = vec![0; Self::BUFFER_SIZE];
         let mut offset = 0;
@@ -150,6 +151,7 @@ impl Marshall for SensitiveBuffer {
 }
 
 impl UnMarshall for SensitiveBuffer {
+    /// Unmarshall the structure from [`TPM2B_SENSITIVE`]
     fn unmarshall(marshalled_data: &[u8]) -> Result<Self> {
         let mut dest = TPM2B_SENSITIVE::default();
         let mut offset = 0;

tss-esapi/src/structures/signatures.rs

@@ -10,6 +10,9 @@ use log::error;
 use std::convert::{TryFrom, TryInto};
 
 /// Type holding RSA signature information.
+///
+/// For more information about the contents of `signature` see Annex B
+/// in the Architecture spec.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct RsaSignature {
     hashing_algorithm: HashingAlgorithm,
@@ -70,6 +73,9 @@ impl TryFrom<TPMS_SIGNATURE_RSA> for RsaSignature {
 }
 
 /// Type holding ECC signature information.
+///
+/// For more information about the contents of `signature_r` and `signature_s`
+/// see Annex B in the Architecture spec (or Annex D for SM2 signatures).
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct EccSignature {
     hashing_algorithm: HashingAlgorithm,

tss-esapi/src/structures/tagged/public.rs

@@ -76,7 +76,7 @@ impl PublicBuilder {
         self
     }
 
-    /// Adds the name hash algorithm for the [Public] strucutre
+    /// Adds the name hash algorithm for the [Public] structure
     /// to the builder.
     pub const fn with_name_hashing_algorithm(
         mut self,
@@ -86,7 +86,7 @@ impl PublicBuilder {
         self
     }
 
-    /// Adds the auth policy for the [Public] strucutre
+    /// Adds the auth policy for the [Public] structure
     /// to the builder
     pub fn with_auth_policy(mut self, auth_policy: Digest) -> Self {
         self.auth_policy = Some(auth_policy);
@@ -494,6 +494,9 @@ impl TryFrom<TPMT_PUBLIC> for Public {
 impl Marshall for Public {
     const BUFFER_SIZE: usize = std::mem::size_of::<TPMT_PUBLIC>();
 
+    /// Produce a marshalled [TPMT_PUBLIC]
+    ///
+    /// Note: for [TPM2B_PUBLIC] marshalling use [PublicBuffer][`crate::structures::PublicBuffer]
     fn marshall(&self) -> Result<Vec<u8>> {
         let mut buffer = vec![0; Self::BUFFER_SIZE];
         let mut offset = 0;
@@ -526,6 +529,9 @@ impl Marshall for Public {
 }
 
 impl UnMarshall for Public {
+    /// Unmarshall the structure from [`TPMT_PUBLIC`]
+    ///
+    /// Note: for [TPM2B_PUBLIC] unmarshalling use [PublicBuffer][`crate::structures::PublicBuffer]
     fn unmarshall(marshalled_data: &[u8]) -> Result<Self> {
         let mut dest = TPMT_PUBLIC::default();
         let mut offset = 0;

tss-esapi/src/structures/tagged/sensitive.rs

@@ -166,6 +166,9 @@ impl TryFrom<TPMT_SENSITIVE> for Sensitive {
 impl Marshall for Sensitive {
     const BUFFER_SIZE: usize = std::mem::size_of::<TPMT_SENSITIVE>();
 
+    /// Produce a marshalled [`TPMT_SENSITIVE`]
+    ///
+    /// Note: for [TPM2B_SENSITIVE] marshalling use [SensitiveBuffer][`crate::structures::SensitiveBuffer]
     fn marshall(&self) -> Result<Vec<u8>> {
         let mut buffer = vec![0; Self::BUFFER_SIZE];
         let mut offset = 0;
@@ -198,6 +201,9 @@ impl Marshall for Sensitive {
 }
 
 impl UnMarshall for Sensitive {
+    /// Unmarshall the structure from [`TPMT_SENSITIVE`]
+    ///
+    /// Note: for [TPM2B_SENSITIVE] marshalling use [SensitiveBuffer][`crate::structures::SensitiveBuffer]
     fn unmarshall(marshalled_data: &[u8]) -> Result<Self> {
         let mut dest = TPMT_SENSITIVE::default();
         let mut offset = 0;

tss-esapi/src/structures/tagged/signature.rs

@@ -132,6 +132,7 @@ impl TryFrom<TPMT_SIGNATURE> for Signature {
 impl Marshall for Signature {
     const BUFFER_SIZE: usize = std::mem::size_of::<TPMT_SIGNATURE>();
 
+    /// Produce a marshalled [`TPMT_SIGNATURE`]
     fn marshall(&self) -> Result<Vec<u8>> {
         let tpmt_sig = TPMT_SIGNATURE::try_from(self.clone())?;
         let mut offset = 0;
@@ -164,6 +165,7 @@ impl Marshall for Signature {
 }
 
 impl UnMarshall for Signature {
+    /// Unmarshall the structure from [`TPMT_SIGNATURE`]
     fn unmarshall(public_buffer: &[u8]) -> Result<Self> {
         let mut tpmt_sig = TPMT_SIGNATURE::default();
         let mut offset = 0;

tss-esapi/src/structures/tagged/symmetric.rs

@@ -9,7 +9,7 @@ use crate::{
     Error, Result, WrapperErrorKind,
 };
 use std::convert::{TryFrom, TryInto};
-/// Enum repsesnting the symmetric algorithm definition.
+/// Enum representing the symmetric algorithm definition.
 ///
 /// # Details
 /// This corresponds to TPMT_SYM_DEF.