Trait aes_gcm::AeadCore

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 { ... }
}

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

type NonceSize: ArrayLength<u8>

The length of a nonce.

type TagSize: ArrayLength<u8>

The maximum length of the nonce.

type CiphertextOverhead: ArrayLength<u8> + Unsigned

The upper bound amount of additional space required to support a ciphertext vs. a plaintext.

Provided Methods

fn generate_nonce( rng: impl CryptoRng + RngCore, ) -> GenericArray<u8, Self::NonceSize>

where GenericArray<u8, Self::NonceSize>: Default,

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.

Object Safety

This trait is not object safe.

Implementors

impl<Aes, NonceSize, TagSize> AeadCore for AesGcm<Aes, NonceSize, TagSize>

where NonceSize: ArrayLength<u8>, TagSize: TagSize,

type NonceSize = NonceSize

type TagSize = TagSize

type CiphertextOverhead = UTerm