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 <[email protected]>

Author: Superhepper

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<Name> {
         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<ObjectHandle> {
         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(