From 0c597cc6b4bac908cf5c5d81a357632dd3bb7522 Mon Sep 17 00:00:00 2001 From: Jesper Brynolf Date: Mon, 19 Sep 2022 15:51:29 +0200 Subject: [PATCH] Improves documentation of general esys tr context emthods. - Improves the documentation of the general esys tr context methods by add ing description of arguments and code examples. Signed-off-by: Jesper Brynolf --- tss-esapi/src/context/general_esys_tr.rs | 283 ++++++++++++++++++++++- 1 file changed, 282 insertions(+), 1 deletion(-) diff --git a/tss-esapi/src/context/general_esys_tr.rs b/tss-esapi/src/context/general_esys_tr.rs index cc1e3196..4caff983 100644 --- a/tss-esapi/src/context/general_esys_tr.rs +++ b/tss-esapi/src/context/general_esys_tr.rs @@ -16,6 +16,25 @@ use zeroize::Zeroize; impl Context { /// Set the authentication value for a given object handle in the ESYS context. + /// + /// # Arguments + /// * `object_handle` - The [ObjectHandle] associated with an object for which the auth is to be set. + /// * `auth` - The [Auth] that is to be set. + /// + /// ```rust + /// # use tss_esapi::{Context, TctiNameConf}; + /// use tss_esapi::{handles::ObjectHandle, structures::Auth}; + /// # // Create context + /// # let mut context = + /// # Context::new( + /// # TctiNameConf::from_environment_variable().expect("Failed to get TCTI"), + /// # ).expect("Failed to create Context"); + /// + /// // Sets auth for Owner to empty string. + /// context + /// .tr_set_auth(ObjectHandle::Owner, Auth::default()) + /// .expect("Failed to call tr_set_auth"); + /// ``` pub fn tr_set_auth(&mut self, object_handle: ObjectHandle, auth: Auth) -> Result<()> { let mut auth_value = auth.into(); ReturnCode::ensure_success( @@ -27,7 +46,86 @@ impl Context { ) } - /// Retrieve the name of an object from the object handle + /// Retrieve the name of an object from the object handle. + /// + /// # Arguments + /// * `object_handle` - Handle to the object for which the 'name' shall be retrieved. + /// + /// # Returns + /// The objects name. + /// + /// # Example + /// ```rust + /// # use tss_esapi::{ + /// # Context, TctiNameConf, attributes::{SessionAttributes, NvIndexAttributes}, + /// # constants::SessionType, handles::NvIndexTpmHandle, + /// # interface_types::{algorithm::HashingAlgorithm, resource_handles::Provision}, + /// # structures::{SymmetricDefinition, NvPublic}, + /// # }; + /// # // Create context + /// # let mut context = + /// # Context::new( + /// # TctiNameConf::from_environment_variable().expect("Failed to get TCTI"), + /// # ).expect("Failed to create Context"); + /// # + /// # let session = context + /// # .start_auth_session( + /// # None, + /// # None, + /// # None, + /// # SessionType::Hmac, + /// # SymmetricDefinition::AES_256_CFB, + /// # HashingAlgorithm::Sha256, + /// # ) + /// # .expect("Failed to create session") + /// # .expect("Received invalid handle"); + /// # let (session_attributes, session_attributes_mask) = SessionAttributes::builder() + /// # .with_decrypt(true) + /// # .with_encrypt(true) + /// # .build(); + /// # context.tr_sess_set_attributes(session, session_attributes, session_attributes_mask) + /// # .expect("Failed to set attributes on session"); + /// # context.set_sessions((Some(session), None, None)); + /// # + /// # let nv_index = NvIndexTpmHandle::new(0x01500401) + /// # .expect("Failed to create NV index tpm handle"); + /// # + /// # // Create NV index attributes + /// # let owner_nv_index_attributes = NvIndexAttributes::builder() + /// # .with_owner_write(true) + /// # .with_owner_read(true) + /// # .build() + /// # .expect("Failed to create owner nv index attributes"); + /// # + /// # // Create owner nv public. + /// # let owner_nv_public = NvPublic::builder() + /// # .with_nv_index(nv_index) + /// # .with_index_name_algorithm(HashingAlgorithm::Sha256) + /// # .with_index_attributes(owner_nv_index_attributes) + /// # .with_data_area_size(32) + /// # .build() + /// # .expect("Failed to build NvPublic for owner"); + /// # + /// # // Define the NV space. + /// # let nv_index_handle = context + /// # .nv_define_space(Provision::Owner, None, owner_nv_public) + /// # .expect("Call to nv_define_space failed"); + /// + /// // Get the name using tr_get_name + /// let tr_get_name_result = context.tr_get_name(nv_index_handle.into()); + /// + /// // Get the name from the NV by calling nv_read_public + /// let nv_read_public_result = context.nv_read_public(nv_index_handle); + /// # + /// # context + /// # .nv_undefine_space(Provision::Owner, nv_index_handle) + /// # .expect("Call to nv_undefine_space failed"); + /// # + /// // Process result by comparing the names + /// let (_public_area, expected_name) = nv_read_public_result.expect("Call to nv_read_public failed"); + /// let actual_name = tr_get_name_result.expect("Call to tr_get_name failed"); + /// assert_eq!(expected_name, actual_name); + /// ``` pub fn tr_get_name(&mut self, object_handle: ObjectHandle) -> Result { let mut name_ptr = null_mut(); ReturnCode::ensure_success( @@ -40,6 +138,103 @@ impl Context { } /// Used to construct an esys object from the resources inside the TPM. + /// + /// # Arguments + /// * `tpm_handle` - The TPM handle that references the TPM object for which + /// the ESYS object is being created. + /// + /// # Returns + /// A handle to the ESYS object that was created from a TPM resource. + /// + /// # Example + /// ```rust + /// # use tss_esapi::{ + /// # Context, TctiNameConf, attributes::{SessionAttributes, NvIndexAttributes}, + /// # constants::SessionType, + /// # interface_types::{algorithm::HashingAlgorithm, resource_handles::Provision}, + /// # structures::{SymmetricDefinition, NvPublic}, + /// # }; + /// use tss_esapi::{ + /// handles::NvIndexTpmHandle, + /// }; + /// # // Create context + /// # let mut context = + /// # Context::new( + /// # TctiNameConf::from_environment_variable().expect("Failed to get TCTI"), + /// # ).expect("Failed to create Context"); + /// # + /// # let session = context + /// # .start_auth_session( + /// # None, + /// # None, + /// # None, + /// # SessionType::Hmac, + /// # SymmetricDefinition::AES_256_CFB, + /// # HashingAlgorithm::Sha256, + /// # ) + /// # .expect("Failed to create session") + /// # .expect("Received invalid handle"); + /// # let (session_attributes, session_attributes_mask) = SessionAttributes::builder() + /// # .with_decrypt(true) + /// # .with_encrypt(true) + /// # .build(); + /// # context.tr_sess_set_attributes(session, session_attributes, session_attributes_mask) + /// # .expect("Failed to set attributes on session"); + /// # context.set_sessions((Some(session), None, None)); + /// # + /// let nv_index = NvIndexTpmHandle::new(0x01500402) + /// .expect("Failed to create NV index tpm handle"); + /// # + /// # // Create NV index attributes + /// # let owner_nv_index_attributes = NvIndexAttributes::builder() + /// # .with_owner_write(true) + /// # .with_owner_read(true) + /// # .build() + /// # .expect("Failed to create owner nv index attributes"); + /// # + /// # // Create owner nv public. + /// # let owner_nv_public = NvPublic::builder() + /// # .with_nv_index(nv_index) + /// # .with_index_name_algorithm(HashingAlgorithm::Sha256) + /// # .with_index_attributes(owner_nv_index_attributes) + /// # .with_data_area_size(32) + /// # .build() + /// # .expect("Failed to build NvPublic for owner"); + /// # + /// # // Define the NV space. + /// # let nv_index_handle = context + /// # .nv_define_space(Provision::Owner, None, owner_nv_public) + /// # .expect("Call to nv_define_space failed"); + /// # + /// # // Retrieve the name of the NV space. + /// # let nv_read_public_result = context.nv_read_public(nv_index_handle); + /// # + /// # // Close the handle (remove all the metadata). + /// # let mut handle_to_be_closed = nv_index_handle.into(); + /// # let tr_close_result = context + /// # .tr_close(&mut handle_to_be_closed); + /// # + /// // Call function without session (session can be provided in order to + /// // verify that the public data read actually originates from this TPM). + /// let retrieved_handle = context.execute_without_session(|ctx| { + /// ctx.tr_from_tpm_public(nv_index.into()) + /// }) + /// .expect("Call to tr_from_tpm_public failed."); + /// # + /// # // Use the retrieved handle to get the name of the object. + /// # let tr_get_name_result = context + /// # .tr_get_name(retrieved_handle); + /// # + /// # context + /// # .nv_undefine_space(Provision::Owner, retrieved_handle.into()) + /// # .expect("Call to nv_undefine_space failed"); + /// # + /// # // Process results. + /// # tr_close_result.expect("Call to tr_close_result failed"); + /// # let (_, expected_name) = nv_read_public_result.expect("Call to nv_read_public failed"); + /// # let actual_name = tr_get_name_result.expect("Call to tr_get_name failed"); + /// # assert_eq!(expected_name, actual_name); + /// ``` pub fn tr_from_tpm_public(&mut self, tpm_handle: TpmHandle) -> Result { let mut object = ObjectHandle::None.into(); ReturnCode::ensure_success( @@ -71,6 +266,92 @@ impl Context { /// Instructs the ESAPI to release the metadata and resources allocated for a specific ObjectHandle. /// /// This is useful for cleaning up handles for which the context cannot be flushed. + /// + /// # Arguments + /// * object_handle`- An [ObjectHandle] referring to an object for which all metadata and + /// resources is going to be released. + /// + /// # Example + /// ```rust + /// # use tss_esapi::{ + /// # Context, TctiNameConf, attributes::{SessionAttributes, NvIndexAttributes}, + /// # constants::SessionType, handles::NvIndexTpmHandle, + /// # interface_types::{algorithm::HashingAlgorithm, resource_handles::Provision}, + /// # structures::{SymmetricDefinition, NvPublic}, + /// # }; + /// # // Create context + /// # let mut context = + /// # Context::new( + /// # TctiNameConf::from_environment_variable().expect("Failed to get TCTI"), + /// # ).expect("Failed to create Context"); + /// # + /// # let session = context + /// # .start_auth_session( + /// # None, + /// # None, + /// # None, + /// # SessionType::Hmac, + /// # SymmetricDefinition::AES_256_CFB, + /// # HashingAlgorithm::Sha256, + /// # ) + /// # .expect("Failed to create session") + /// # .expect("Received invalid handle"); + /// # let (session_attributes, session_attributes_mask) = SessionAttributes::builder() + /// # .with_decrypt(true) + /// # .with_encrypt(true) + /// # .build(); + /// # context.tr_sess_set_attributes(session, session_attributes, session_attributes_mask) + /// # .expect("Failed to set attributes on session"); + /// # context.set_sessions((Some(session), None, None)); + /// # + /// let nv_index = NvIndexTpmHandle::new(0x01500403) + /// .expect("Failed to create NV index tpm handle"); + /// # + /// # // Create NV index attributes + /// # let owner_nv_index_attributes = NvIndexAttributes::builder() + /// # .with_owner_write(true) + /// # .with_owner_read(true) + /// # .build() + /// # .expect("Failed to create owner nv index attributes"); + /// # + /// # // Create owner nv public. + /// # let owner_nv_public = NvPublic::builder() + /// # .with_nv_index(nv_index) + /// # .with_index_name_algorithm(HashingAlgorithm::Sha256) + /// # .with_index_attributes(owner_nv_index_attributes) + /// # .with_data_area_size(32) + /// # .build() + /// # .expect("Failed to build NvPublic for owner"); + /// # + /// # // Define the NV space. + /// # let nv_index_handle = context + /// # .nv_define_space(Provision::Owner, None, owner_nv_public) + /// # .expect("Call to nv_define_space failed"); + /// # + /// # // Close the handle (remove all the metadata). + /// # let mut handle_to_be_closed = nv_index_handle.into(); + /// let tr_close_result = context + /// .tr_close(&mut handle_to_be_closed); + /// # + /// # // Use the retrieved handle to get the name of the object. + /// # let tr_get_name_result = context + /// # .tr_get_name(nv_index_handle.into()); + /// # + /// # // Call function without session (session can be provided in order to + /// # // verify that the public data read actually originates from this TPM). + /// # let retrieved_handle = context.execute_without_session(|ctx| { + /// # ctx.tr_from_tpm_public(nv_index.into()) + /// # }) + /// # .expect("Call to tr_from_tpm_public failed."); + /// # + /// # context + /// # .nv_undefine_space(Provision::Owner, retrieved_handle.into()) + /// # .expect("Call to nv_undefine_space failed"); + /// # + /// // Process results. + /// tr_close_result.expect("Call to tr_close failed."); + /// # tr_get_name_result.expect_err("Calling tr_get_name with invalid handle did not result in an error."); + /// ``` pub fn tr_close(&mut self, object_handle: &mut ObjectHandle) -> Result<()> { let mut rsrc_handle = object_handle.try_into_not_none()?; ReturnCode::ensure_success(