Skip to content

Commit 1c30489

Browse files
SuperhepperSuperhepper
committed
Adds proper documentation for rsa_encrypt and rsa_decrypt.
Signed-off-by: Jesper Brynolf <[email protected]>
1 parent 2df045f commit 1c30489

File tree

2 files changed

+250
-0
lines changed

2 files changed

+250
-0
lines changed

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

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,130 @@ 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 according to IETF RFC
20+
/// > 8017.
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
28+
/// verified.
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 = String::from("Plain Text");
127+
/// let plain_text_bytes = plain_text.as_bytes().to_vec();
128+
/// let message_in = PublicKeyRsa::try_from(plain_text_bytes)
129+
/// .expect("Should be possible to create a PublicKeyRsa object from valid bytes.");
130+
/// let label = Data::default();
131+
/// let cipher_text = context.rsa_encrypt(key_handle, message_in, scheme, label.clone())
132+
/// .expect("Should be possible to call rsa_encrypt using valid arguments.");
133+
/// # let message_out = context.rsa_decrypt(key_handle, cipher_text, scheme, label)
134+
/// # .expect("Should be possible to call rsa_decrypt using valid arguments.");
135+
/// # let decrypted_bytes = message_out.as_bytes().to_vec();
136+
/// # let decrypted_text = String::from_utf8(decrypted_bytes)
137+
/// # .expect("Should be possible to turn the decrypted data into an utf-8 string.");
138+
/// # assert_eq!(plain_text, decrypted_text);
139+
/// ```
16140
pub fn rsa_encrypt(
17141
&mut self,
18142
key_handle: KeyHandle,
@@ -43,6 +167,128 @@ impl Context {
43167
}
44168

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

‎tss-esapi/src/lib.rs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,10 @@
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 are just small snippets of all the different steps that are necessary
97+
//! in order to get the examples to actually work so it is recommended to check all the steps
98+
//! in comments in the source code.
9599
96100
mod context;
97101

0 commit comments

Comments
 (0)