Skip to content

Commit feafd12

Browse files
SuperhepperSuperhepper
committed
Adds proper documentation for rsa_encrypt and rsa_decrypt.
Signed-off-by: Jesper Brynolf <jesper.brynolf@gmail.com>
1 parent d4506ca commit feafd12

File tree

2 files changed

+246
-0
lines changed

2 files changed

+246
-0
lines changed

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

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,127 @@ use std::ptr::null_mut;
1313

1414
impl Context {
1515
/// Perform an asymmetric RSA encryption.
16+
///
17+
/// # Details
18+
/// *From the specification*
19+
/// > This command performs RSA encryption using the indicated padding scheme
20+
/// > according to IETF [RFC 8017](https://www.rfc-editor.org/rfc/rfc8017).
21+
///
22+
/// # Arguments
23+
/// * `key_handle` - A [KeyHandle] to to public portion of RSA key to use for encryption.
24+
/// * `message` - The message to be encrypted.
25+
/// * `in_scheme` - The padding scheme to use if scheme associated with
26+
/// the `key_handle` is [RsaDecryptionScheme::Null].
27+
/// * `label` - A label whose association with the message is to be verified.
28+
///
29+
/// # Returns
30+
/// The encrypted output.
31+
///
32+
/// # Example
33+
///
34+
/// ```rust
35+
/// # use tss_esapi::{
36+
/// # Context, TctiNameConf,
37+
/// # attributes::{SessionAttributesBuilder, ObjectAttributesBuilder},
38+
/// # constants::SessionType,
39+
/// # interface_types::{
40+
/// # algorithm::{
41+
/// # HashingAlgorithm, PublicAlgorithm, RsaDecryptAlgorithm,
42+
/// # },
43+
/// # key_bits::RsaKeyBits,
44+
/// # reserved_handles::Hierarchy,
45+
/// # },
46+
/// # structures::{
47+
/// # Auth, Data, RsaScheme, PublicBuilder, PublicRsaParametersBuilder, PublicKeyRsa,
48+
/// # RsaDecryptionScheme, HashScheme, SymmetricDefinition, RsaExponent,
49+
/// # },
50+
/// # };
51+
/// # use std::{env, str::FromStr, convert::TryFrom};
52+
/// # // Create context
53+
/// # let mut context =
54+
/// # Context::new(
55+
/// # TctiNameConf::from_environment_variable().expect("Failed to get TCTI"),
56+
/// # ).expect("Failed to create Context");
57+
/// #
58+
/// # let session = context
59+
/// # .start_auth_session(
60+
/// # None,
61+
/// # None,
62+
/// # None,
63+
/// # SessionType::Hmac,
64+
/// # SymmetricDefinition::AES_256_CFB,
65+
/// # tss_esapi::interface_types::algorithm::HashingAlgorithm::Sha256,
66+
/// # )
67+
/// # .expect("Failed to create session")
68+
/// # .expect("Received invalid handle");
69+
/// # let (session_attributes, session_attributes_mask) = SessionAttributesBuilder::new()
70+
/// # .with_decrypt(true)
71+
/// # .with_encrypt(true)
72+
/// # .build();
73+
/// # context.tr_sess_set_attributes(session, session_attributes, session_attributes_mask)
74+
/// # .expect("Failed to set attributes on session");
75+
/// # context.set_sessions((Some(session), None, None));
76+
/// # let mut random_digest = vec![0u8; 16];
77+
/// # getrandom::getrandom(&mut random_digest).unwrap();
78+
/// # let key_auth = Auth::from_bytes(random_digest.as_slice()).unwrap();
79+
/// #
80+
/// # let object_attributes = ObjectAttributesBuilder::new()
81+
/// # .with_fixed_tpm(true)
82+
/// # .with_fixed_parent(true)
83+
/// # .with_sensitive_data_origin(true)
84+
/// # .with_user_with_auth(true)
85+
/// # .with_decrypt(true)
86+
/// # .with_sign_encrypt(true)
87+
/// # .with_restricted(false)
88+
/// # .build()
89+
/// # .expect("Should be able to build object attributes when the attributes are not conflicting.");
90+
/// #
91+
/// # let key_pub = PublicBuilder::new()
92+
/// # .with_public_algorithm(PublicAlgorithm::Rsa)
93+
/// # .with_name_hashing_algorithm(HashingAlgorithm::Sha256)
94+
/// # .with_object_attributes(object_attributes)
95+
/// # .with_rsa_parameters(
96+
/// # PublicRsaParametersBuilder::new()
97+
/// # .with_scheme(RsaScheme::Null)
98+
/// # .with_key_bits(RsaKeyBits::Rsa2048)
99+
/// # .with_exponent(RsaExponent::default())
100+
/// # .with_is_signing_key(true)
101+
/// # .with_is_decryption_key(true)
102+
/// # .with_restricted(false)
103+
/// # .build()
104+
/// # .expect("Should be possible to build valid RSA parameters")
105+
/// # )
106+
/// # .with_rsa_unique_identifier(PublicKeyRsa::default())
107+
/// # .build()
108+
/// # .expect("Should be possible to build a valid Public object.");
109+
/// #
110+
/// # let key_handle = context
111+
/// # .create_primary(
112+
/// # Hierarchy::Owner,
113+
/// # key_pub,
114+
/// # None,
115+
/// # None,
116+
/// # None,
117+
/// # None,
118+
/// # )
119+
/// # .expect("Should be possible to create primary key from using valid Public object.")
120+
/// # .key_handle;
121+
/// // Because the key was created with RsaScheme::Null it is possible to
122+
/// // provide a scheme for the rsa_encrypt function to use.
123+
/// let scheme =
124+
/// RsaDecryptionScheme::create(RsaDecryptAlgorithm::Oaep, Some(HashingAlgorithm::Sha256))
125+
/// .expect("Failed to create rsa decryption scheme");
126+
/// let plain_text_bytes = vec![1, 2, 3, 4];
127+
/// let message_in = PublicKeyRsa::try_from(plain_text_bytes.clone())
128+
/// .expect("Should be possible to create a PublicKeyRsa object from valid bytes.");
129+
/// let label = Data::default();
130+
/// let cipher_text = context.rsa_encrypt(key_handle, message_in, scheme, label.clone())
131+
/// .expect("Should be possible to call rsa_encrypt using valid arguments.");
132+
/// # let message_out = context.rsa_decrypt(key_handle, cipher_text, scheme, label)
133+
/// # .expect("Should be possible to call rsa_decrypt using valid arguments.");
134+
/// # let decrypted_bytes = message_out.as_bytes();
135+
/// # assert_eq!(plain_text_bytes, decrypted_bytes);
136+
/// ```
16137
pub fn rsa_encrypt(
17138
&mut self,
18139
key_handle: KeyHandle,
@@ -43,6 +164,125 @@ impl Context {
43164
}
44165

45166
/// Perform an asymmetric RSA decryption.
167+
///
168+
/// # Details
169+
/// *From the specification*
170+
/// > This command performs RSA decryption using the indicated padding scheme according to IETF RFC
171+
/// > 8017 ((PKCS#1).
172+
///
173+
/// # Arguments
174+
/// * `key_handle` - A [KeyHandle] of the RSA key to use for decryption.
175+
/// * `cipher_text` - The cipher text to be decrypted.
176+
/// * `in_scheme` - The padding scheme to use if scheme associated with
177+
/// the `key_handle` is [RsaDecryptionScheme::Null].
178+
/// * `label` - A label whose association with the message is to be verified.
179+
///
180+
/// # Returns
181+
/// The decrypted output.
182+
///
183+
/// # Example
184+
///
185+
/// ```rust
186+
/// # use tss_esapi::{
187+
/// # Context, TctiNameConf,
188+
/// # attributes::{SessionAttributesBuilder, ObjectAttributesBuilder},
189+
/// # constants::SessionType,
190+
/// # interface_types::{
191+
/// # algorithm::{
192+
/// # HashingAlgorithm, PublicAlgorithm, RsaDecryptAlgorithm,
193+
/// # },
194+
/// # key_bits::RsaKeyBits,
195+
/// # reserved_handles::Hierarchy,
196+
/// # },
197+
/// # structures::{
198+
/// # Auth, Data, RsaScheme, PublicBuilder, PublicRsaParametersBuilder, PublicKeyRsa,
199+
/// # RsaDecryptionScheme, HashScheme, SymmetricDefinition, RsaExponent,
200+
/// # },
201+
/// # };
202+
/// # use std::{env, str::FromStr, convert::TryFrom};
203+
/// # // Create context
204+
/// # let mut context =
205+
/// # Context::new(
206+
/// # TctiNameConf::from_environment_variable().expect("Failed to get TCTI"),
207+
/// # ).expect("Failed to create Context");
208+
/// #
209+
/// # let session = context
210+
/// # .start_auth_session(
211+
/// # None,
212+
/// # None,
213+
/// # None,
214+
/// # SessionType::Hmac,
215+
/// # SymmetricDefinition::AES_256_CFB,
216+
/// # tss_esapi::interface_types::algorithm::HashingAlgorithm::Sha256,
217+
/// # )
218+
/// # .expect("Failed to create session")
219+
/// # .expect("Received invalid handle");
220+
/// # let (session_attributes, session_attributes_mask) = SessionAttributesBuilder::new()
221+
/// # .with_decrypt(true)
222+
/// # .with_encrypt(true)
223+
/// # .build();
224+
/// # context.tr_sess_set_attributes(session, session_attributes, session_attributes_mask)
225+
/// # .expect("Failed to set attributes on session");
226+
/// # context.set_sessions((Some(session), None, None));
227+
/// # let mut random_digest = vec![0u8; 16];
228+
/// # getrandom::getrandom(&mut random_digest).unwrap();
229+
/// # let key_auth = Auth::from_bytes(random_digest.as_slice()).unwrap();
230+
/// #
231+
/// # let object_attributes = ObjectAttributesBuilder::new()
232+
/// # .with_fixed_tpm(true)
233+
/// # .with_fixed_parent(true)
234+
/// # .with_sensitive_data_origin(true)
235+
/// # .with_user_with_auth(true)
236+
/// # .with_decrypt(true)
237+
/// # .with_sign_encrypt(true)
238+
/// # .with_restricted(false)
239+
/// # .build()
240+
/// # .expect("Should be able to build object attributes when the attributes are not conflicting.");
241+
/// #
242+
/// # let key_pub = PublicBuilder::new()
243+
/// # .with_public_algorithm(PublicAlgorithm::Rsa)
244+
/// # .with_name_hashing_algorithm(HashingAlgorithm::Sha256)
245+
/// # .with_object_attributes(object_attributes)
246+
/// # .with_rsa_parameters(
247+
/// # PublicRsaParametersBuilder::new()
248+
/// # .with_scheme(RsaScheme::Null)
249+
/// # .with_key_bits(RsaKeyBits::Rsa2048)
250+
/// # .with_exponent(RsaExponent::default())
251+
/// # .with_is_signing_key(true)
252+
/// # .with_is_decryption_key(true)
253+
/// # .with_restricted(false)
254+
/// # .build()
255+
/// # .expect("Should be possible to build valid RSA parameters")
256+
/// # )
257+
/// # .with_rsa_unique_identifier(PublicKeyRsa::default())
258+
/// # .build()
259+
/// # .expect("Should be possible to build a valid Public object.");
260+
/// #
261+
/// # let key_handle = context
262+
/// # .create_primary(
263+
/// # Hierarchy::Owner,
264+
/// # key_pub,
265+
/// # None,
266+
/// # None,
267+
/// # None,
268+
/// # None,
269+
/// # )
270+
/// # .expect("Should be possible to create primary key from using valid Public object.")
271+
/// # .key_handle;
272+
/// # let scheme =
273+
/// # RsaDecryptionScheme::create(RsaDecryptAlgorithm::RsaEs, None)
274+
/// # .expect("Failed to create rsa decryption scheme");
275+
/// # let plain_text_bytes = vec![4, 3, 2, 1, 0];
276+
/// # let message_in = PublicKeyRsa::try_from(plain_text_bytes.clone())
277+
/// # .expect("Should be possible to create a PublicKeyRsa object from valid bytes.");
278+
/// # let label = Data::default();
279+
/// # let cipher_text = context.rsa_encrypt(key_handle, message_in, scheme, label.clone())
280+
/// # .expect("Should be possible to call rsa_encrypt using valid arguments.");
281+
/// let message_out = context.rsa_decrypt(key_handle, cipher_text, scheme, label)
282+
/// .expect("Should be possible to call rsa_decrypt using valid arguments.");
283+
/// let decrypted_bytes = message_out.as_bytes();
284+
/// # assert_eq!(plain_text_bytes, decrypted_bytes);
285+
/// ```
46286
pub fn rsa_decrypt(
47287
&mut self,
48288
key_handle: KeyHandle,

‎tss-esapi/src/lib.rs‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,12 @@
9292
//! controlled through environment variables as explained
9393
//! [here](https://github.com/tpm2-software/tpm2-tss/blob/main/doc/logging.md#runtime-log-level).
9494
//!
95+
//! # Code examples
96+
//! The code examples in this documentation usually only showing a small part of all
97+
//! the steps that are necessary in order to make things work. For the most part it
98+
//! only shows the point of interest e.g. the code related to a context method call. It
99+
//! is therefore recommended to view the code for the whole example by looking at the
100+
//! source code or view the examples in our repository.
95101
96102
mod context;
97103

0 commit comments

Comments
 (0)