Skip to content

Commit f123b99

Browse files
ionut-armionut-arm
authored
Merge pull request #373 from Superhepper/general-esys-tr-documentation
Improves the general esys tr context methods documentation.
2 parents ac7efa4 + 0c597cc commit f123b99

File tree

3 files changed

+287
-6
lines changed

3 files changed

+287
-6
lines changed

‎tss-esapi/src/context/general_esys_tr.rs

+282-1
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,25 @@ use zeroize::Zeroize;
1616

1717
impl Context {
1818
/// Set the authentication value for a given object handle in the ESYS context.
19+
///
20+
/// # Arguments
21+
/// * `object_handle` - The [ObjectHandle] associated with an object for which the auth is to be set.
22+
/// * `auth` - The [Auth] that is to be set.
23+
///
24+
/// ```rust
25+
/// # use tss_esapi::{Context, TctiNameConf};
26+
/// use tss_esapi::{handles::ObjectHandle, structures::Auth};
27+
/// # // Create context
28+
/// # let mut context =
29+
/// # Context::new(
30+
/// # TctiNameConf::from_environment_variable().expect("Failed to get TCTI"),
31+
/// # ).expect("Failed to create Context");
32+
///
33+
/// // Sets auth for Owner to empty string.
34+
/// context
35+
/// .tr_set_auth(ObjectHandle::Owner, Auth::default())
36+
/// .expect("Failed to call tr_set_auth");
37+
/// ```
1938
pub fn tr_set_auth(&mut self, object_handle: ObjectHandle, auth: Auth) -> Result<()> {
2039
let mut auth_value = auth.into();
2140
ReturnCode::ensure_success(
@@ -27,7 +46,86 @@ impl Context {
2746
)
2847
}
2948

30-
/// Retrieve the name of an object from the object handle
49+
/// Retrieve the name of an object from the object handle.
50+
///
51+
/// # Arguments
52+
/// * `object_handle` - Handle to the object for which the 'name' shall be retrieved.
53+
///
54+
/// # Returns
55+
/// The objects name.
56+
///
57+
/// # Example
58+
/// ```rust
59+
/// # use tss_esapi::{
60+
/// # Context, TctiNameConf, attributes::{SessionAttributes, NvIndexAttributes},
61+
/// # constants::SessionType, handles::NvIndexTpmHandle,
62+
/// # interface_types::{algorithm::HashingAlgorithm, resource_handles::Provision},
63+
/// # structures::{SymmetricDefinition, NvPublic},
64+
/// # };
65+
/// # // Create context
66+
/// # let mut context =
67+
/// # Context::new(
68+
/// # TctiNameConf::from_environment_variable().expect("Failed to get TCTI"),
69+
/// # ).expect("Failed to create Context");
70+
/// #
71+
/// # let session = context
72+
/// # .start_auth_session(
73+
/// # None,
74+
/// # None,
75+
/// # None,
76+
/// # SessionType::Hmac,
77+
/// # SymmetricDefinition::AES_256_CFB,
78+
/// # HashingAlgorithm::Sha256,
79+
/// # )
80+
/// # .expect("Failed to create session")
81+
/// # .expect("Received invalid handle");
82+
/// # let (session_attributes, session_attributes_mask) = SessionAttributes::builder()
83+
/// # .with_decrypt(true)
84+
/// # .with_encrypt(true)
85+
/// # .build();
86+
/// # context.tr_sess_set_attributes(session, session_attributes, session_attributes_mask)
87+
/// # .expect("Failed to set attributes on session");
88+
/// # context.set_sessions((Some(session), None, None));
89+
/// #
90+
/// # let nv_index = NvIndexTpmHandle::new(0x01500401)
91+
/// # .expect("Failed to create NV index tpm handle");
92+
/// #
93+
/// # // Create NV index attributes
94+
/// # let owner_nv_index_attributes = NvIndexAttributes::builder()
95+
/// # .with_owner_write(true)
96+
/// # .with_owner_read(true)
97+
/// # .build()
98+
/// # .expect("Failed to create owner nv index attributes");
99+
/// #
100+
/// # // Create owner nv public.
101+
/// # let owner_nv_public = NvPublic::builder()
102+
/// # .with_nv_index(nv_index)
103+
/// # .with_index_name_algorithm(HashingAlgorithm::Sha256)
104+
/// # .with_index_attributes(owner_nv_index_attributes)
105+
/// # .with_data_area_size(32)
106+
/// # .build()
107+
/// # .expect("Failed to build NvPublic for owner");
108+
/// #
109+
/// # // Define the NV space.
110+
/// # let nv_index_handle = context
111+
/// # .nv_define_space(Provision::Owner, None, owner_nv_public)
112+
/// # .expect("Call to nv_define_space failed");
113+
///
114+
/// // Get the name using tr_get_name
115+
/// let tr_get_name_result = context.tr_get_name(nv_index_handle.into());
116+
///
117+
/// // Get the name from the NV by calling nv_read_public
118+
/// let nv_read_public_result = context.nv_read_public(nv_index_handle);
119+
/// #
120+
/// # context
121+
/// # .nv_undefine_space(Provision::Owner, nv_index_handle)
122+
/// # .expect("Call to nv_undefine_space failed");
123+
/// #
124+
/// // Process result by comparing the names
125+
/// let (_public_area, expected_name) = nv_read_public_result.expect("Call to nv_read_public failed");
126+
/// let actual_name = tr_get_name_result.expect("Call to tr_get_name failed");
127+
/// assert_eq!(expected_name, actual_name);
128+
/// ```
31129
pub fn tr_get_name(&mut self, object_handle: ObjectHandle) -> Result<Name> {
32130
let mut name_ptr = null_mut();
33131
ReturnCode::ensure_success(
@@ -40,6 +138,103 @@ impl Context {
40138
}
41139

42140
/// Used to construct an esys object from the resources inside the TPM.
141+
///
142+
/// # Arguments
143+
/// * `tpm_handle` - The TPM handle that references the TPM object for which
144+
/// the ESYS object is being created.
145+
///
146+
/// # Returns
147+
/// A handle to the ESYS object that was created from a TPM resource.
148+
///
149+
/// # Example
150+
/// ```rust
151+
/// # use tss_esapi::{
152+
/// # Context, TctiNameConf, attributes::{SessionAttributes, NvIndexAttributes},
153+
/// # constants::SessionType,
154+
/// # interface_types::{algorithm::HashingAlgorithm, resource_handles::Provision},
155+
/// # structures::{SymmetricDefinition, NvPublic},
156+
/// # };
157+
/// use tss_esapi::{
158+
/// handles::NvIndexTpmHandle,
159+
/// };
160+
/// # // Create context
161+
/// # let mut context =
162+
/// # Context::new(
163+
/// # TctiNameConf::from_environment_variable().expect("Failed to get TCTI"),
164+
/// # ).expect("Failed to create Context");
165+
/// #
166+
/// # let session = context
167+
/// # .start_auth_session(
168+
/// # None,
169+
/// # None,
170+
/// # None,
171+
/// # SessionType::Hmac,
172+
/// # SymmetricDefinition::AES_256_CFB,
173+
/// # HashingAlgorithm::Sha256,
174+
/// # )
175+
/// # .expect("Failed to create session")
176+
/// # .expect("Received invalid handle");
177+
/// # let (session_attributes, session_attributes_mask) = SessionAttributes::builder()
178+
/// # .with_decrypt(true)
179+
/// # .with_encrypt(true)
180+
/// # .build();
181+
/// # context.tr_sess_set_attributes(session, session_attributes, session_attributes_mask)
182+
/// # .expect("Failed to set attributes on session");
183+
/// # context.set_sessions((Some(session), None, None));
184+
/// #
185+
/// let nv_index = NvIndexTpmHandle::new(0x01500402)
186+
/// .expect("Failed to create NV index tpm handle");
187+
/// #
188+
/// # // Create NV index attributes
189+
/// # let owner_nv_index_attributes = NvIndexAttributes::builder()
190+
/// # .with_owner_write(true)
191+
/// # .with_owner_read(true)
192+
/// # .build()
193+
/// # .expect("Failed to create owner nv index attributes");
194+
/// #
195+
/// # // Create owner nv public.
196+
/// # let owner_nv_public = NvPublic::builder()
197+
/// # .with_nv_index(nv_index)
198+
/// # .with_index_name_algorithm(HashingAlgorithm::Sha256)
199+
/// # .with_index_attributes(owner_nv_index_attributes)
200+
/// # .with_data_area_size(32)
201+
/// # .build()
202+
/// # .expect("Failed to build NvPublic for owner");
203+
/// #
204+
/// # // Define the NV space.
205+
/// # let nv_index_handle = context
206+
/// # .nv_define_space(Provision::Owner, None, owner_nv_public)
207+
/// # .expect("Call to nv_define_space failed");
208+
/// #
209+
/// # // Retrieve the name of the NV space.
210+
/// # let nv_read_public_result = context.nv_read_public(nv_index_handle);
211+
/// #
212+
/// # // Close the handle (remove all the metadata).
213+
/// # let mut handle_to_be_closed = nv_index_handle.into();
214+
/// # let tr_close_result = context
215+
/// # .tr_close(&mut handle_to_be_closed);
216+
/// #
217+
/// // Call function without session (session can be provided in order to
218+
/// // verify that the public data read actually originates from this TPM).
219+
/// let retrieved_handle = context.execute_without_session(|ctx| {
220+
/// ctx.tr_from_tpm_public(nv_index.into())
221+
/// })
222+
/// .expect("Call to tr_from_tpm_public failed.");
223+
/// #
224+
/// # // Use the retrieved handle to get the name of the object.
225+
/// # let tr_get_name_result = context
226+
/// # .tr_get_name(retrieved_handle);
227+
/// #
228+
/// # context
229+
/// # .nv_undefine_space(Provision::Owner, retrieved_handle.into())
230+
/// # .expect("Call to nv_undefine_space failed");
231+
/// #
232+
/// # // Process results.
233+
/// # tr_close_result.expect("Call to tr_close_result failed");
234+
/// # let (_, expected_name) = nv_read_public_result.expect("Call to nv_read_public failed");
235+
/// # let actual_name = tr_get_name_result.expect("Call to tr_get_name failed");
236+
/// # assert_eq!(expected_name, actual_name);
237+
/// ```
43238
pub fn tr_from_tpm_public(&mut self, tpm_handle: TpmHandle) -> Result<ObjectHandle> {
44239
let mut object = ObjectHandle::None.into();
45240
ReturnCode::ensure_success(
@@ -71,6 +266,92 @@ impl Context {
71266
/// Instructs the ESAPI to release the metadata and resources allocated for a specific ObjectHandle.
72267
///
73268
/// This is useful for cleaning up handles for which the context cannot be flushed.
269+
///
270+
/// # Arguments
271+
/// * object_handle`- An [ObjectHandle] referring to an object for which all metadata and
272+
/// resources is going to be released.
273+
///
274+
/// # Example
275+
/// ```rust
276+
/// # use tss_esapi::{
277+
/// # Context, TctiNameConf, attributes::{SessionAttributes, NvIndexAttributes},
278+
/// # constants::SessionType, handles::NvIndexTpmHandle,
279+
/// # interface_types::{algorithm::HashingAlgorithm, resource_handles::Provision},
280+
/// # structures::{SymmetricDefinition, NvPublic},
281+
/// # };
282+
/// # // Create context
283+
/// # let mut context =
284+
/// # Context::new(
285+
/// # TctiNameConf::from_environment_variable().expect("Failed to get TCTI"),
286+
/// # ).expect("Failed to create Context");
287+
/// #
288+
/// # let session = context
289+
/// # .start_auth_session(
290+
/// # None,
291+
/// # None,
292+
/// # None,
293+
/// # SessionType::Hmac,
294+
/// # SymmetricDefinition::AES_256_CFB,
295+
/// # HashingAlgorithm::Sha256,
296+
/// # )
297+
/// # .expect("Failed to create session")
298+
/// # .expect("Received invalid handle");
299+
/// # let (session_attributes, session_attributes_mask) = SessionAttributes::builder()
300+
/// # .with_decrypt(true)
301+
/// # .with_encrypt(true)
302+
/// # .build();
303+
/// # context.tr_sess_set_attributes(session, session_attributes, session_attributes_mask)
304+
/// # .expect("Failed to set attributes on session");
305+
/// # context.set_sessions((Some(session), None, None));
306+
/// #
307+
/// let nv_index = NvIndexTpmHandle::new(0x01500403)
308+
/// .expect("Failed to create NV index tpm handle");
309+
/// #
310+
/// # // Create NV index attributes
311+
/// # let owner_nv_index_attributes = NvIndexAttributes::builder()
312+
/// # .with_owner_write(true)
313+
/// # .with_owner_read(true)
314+
/// # .build()
315+
/// # .expect("Failed to create owner nv index attributes");
316+
/// #
317+
/// # // Create owner nv public.
318+
/// # let owner_nv_public = NvPublic::builder()
319+
/// # .with_nv_index(nv_index)
320+
/// # .with_index_name_algorithm(HashingAlgorithm::Sha256)
321+
/// # .with_index_attributes(owner_nv_index_attributes)
322+
/// # .with_data_area_size(32)
323+
/// # .build()
324+
/// # .expect("Failed to build NvPublic for owner");
325+
/// #
326+
/// # // Define the NV space.
327+
/// # let nv_index_handle = context
328+
/// # .nv_define_space(Provision::Owner, None, owner_nv_public)
329+
/// # .expect("Call to nv_define_space failed");
330+
/// #
331+
/// # // Close the handle (remove all the metadata).
332+
/// # let mut handle_to_be_closed = nv_index_handle.into();
333+
/// let tr_close_result = context
334+
/// .tr_close(&mut handle_to_be_closed);
335+
/// #
336+
/// # // Use the retrieved handle to get the name of the object.
337+
/// # let tr_get_name_result = context
338+
/// # .tr_get_name(nv_index_handle.into());
339+
/// #
340+
/// # // Call function without session (session can be provided in order to
341+
/// # // verify that the public data read actually originates from this TPM).
342+
/// # let retrieved_handle = context.execute_without_session(|ctx| {
343+
/// # ctx.tr_from_tpm_public(nv_index.into())
344+
/// # })
345+
/// # .expect("Call to tr_from_tpm_public failed.");
346+
/// #
347+
/// # context
348+
/// # .nv_undefine_space(Provision::Owner, retrieved_handle.into())
349+
/// # .expect("Call to nv_undefine_space failed");
350+
/// #
351+
/// // Process results.
352+
/// tr_close_result.expect("Call to tr_close failed.");
353+
/// # tr_get_name_result.expect_err("Calling tr_get_name with invalid handle did not result in an error.");
354+
/// ```
74355
pub fn tr_close(&mut self, object_handle: &mut ObjectHandle) -> Result<()> {
75356
let mut rsrc_handle = object_handle.try_into_not_none()?;
76357
ReturnCode::ensure_success(

‎tss-esapi/src/context/tpm_commands/non_volatile_storage.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -614,7 +614,7 @@ impl Context {
614614
/// # .expect("Failed to set attributes on session");
615615
/// # context.set_sessions((Some(session), None, None));
616616
/// #
617-
/// # let nv_index = NvIndexTpmHandle::new(0x01500025)
617+
/// # let nv_index = NvIndexTpmHandle::new(0x01500027)
618618
/// # .expect("Failed to create NV index tpm handle");
619619
/// #
620620
/// # // Create NV index attributes

‎tss-esapi/tests/integration_tests/context_tests/general_esys_tr_tests.rs

+4-4
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ mod test_tr_from_tpm_public {
5454
fn test_tr_from_tpm_public_owner_auth() {
5555
let mut context = create_ctx_without_session();
5656

57-
let nv_index_tpm_handle = NvIndexTpmHandle::new(0x01500021).unwrap();
57+
let nv_index_tpm_handle = NvIndexTpmHandle::new(0x01500301).unwrap();
5858

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

125125
#[test]
126126
fn test_tr_from_tpm_public_password_auth() {
127-
let nv_index_tpm_handle = NvIndexTpmHandle::new(0x01500022).unwrap();
127+
let nv_index_tpm_handle = NvIndexTpmHandle::new(0x01500302).unwrap();
128128
remove_nv_index_handle_from_tpm(nv_index_tpm_handle, Provision::Owner);
129129

130130
let mut context = create_ctx_without_session();
@@ -226,7 +226,7 @@ mod test_tr_from_tpm_public {
226226

227227
#[test]
228228
fn read_from_retrieved_handle_using_password_authorization() {
229-
let nv_index_tpm_handle = NvIndexTpmHandle::new(0x01500023).unwrap();
229+
let nv_index_tpm_handle = NvIndexTpmHandle::new(0x01500303).unwrap();
230230

231231
remove_nv_index_handle_from_tpm(nv_index_tpm_handle, Provision::Owner);
232232

@@ -381,7 +381,7 @@ mod test_tr_from_tpm_public {
381381
fn test_tr_get_tpm_handle() {
382382
use tss_esapi::handles::TpmHandle;
383383

384-
let nv_index_tpm_handle = NvIndexTpmHandle::new(0x01500024).unwrap();
384+
let nv_index_tpm_handle = NvIndexTpmHandle::new(0x01500304).unwrap();
385385
remove_nv_index_handle_from_tpm(nv_index_tpm_handle, Provision::Owner);
386386

387387
let mut context = create_ctx_without_session();

0 commit comments

Comments
 (0)