Crate ascon_aead

Authenticated Encryption and Associated Data (AEAD) with Ascon

Security Notes

This crate has received no security audit. Use at your own risk.

Usage

Simple usage (allocating, no associated data):

use ascon_aead::{Ascon128, Key, Nonce}; // Or `Ascon128a`
use ascon_aead::aead::{Aead, NewAead};

let key = Key::from_slice(b"very secret key.");
let cipher = Ascon128::new(key);

let nonce = Nonce::from_slice(b"unique nonce 012"); // 128-bits; unique per message

let ciphertext = cipher.encrypt(nonce, b"plaintext message".as_ref())
    .expect("encryption failure!"); // NOTE: handle this error to avoid panics!

let plaintext = cipher.decrypt(nonce, ciphertext.as_ref())
    .expect("decryption failure!"); // NOTE: handle this error to avoid panics!

assert_eq!(&plaintext, b"plaintext message");

In-place Usage (eliminates alloc requirement)

Similar to other crates implementing aead interfaces, this crate also offers an optional alloc feature which can be disabled in e.g. microcontroller environments that don’t have a heap. See aead::AeadInPlace for more details.

use ascon_aead::{Ascon128, Key, Nonce}; // Or `Ascon128a`
use ascon_aead::aead::{AeadInPlace, NewAead};
use ascon_aead::aead::heapless::{Vec, consts::U128};

let key = Key::from_slice(b"very secret key.");
let cipher = Ascon128::new(key);

let nonce = Nonce::from_slice(b"unique nonce 012"); // 128-bits; unique per message

let mut buffer: Vec<u8, U128> = Vec::new(); // Buffer needs 16-bytes overhead for authentication tag
buffer.extend_from_slice(b"plaintext message");

// Encrypt `buffer` in-place, replacing the plaintext contents with ciphertext
cipher.encrypt_in_place(nonce, b"", &mut buffer).expect("encryption failure!");

// `buffer` now contains the message ciphertext
assert_ne!(&buffer, b"plaintext message");

// Decrypt `buffer` in-place, replacing its ciphertext context with the original plaintext
cipher.decrypt_in_place(nonce, b"", &mut buffer).expect("decryption failure!");
assert_eq!(&buffer, b"plaintext message");

Re-exports

pub use aead;

Structs

Ascon	Ascon generic over some Parameters
Error	Error type.
Parameters128	Parameters for Ascon-128
Parameters128a	Paramters for Ascon-128a

Traits

AeadCore	Authenticated Encryption with Associated Data (AEAD) algorithm core trait.
AeadInPlace	In-place stateless AEAD trait.
Buffer	In-place encryption/decryption byte buffers.
NewAead	Instantiate either a stateless Aead or stateful AeadMut algorithm.
Parameters	Parameters of an Ascon instance

Type Definitions

Ascon128	Ascon-128
Ascon128a	Ascon-128a
Key	Ascon keys
Nonce	Ascon nonces
Tag	Ascon tags