Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improves the general esys tr context methods documentation. #373

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
283 changes: 282 additions & 1 deletion tss-esapi/src/context/general_esys_tr.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand All @@ -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(
Expand All @@ -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(
Expand Down Expand Up @@ -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(
Expand Down
2 changes: 1 addition & 1 deletion tss-esapi/src/context/tpm_commands/non_volatile_storage.rs
Original file line number Diff line number Diff line change
Expand Up @@ -614,7 +614,7 @@ impl Context {
/// # .expect("Failed to set attributes on session");
/// # context.set_sessions((Some(session), None, None));
/// #
/// # let nv_index = NvIndexTpmHandle::new(0x01500025)
/// # let nv_index = NvIndexTpmHandle::new(0x01500027)
/// # .expect("Failed to create NV index tpm handle");
/// #
/// # // Create NV index attributes
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ mod test_tr_from_tpm_public {
fn test_tr_from_tpm_public_owner_auth() {
let mut context = create_ctx_without_session();

let nv_index_tpm_handle = NvIndexTpmHandle::new(0x01500021).unwrap();
let nv_index_tpm_handle = NvIndexTpmHandle::new(0x01500301).unwrap();

// closure for cleaning up if a call fails.
let cleanup = |context: &mut Context,
Expand Down Expand Up @@ -124,7 +124,7 @@ mod test_tr_from_tpm_public {

#[test]
fn test_tr_from_tpm_public_password_auth() {
let nv_index_tpm_handle = NvIndexTpmHandle::new(0x01500022).unwrap();
let nv_index_tpm_handle = NvIndexTpmHandle::new(0x01500302).unwrap();
remove_nv_index_handle_from_tpm(nv_index_tpm_handle, Provision::Owner);

let mut context = create_ctx_without_session();
Expand Down Expand Up @@ -226,7 +226,7 @@ mod test_tr_from_tpm_public {

#[test]
fn read_from_retrieved_handle_using_password_authorization() {
let nv_index_tpm_handle = NvIndexTpmHandle::new(0x01500023).unwrap();
let nv_index_tpm_handle = NvIndexTpmHandle::new(0x01500303).unwrap();

remove_nv_index_handle_from_tpm(nv_index_tpm_handle, Provision::Owner);

Expand Down Expand Up @@ -381,7 +381,7 @@ mod test_tr_from_tpm_public {
fn test_tr_get_tpm_handle() {
use tss_esapi::handles::TpmHandle;

let nv_index_tpm_handle = NvIndexTpmHandle::new(0x01500024).unwrap();
let nv_index_tpm_handle = NvIndexTpmHandle::new(0x01500304).unwrap();
remove_nv_index_handle_from_tpm(nv_index_tpm_handle, Provision::Owner);

let mut context = create_ctx_without_session();
Expand Down