Module orion::aead

Available on crate feature safe_api only.

Authenticated secret-key encryption.

Use case:

orion::aead can be used to encrypt data in a way that detects if the encrypted data has been tampered with before decrypting it.

An example of this could be sending messages across networks, where confidentiality and authenticity of these messages is required.

About:

• Both one-shot functions and a streaming API are provided.
• The nonce is automatically generated.
• Returns a vector where the first 24 bytes are the nonce and the rest is the authenticated ciphertext with the last 16 bytes being the corresponding Poly1305 tag.
• Uses XChaCha20Poly1305 with no additional data.
• When using seal and open then the separation of tags, nonces and ciphertext are automatically handled.

Parameters:

• plaintext: The data to be encrypted.
• secret_key: The secret key used to encrypt the plaintext.
• ciphertext_with_tag_and_nonce: The data to be decrypted with the first 24 bytes being the nonce and the last 16 bytes being the corresponding Poly1305 tag.

Errors:

An error will be returned if:

• secret_key is not 32 bytes.
• The plaintext is empty.
• ciphertext_with_tag_and_nonce is less than 41 bytes (XCHACHA_NONCESIZE + POLY1305_OUTSIZE + 1).
• The received tag does not match the calculated tag when calling open.
• plaintext.len() + XCHACHA_NONCESIZE + POLY1305_OUTSIZE overflows when calling seal.

Panics:

A panic will occur if:

• More than 2^32-1 * 64 bytes of data are processed.
• Failure to generate random bytes securely.

Security:

• It is critical for security that a given nonce is not re-used with a given key. Should this happen, the security of all data that has been encrypted with that given key is compromised.
• To securely generate a strong key, use SecretKey::default().
• The length of the plaintext is not hidden, only its contents.

Example:

use orion::aead;

let secret_key = aead::SecretKey::default();
let ciphertext = aead::seal(&secret_key, b"Secret message")?;
let decrypted_data = aead::open(&secret_key, &ciphertext)?;

assert_eq!(decrypted_data, b"Secret message");

Modules

• streaming
  Streaming AEAD based on XChaCha20Poly1305.

Structs

• SecretKey
  A type to represent a secret key.

Functions

• open
  Authenticated decryption using XChaCha20Poly1305.
• seal
  Authenticated encryption using XChaCha20Poly1305.