Trait crypto_secretbox::AeadCore
source · pub trait AeadCore {
type NonceSize: ArrayLength<u8>;
type TagSize: ArrayLength<u8>;
type CiphertextOverhead: ArrayLength<u8> + Unsigned;
// Provided method
fn generate_nonce(
rng: impl CryptoRng + RngCore,
) -> GenericArray<u8, Self::NonceSize>
where GenericArray<u8, Self::NonceSize>: Default { ... }
}
Expand description
Authenticated Encryption with Associated Data (AEAD) algorithm core trait.
Defines nonce, tag, and overhead sizes that are consumed by various other
Aead*
traits.
Required Associated Types§
sourcetype NonceSize: ArrayLength<u8>
type NonceSize: ArrayLength<u8>
The length of a nonce.
sourcetype TagSize: ArrayLength<u8>
type TagSize: ArrayLength<u8>
The maximum length of the nonce.
sourcetype CiphertextOverhead: ArrayLength<u8> + Unsigned
type CiphertextOverhead: ArrayLength<u8> + Unsigned
The upper bound amount of additional space required to support a ciphertext vs. a plaintext.
Provided Methods§
sourcefn generate_nonce(
rng: impl CryptoRng + RngCore,
) -> GenericArray<u8, Self::NonceSize>
fn generate_nonce( rng: impl CryptoRng + RngCore, ) -> GenericArray<u8, Self::NonceSize>
Generate a random nonce for this AEAD algorithm.
AEAD algorithms accept a parameter to encryption/decryption called a “nonce” which must be unique every time encryption is performed and never repeated for the same key. The nonce is often prepended to the ciphertext. The nonce used to produce a given ciphertext must be passed to the decryption function in order for it to decrypt correctly.
Nonces don’t necessarily have to be random, but it is one strategy which is implemented by this function.
§⚠️Security Warning
AEAD algorithms often fail catastrophically if nonces are ever repeated (with SIV modes being an exception).
Using random nonces runs the risk of repeating them unless the nonce
size is particularly large (e.g. 192-bit extended nonces used by the
XChaCha20Poly1305
and XSalsa20Poly1305
constructions.
NIST SP 800-38D recommends the following:
The total number of invocations of the authenticated encryption function shall not exceed 2^32, including all IV lengths and all instances of the authenticated encryption function with the given key.
Following this guideline, only 4,294,967,296 messages with random nonces can be encrypted under a given key. While this bound is high, it’s possible to encounter in practice, and systems which might reach it should consider alternatives to purely random nonces, like a counter or a combination of a random nonce + counter.
See the [stream
] module for a ready-made implementation of the latter.