diff --git a/ciphers/src/hash_domain.rs b/ciphers/src/hash_domain.rs index ce96013..2b05ffe 100644 --- a/ciphers/src/hash_domain.rs +++ b/ciphers/src/hash_domain.rs @@ -11,7 +11,7 @@ pub use hash::KEY_LEN; /// # use rosenpass_ciphers::hash_domain::{HashDomain, HashDomainNamespace, SecretHashDomain, SecretHashDomainNamespace}; /// use rosenpass_secret_memory::Secret; /// # rosenpass_secret_memory::secret_policy_use_only_malloc_secrets(); -/// +/// /// const PROTOCOL_IDENTIFIER: &str = "MY_PROTOCOL:IDENTIFIER"; /// # fn do_doc_test() -> Result<(), Box> { /// // create use once hash domain for the protocol identifier @@ -30,11 +30,11 @@ pub use hash::KEY_LEN; /// // derive a new key based on the secret key /// let new_key_identifier = "my_new_key_identifier".as_bytes(); /// let new_key = secret_hash_domain.mix(new_key_identifier)?.into_secret(); -/// +/// /// # Ok(()) /// # } /// # do_doc_test().unwrap(); -/// +/// ///``` /// @@ -49,7 +49,7 @@ pub struct HashDomain([u8; KEY_LEN]); /// use [SecretHashDomainNamespace] instead. #[derive(Clone, Debug)] pub struct HashDomainNamespace([u8; KEY_LEN]); -/// A use-once hash domain for a specified key that can be used directly +/// A use-once hash domain for a specified key that can be used directly /// by wrapping it in [Secret]. The key must consist of [KEY_LEN] many bytes. #[derive(Clone, Debug)] pub struct SecretHashDomain(Secret); @@ -59,7 +59,7 @@ pub struct SecretHashDomain(Secret); pub struct SecretHashDomainNamespace(Secret); impl HashDomain { - /// Creates a nw [HashDomain] initialized with a all-zeros key. + /// Creates a nw [HashDomain] initialized with a all-zeros key. pub fn zero() -> Self { Self([0u8; KEY_LEN]) } @@ -74,7 +74,7 @@ impl HashDomain { pub fn turn_secret(self) -> SecretHashDomain { SecretHashDomain(Secret::from_slice(&self.0)) } - + // TODO: Protocol! Use domain separation to ensure that /// Creates a new [HashDomain] by mixing in a new key `v`. Specifically, /// it evaluates [hash::hash] with this HashDomain's key as the key and `v` @@ -97,9 +97,7 @@ impl HashDomain { } } - impl HashDomainNamespace { - /// Creates a new [HashDomain] by mixing in a new key `v`. Specifically, /// it evaluates [hash::hash] with the key of this HashDomainNamespace key as the key and `v` /// as the `data` and uses the result as the key for the new [HashDomain]. @@ -120,10 +118,9 @@ impl HashDomainNamespace { } impl SecretHashDomain { - /// Create a new [SecretHashDomain] with the given key `k` and data `d` by calling /// [hash::hash] with `k` as the `key` and `d` s the `data`, and using the result - /// as the content for the new [SecretHashDomain]. + /// as the content for the new [SecretHashDomain]. /// Both `k` and `d` have to be exactly [KEY_LEN] bytes in length. pub fn invoke_primitive(k: &[u8], d: &[u8]) -> Result { let mut r = SecretHashDomain(Secret::zero()); @@ -173,7 +170,7 @@ impl SecretHashDomain { /// Evaluate [hash::hash] with this [SecretHashDomain]'s data as the `key` and /// `dst` as the `data` and stores the result as the new data for this [SecretHashDomain]. - /// + /// /// It requires that both `v` and `d` consist of exactly [KEY_LEN] many bytes. pub fn into_secret_slice(mut self, v: &[u8], dst: &[u8]) -> Result<()> { hash::hash(v, dst).to(self.0.secret_mut()) @@ -181,7 +178,6 @@ impl SecretHashDomain { } impl SecretHashDomainNamespace { - /// Creates a new [SecretHashDomain] by mixing in a new key `v`. Specifically, /// it evaluates [hash::hash] with the key of this HashDomainNamespace key as the key and `v` /// as the `data` and uses the result as the key for the new [HashDomain]. diff --git a/ciphers/src/lib.rs b/ciphers/src/lib.rs index ada564e..ecb618d 100644 --- a/ciphers/src/lib.rs +++ b/ciphers/src/lib.rs @@ -42,10 +42,10 @@ pub mod hash_domain; /// This crate includes two key encapsulation mechanisms. /// Namely ClassicMceliece460896 (as [StaticKem]) and Kyber512 (as [EphemeralKem]). -/// +/// /// See [rosenpass_oqs::ClassicMceliece460896](rosenpass_oqs::ClassicMceliece460896) /// and [rosenpass_oqs::Kyber512](rosenpass_oqs::Kyber512) for more details on the specific KEMS. -/// +/// pub mod kem { pub use rosenpass_oqs::ClassicMceliece460896 as StaticKem; pub use rosenpass_oqs::Kyber512 as EphemeralKem; diff --git a/ciphers/src/subtle/blake2b.rs b/ciphers/src/subtle/blake2b.rs index 3b5b34b..c29a6e3 100644 --- a/ciphers/src/subtle/blake2b.rs +++ b/ciphers/src/subtle/blake2b.rs @@ -9,7 +9,7 @@ use blake2::Blake2bMac; use rosenpass_to::{ops::copy_slice, with_destination, To}; use rosenpass_util::typenum2const; -/// Specify that the used implementation of BLAKE2b is the MAC version of BLAKE2b +/// Specify that the used implementation of BLAKE2b is the MAC version of BLAKE2b /// with output and key length of 32 bytes (see [Blake2bMac]). type Impl = Blake2bMac; @@ -32,20 +32,20 @@ pub const OUT_MAX: usize = OUT_LEN; /// Hashes the given `data` with the [Blake2bMac] hash function under the given `key`. /// The [KEY_LEN] and [OUT_LEN] are both set to 32 bytes (or 256 bits). -/// +/// /// # Examples -/// +/// ///```rust /// # use rosenpass_ciphers::subtle::blake2b::hash; /// use rosenpass_to::To; -/// let zero_key: [u8; 32] = [0; 32]; +/// let zero_key: [u8; 32] = [0; 32]; /// let data: [u8; 32] = [255; 32]; /// // buffer for the hash output /// let mut hash_data: [u8; 32] = [0u8; 32]; /// /// assert!(hash(&zero_key, &data).to(&mut hash_data).is_ok(), "Hashing has to return OK result"); ///``` -/// +/// #[inline] pub fn hash<'a>(key: &'a [u8], data: &'a [u8]) -> impl To<[u8], anyhow::Result<()>> + 'a { with_destination(|out: &mut [u8]| { diff --git a/ciphers/src/subtle/chacha20poly1305_ietf.rs b/ciphers/src/subtle/chacha20poly1305_ietf.rs index 59f6a5c..b979aff 100644 --- a/ciphers/src/subtle/chacha20poly1305_ietf.rs +++ b/ciphers/src/subtle/chacha20poly1305_ietf.rs @@ -18,7 +18,7 @@ pub const NONCE_LEN: usize = typenum2const! { ::NonceSize /// a length of [KEY_LEN]. The `nonce` slice MUST have a length of [NONCE_LEN]. The last [TAG_LEN] bytes /// written in `ciphertext` are the tag guaranteeing integrity. `ciphertext` MUST have a capacity of /// `plaintext.len()` + [TAG_LEN]. -/// +/// /// # Examples ///```rust /// # use rosenpass_ciphers::subtle::chacha20poly1305_ietf::{encrypt, TAG_LEN, KEY_LEN, NONCE_LEN}; @@ -57,10 +57,10 @@ pub fn encrypt( /// Decrypts a `ciphertext` and verifies the integrity of the `ciphertext` and the additional data /// `ad`. using ChaCha20Poly1305 as implemented in [RustCrypto](https://github.com/RustCrypto/AEADs/tree/master/chacha20poly1305). -/// +/// /// The `key` slice MUST have a length of [KEY_LEN]. The `nonce` slice MUST have a length of /// [NONCE_LEN]. The plaintext buffer must have a capacity of `ciphertext.len()` - [TAG_LEN]. -/// +/// /// # Examples ///```rust /// # use rosenpass_ciphers::subtle::chacha20poly1305_ietf::{decrypt, TAG_LEN, KEY_LEN, NONCE_LEN}; diff --git a/ciphers/src/subtle/chacha20poly1305_ietf_libcrux.rs b/ciphers/src/subtle/chacha20poly1305_ietf_libcrux.rs index 2f6b9f2..ccf9735 100644 --- a/ciphers/src/subtle/chacha20poly1305_ietf_libcrux.rs +++ b/ciphers/src/subtle/chacha20poly1305_ietf_libcrux.rs @@ -65,10 +65,10 @@ pub fn encrypt( /// Decrypts a `ciphertext` and verifies the integrity of the `ciphertext` and the additional data /// `ad`. using ChaCha20Poly1305 as implemented in [libcrux](https://github.com/cryspen/libcrux). -/// +/// /// The `key` slice MUST have a length of [KEY_LEN]. The `nonce` slice MUST have a length of /// [NONCE_LEN]. The plaintext buffer must have a capacity of `ciphertext.len()` - [TAG_LEN]. -/// +/// /// # Examples ///```rust /// # use rosenpass_ciphers::subtle::chacha20poly1305_ietf_libcrux::{decrypt, TAG_LEN, KEY_LEN, NONCE_LEN}; diff --git a/ciphers/src/subtle/incorrect_hmac_blake2b.rs b/ciphers/src/subtle/incorrect_hmac_blake2b.rs index 27c5f0e..0bc72cf 100644 --- a/ciphers/src/subtle/incorrect_hmac_blake2b.rs +++ b/ciphers/src/subtle/incorrect_hmac_blake2b.rs @@ -24,22 +24,22 @@ pub const OUT_MAX: usize = blake2b::OUT_MAX; /// /// This will be replaced, likely by Kekkac at some point soon. /// -/// +/// /// # Examples ///```rust /// # use rosenpass_ciphers::subtle::incorrect_hmac_blake2b::hash; /// use rosenpass_to::To; -/// let key: [u8; 32] = [0; 32]; +/// let key: [u8; 32] = [0; 32]; /// let data: [u8; 32] = [255; 32]; /// // buffer for the hash output /// let mut hash_data: [u8; 32] = [0u8; 32]; /// /// assert!(hash(&key, &data).to(&mut hash_data).is_ok(), "Hashing has to return OK result"); /// # let expected_hash: &[u8] = &[5, 152, 135, 141, 151, 106, 147, 8, 220, 95, 38, 66, 29, 33, 3, -/// 104, 250, 114, 131, 119, 27, 56, 59, 44, 11, 67, 230, 113, 112, 20, 80, 103]; +/// 104, 250, 114, 131, 119, 27, 56, 59, 44, 11, 67, 230, 113, 112, 20, 80, 103]; /// # assert_eq!(hash_data, expected_hash); ///``` -/// +/// #[inline] pub fn hash<'a>(key: &'a [u8], data: &'a [u8]) -> impl To<[u8], anyhow::Result<()>> + 'a { const IPAD: [u8; KEY_LEN] = [0x36u8; KEY_LEN]; diff --git a/ciphers/src/subtle/mod.rs b/ciphers/src/subtle/mod.rs index 0f19e37..179cf9e 100644 --- a/ciphers/src/subtle/mod.rs +++ b/ciphers/src/subtle/mod.rs @@ -10,4 +10,4 @@ pub mod chacha20poly1305_ietf; #[cfg(feature = "experiment_libcrux")] pub mod chacha20poly1305_ietf_libcrux; pub mod incorrect_hmac_blake2b; -pub mod xchacha20poly1305_ietf; \ No newline at end of file +pub mod xchacha20poly1305_ietf;