diff --git a/INTRODUCTION.md b/INTRODUCTION.md index a6cc415..13d816b 100644 --- a/INTRODUCTION.md +++ b/INTRODUCTION.md @@ -123,7 +123,7 @@ While the `KeyMaterial` is fundamentally just a buffer of bytes, it tracks many The `KeyMaterial` object is used consistently across the library and any functions that manipulate a key material object will properly update the metadata to track any changes made to the key's entropy or security strength. For example, a `KeyMaterial512{ key_type: MACKey, security_strength: _256bit}` will have its security strength downgraded to 128 bit if you pass it through a SHA256-based KDF, indicating that it is no longer sufficient to generate a full-strength AES256 or ML-DSA-87. -Of course, there will always be things developers need to do that the library did not provide a utility function for, for example, you may actually need an all-zero MACKey in order to implement certain standardized MAC algorithms. To the end, the library will allow you to, for example, force a key type to any full-entropy key type and security strength, or even get a direct immutable or mutable reference to the underlying buffer via `.ref_to_bytes()` and `mut_ref_to_bytes()`, but only with use of the `allow_hazardous_operations` flag: +Of course, there will always be things developers need to do that the library did not provide a utility function for, for example, you may actually need an all-zero MACKey in order to implement certain standardized MAC algorithms. To the end, the library will allow you to, for example, force a key type to any full-entropy key type and security strength, or even get a direct immutable or mutable reference to the underlying buffer via `.ref_to_bytes()` and `ref_to_bytes_mut()`, but only with use of the `allow_hazardous_operations` flag: ```rust key.allow_hazardous_operations(); @@ -202,4 +202,4 @@ As this is an alpha release, we're eagerly looking for feedback from the communi You can reach us at Sincerely, -Mike Ounsworth (lead maintainer of BC-Rust), on behalf of the Legion of the Bouncy Castle and the entire Bouncy Castle community \ No newline at end of file +Mike Ounsworth (lead maintainer of BC-Rust), on behalf of the Legion of the Bouncy Castle and the entire Bouncy Castle community diff --git a/crypto/core/src/key_material.rs b/crypto/core/src/key_material.rs index 6097413..61f0413 100644 --- a/crypto/core/src/key_material.rs +++ b/crypto/core/src/key_material.rs @@ -112,7 +112,7 @@ pub trait KeyMaterialTrait { /// This requires [KeyMaterialTrait::allow_hazardous_operations] to be set. /// When writing directly to the buffer, you are responsible for setting the key_len and key_type afterwards, /// and you should [KeyMaterialTrait::drop_hazardous_operations]. - fn mut_ref_to_bytes(&mut self) -> Result<&mut [u8], KeyMaterialError>; + fn ref_to_bytes_mut(&mut self) -> Result<&mut [u8], KeyMaterialError>; /// The size of the internal buffer; ie the largest key that this instance can hold. /// Equivalent to the constant param this object was created with. @@ -151,7 +151,7 @@ pub trait KeyMaterialTrait { /// Sets this instance to be able to perform potentially hazardous operations such as /// casting a KeyMaterial of type RawUnknownEntropy or RawLowEntropy into RawFullEntropy or SymmetricCipherKey, - /// or manually setting the key bytes via [KeyMaterialTrait::mut_ref_to_bytes], which then requires you to be responsible + /// or manually setting the key bytes via [KeyMaterialTrait::ref_to_bytes_mut], which then requires you to be responsible /// for setting the key_len and key_type afterwards. /// /// The purpose of the hazardous operations guard is not to prevent the user from accessing their data, @@ -254,7 +254,7 @@ impl KeyMaterial { let mut key = Self::new(); key.allow_hazardous_operations(); - rng.next_bytes_out(&mut key.mut_ref_to_bytes().unwrap()) + rng.next_bytes_out(&mut key.ref_to_bytes_mut().unwrap()) .map_err(|_| KeyMaterialError::GenericError("RNG failed."))?; key.key_len = KEY_LEN; @@ -354,7 +354,7 @@ impl KeyMaterialTrait for KeyMaterial { &self.buf[..self.key_len] } - fn mut_ref_to_bytes(&mut self) -> Result<&mut [u8], KeyMaterialError> { + fn ref_to_bytes_mut(&mut self) -> Result<&mut [u8], KeyMaterialError> { if !self.allow_hazardous_operations { return Err(KeyMaterialError::HazardousOperationNotPermitted); } diff --git a/crypto/core/tests/key_material_tests.rs b/crypto/core/tests/key_material_tests.rs index 95d2b6b..9c65827 100644 --- a/crypto/core/tests/key_material_tests.rs +++ b/crypto/core/tests/key_material_tests.rs @@ -75,7 +75,7 @@ mod test_key_material { assert_eq!(key.capacity(), 32); assert_eq!(key.ref_to_bytes(), &[1u8; 16]); // note: this is also testing that even though the internal buffer is larger than 16 bytes, it slices it down to length. - match key.mut_ref_to_bytes() { + match key.ref_to_bytes_mut() { Ok(_) => { panic!("getting a mut ref should require setting hazardous operations.") } @@ -85,12 +85,12 @@ mod test_key_material { } } key.allow_hazardous_operations(); - assert_eq!(key.mut_ref_to_bytes().unwrap().len(), 32); - assert_eq!(key.mut_ref_to_bytes().unwrap()[..16], [1u8; 16]); - assert_eq!(key.mut_ref_to_bytes().unwrap()[16..], [0u8; 16]); + assert_eq!(key.ref_to_bytes_mut().unwrap().len(), 32); + assert_eq!(key.ref_to_bytes_mut().unwrap()[..16], [1u8; 16]); + assert_eq!(key.ref_to_bytes_mut().unwrap()[16..], [0u8; 16]); // and I can set them - key.mut_ref_to_bytes().unwrap().copy_from_slice(&[2u8; 32]); + key.ref_to_bytes_mut().unwrap().copy_from_slice(&[2u8; 32]); key.set_key_len(32).unwrap(); assert_eq!(key.ref_to_bytes(), &[2u8; 32]); assert_eq!(key.key_len(), 32); @@ -179,7 +179,7 @@ mod test_key_material { // Sanity check: the backing buffer actually holds non-zero key material before it is wiped. // Without this, the post-zeroize assertion below could pass vacuously. key.allow_hazardous_operations(); - assert!(key.mut_ref_to_bytes().unwrap().iter().any(|&b| b != 0)); + assert!(key.ref_to_bytes_mut().unwrap().iter().any(|&b| b != 0)); key.drop_hazardous_operations(); key.zeroize(); @@ -192,7 +192,7 @@ mod test_key_material { // actually overwritten with zeros. // Note: key_len is now 0, so ref_to_bytes() returns an empty slice. key.allow_hazardous_operations(); - let full_buf = key.mut_ref_to_bytes().unwrap(); + let full_buf = key.ref_to_bytes_mut().unwrap(); assert_eq!(full_buf.len(), capacity); assert!(full_buf.iter().all(|&b| b == 0)); key.drop_hazardous_operations(); diff --git a/crypto/hkdf/src/lib.rs b/crypto/hkdf/src/lib.rs index 76b47f0..a6ecc51 100644 --- a/crypto/hkdf/src/lib.rs +++ b/crypto/hkdf/src/lib.rs @@ -397,7 +397,7 @@ impl HKDF { let mut bytes_written: usize = 0; okm.allow_hazardous_operations(); - let out: &mut [u8] = okm.mut_ref_to_bytes()?; + let out: &mut [u8] = okm.ref_to_bytes_mut()?; // Could potentially speed this up by unrolling T(0) and T(1) // We're gonna have to kludge the prk key type to MACKey to make HMAC happy, but we'll set it back to the original value afterwards. @@ -568,9 +568,9 @@ impl HKDF { let output_key_type = self.entropy.get_output_key_type(); // need to do this above self.hmac.do_final_out, which will consume self. - okm.allow_hazardous_operations(); // doing it here to get mut_ref_to_bytes + okm.allow_hazardous_operations(); // doing it here to get ref_to_bytes_mut let bytes_written = - self.hmac.unwrap().do_final_out(&mut okm.mut_ref_to_bytes().unwrap())?; + self.hmac.unwrap().do_final_out(&mut okm.ref_to_bytes_mut().unwrap())?; okm.set_key_len(bytes_written)?; okm.set_key_type(output_key_type)?; if output_key_type <= KeyType::BytesLowEntropy { diff --git a/crypto/rng/src/hash_drbg80090a.rs b/crypto/rng/src/hash_drbg80090a.rs index 75b4177..ffac1db 100644 --- a/crypto/rng/src/hash_drbg80090a.rs +++ b/crypto/rng/src/hash_drbg80090a.rs @@ -145,12 +145,12 @@ impl HashDRBG80090A { seed.set_key_type(KeyType::Seed).unwrap(); match H::HASH { SupportedHash::SHA256 => { - getrandom::fill(&mut seed.mut_ref_to_bytes().unwrap()[..32]).unwrap(); + getrandom::fill(&mut seed.ref_to_bytes_mut().unwrap()[..32]).unwrap(); seed.set_key_len(32).unwrap(); seed.set_security_strength(SecurityStrength::_128bit).unwrap(); } SupportedHash::SHA512 => { - getrandom::fill(&mut seed.mut_ref_to_bytes().unwrap()).unwrap(); + getrandom::fill(&mut seed.ref_to_bytes_mut().unwrap()).unwrap(); seed.set_key_len(64).unwrap(); seed.set_security_strength(SecurityStrength::_256bit).unwrap(); } @@ -463,7 +463,7 @@ impl Sp80090ADrbg for HashDRBG80090A { out: &mut impl KeyMaterialTrait, ) -> Result { out.allow_hazardous_operations(); - let bytes_written = self.generate_out(additional_input, out.mut_ref_to_bytes().unwrap())?; + let bytes_written = self.generate_out(additional_input, out.ref_to_bytes_mut().unwrap())?; out.set_key_len(bytes_written)?; out.set_key_type(KeyType::BytesFullEntropy)?; diff --git a/crypto/sha3/src/sha3.rs b/crypto/sha3/src/sha3.rs index cb22998..21edef3 100644 --- a/crypto/sha3/src/sha3.rs +++ b/crypto/sha3/src/sha3.rs @@ -82,7 +82,7 @@ impl SHA3 { let mut key_type = self.kdf_key_type.clone(); let output_security_strength = self.kdf_security_strength.clone(); output_key.allow_hazardous_operations(); - let bytes_written = self.do_final_out(output_key.mut_ref_to_bytes()?); + let bytes_written = self.do_final_out(output_key.ref_to_bytes_mut()?); output_key.set_key_len(bytes_written)?; // since we've done some computation, the result will not actually be zeroized, even if all input key material was zeroized. diff --git a/crypto/sha3/src/shake.rs b/crypto/sha3/src/shake.rs index 59f3bac..3e64e6c 100644 --- a/crypto/sha3/src/shake.rs +++ b/crypto/sha3/src/shake.rs @@ -113,7 +113,7 @@ impl SHAKE { output_key.allow_hazardous_operations(); let bytes_written = self.squeeze_out( output_key - .mut_ref_to_bytes() + .ref_to_bytes_mut() .expect("We just set .allow_hazardous_operations(), so this should be fine."), ); output_key.set_key_len(bytes_written)?;