Trait aead::Aead

pub trait Aead {
    type NonceSize: ArrayLength<u8>;
    type TagSize: ArrayLength<u8>;
    type CiphertextOverhead: ArrayLength<u8> + Unsigned;
    fn encrypt_in_place_detached(
        &self, 
        nonce: &GenericArray<u8, Self::NonceSize>, 
        associated_data: &[u8], 
        buffer: &mut [u8]
    ) -> Result<GenericArray<u8, Self::TagSize>, Error>;
    fn decrypt_in_place_detached(
        &self, 
        nonce: &GenericArray<u8, Self::NonceSize>, 
        associated_data: &[u8], 
        buffer: &mut [u8], 
        tag: &GenericArray<u8, Self::TagSize>
    ) -> Result<(), Error>;

    fn encrypt<'msg, 'aad>(
        &self, 
        nonce: &GenericArray<u8, Self::NonceSize>, 
        plaintext: impl Into<Payload<'msg, 'aad>>
    ) -> Result<Vec<u8>, Error> { ... }
    fn encrypt_in_place(
        &self, 
        nonce: &GenericArray<u8, Self::NonceSize>, 
        associated_data: &[u8], 
        buffer: &mut impl Buffer
    ) -> Result<(), Error> { ... }
    fn decrypt<'msg, 'aad>(
        &self, 
        nonce: &GenericArray<u8, Self::NonceSize>, 
        ciphertext: impl Into<Payload<'msg, 'aad>>
    ) -> Result<Vec<u8>, Error> { ... }
    fn decrypt_in_place(
        &self, 
        nonce: &GenericArray<u8, Self::NonceSize>, 
        associated_data: &[u8], 
        buffer: &mut impl Buffer
    ) -> Result<(), Error> { ... }
}

Authenticated Encryption with Associated Data (AEAD) algorithm.

This trait is intended for use with stateless AEAD algorithms. The AeadMut trait provides a stateful interface.

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.

Loading content...

Required methods

fn encrypt_in_place_detached(
    &self,
    nonce: &GenericArray<u8, Self::NonceSize>,
    associated_data: &[u8],
    buffer: &mut [u8]
) -> Result<GenericArray<u8, Self::TagSize>, Error>

Encrypt the data in-place, returning the authentication tag

fn decrypt_in_place_detached(
    &self,
    nonce: &GenericArray<u8, Self::NonceSize>,
    associated_data: &[u8],
    buffer: &mut [u8],
    tag: &GenericArray<u8, Self::TagSize>
) -> Result<(), Error>

Decrypt the message in-place, returning an error in the event the provided authentication tag does not match the given ciphertext (i.e. ciphertext is modified/unauthentic)

Loading content...

Provided methods

fn encrypt<'msg, 'aad>(
    &self,
    nonce: &GenericArray<u8, Self::NonceSize>,
    plaintext: impl Into<Payload<'msg, 'aad>>
) -> Result<Vec<u8>, Error>

Encrypt the given plaintext payload, and return the resulting ciphertext as a vector of bytes.

The Payload type can be used to provide Additional Associated Data (AAD) along with the message: this is an optional bytestring which is not encrypted, but is authenticated along with the message. Failure to pass the same AAD that was used during encryption will cause decryption to fail, which is useful if you would like to "bind" the ciphertext to some other identifier, like a digital signature key or other identifier.

If you don't care about AAD and just want to encrypt a plaintext message, &[u8] will automatically be coerced into a Payload:

let plaintext = b"Top secret message, handle with care";
let ciphertext = cipher.encrypt(nonce, plaintext);

The default implementation assumes a postfix tag (ala AES-GCM, AES-GCM-SIV, ChaCha20Poly1305). Aead implementations which do not use a postfix tag will need to override this to correctly assemble the ciphertext message.

fn encrypt_in_place(
    &self,
    nonce: &GenericArray<u8, Self::NonceSize>,
    associated_data: &[u8],
    buffer: &mut impl Buffer
) -> Result<(), Error>

Encrypt the given buffer containing a plaintext message in-place.

The buffer must have sufficient capacity to store the ciphertext message, which will always be larger than the original plaintext. The exact size needed is cipher-dependent, but generally includes the size of an authentication tag.

Returns an error if the buffer has insufficient capacity to store the resulting ciphertext message.

fn decrypt<'msg, 'aad>(
    &self,
    nonce: &GenericArray<u8, Self::NonceSize>,
    ciphertext: impl Into<Payload<'msg, 'aad>>
) -> Result<Vec<u8>, Error>

Decrypt the given ciphertext slice, and return the resulting plaintext as a vector of bytes.

See notes on Aead::encrypt() about allowable message payloads and Associated Additional Data (AAD).

If you have no AAD, you can call this as follows:

let ciphertext = b"...";
let plaintext = cipher.decrypt(nonce, ciphertext)?;

The default implementation assumes a postfix tag (ala AES-GCM, AES-GCM-SIV, ChaCha20Poly1305). Aead implementations which do not use a postfix tag will need to override this to correctly parse the ciphertext message.

fn decrypt_in_place(
    &self,
    nonce: &GenericArray<u8, Self::NonceSize>,
    associated_data: &[u8],
    buffer: &mut impl Buffer
) -> Result<(), Error>

Decrypt the message in-place, returning an error in the event the provided authentication tag does not match the given ciphertext.

The buffer will be truncated to the length of the original plaintext message upon success.

Loading content...

Implementors

Loading content...