[go: up one dir, main page]
aead

Trait AeadCore

Source 
pub trait AeadCore {
    type NonceSize: ArraySize;
    type TagSize: ArraySize;

    const TAG_POSITION: TagPosition;

    // Provided methods
    fn generate_nonce() -> Result<Nonce<Self>, OsError> { ... }
    fn generate_nonce_with_rng<R: CryptoRng + ?Sized>(
        rng: &mut R,
    ) -> Nonce<Self> { ... }
    fn try_generate_nonce_with_rng<R: TryCryptoRng + ?Sized>(
        rng: &mut R,
    ) -> Result<Nonce<Self>, R::Error> { ... }
}
Expand description

Authenticated Encryption with Associated Data (AEAD) algorithm.

Required Associated Constants§

Source

const TAG_POSITION: TagPosition

The AEAD tag position.

Required Associated Types§

Source

type NonceSize: ArraySize

The length of a nonce.

Source

type TagSize: ArraySize

The maximum length of the tag.

Provided Methods§

Source

fn generate_nonce() -> Result<Nonce<Self>, OsError>

Available on crate feature os_rng only.

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 aead-stream crate for a ready-made implementation of the latter.

Source

fn generate_nonce_with_rng<R: CryptoRng + ?Sized>(rng: &mut R) -> Nonce<Self>

Available on crate feature rand_core only.

Generate a random nonce for this AEAD algorithm using the specified CryptoRng.

See AeadCore::generate_nonce documentation for requirements for random nonces.

Source

fn try_generate_nonce_with_rng<R: TryCryptoRng + ?Sized>( rng: &mut R, ) -> Result<Nonce<Self>, R::Error>

Available on crate feature rand_core only.

Generate a random nonce for this AEAD algorithm using the specified TryCryptoRng.

See AeadCore::generate_nonce documentation for requirements for random nonces.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§