Crate ascon_aead

Crate ascon_aead 

Source
Expand description

§Ascon AEAD

Pure Rust implementation of the lightweight Authenticated Encryption with Associated Data (AEAD) algorithm Ascon-AEAD128.

§Security Notes

No security audits of this crate have ever been performed.

USE AT YOUR OWN RISK!

§Minimum Supported Rust Version

This crate requires Rust 1.85 at a minimum.

§License

Licensed under either of:

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

§Usage

Simple usage (allocating, no associated data):

use ascon_aead::{AsconAead128, AsconAead128Key, AsconAead128Nonce, Key, Nonce};
use ascon_aead::aead::{Aead, KeyInit};

let key = AsconAead128Key::from_slice(b"very secret key.");
let cipher = AsconAead128::new(key);

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

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");

With randomly sampled keys and nonces (requires getrandom feature):

use ascon_aead::AsconAead128;
use ascon_aead::aead::{Aead, AeadCore, KeyInit, OsRng};

let key = AsconAead128::generate_key(&mut OsRng);
let cipher = AsconAead128::new(&key);

// 128 bits; unique per message
let nonce = AsconAead128::generate_nonce(&mut OsRng);

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)

This crate has an optional alloc feature which can be disabled in e.g. microcontroller environments that don’t have a heap.

The AeadInPlace::encrypt_in_place and AeadInPlace::decrypt_in_place methods accept any type that impls the aead::Buffer trait which contains the plaintext for encryption or ciphertext for decryption.

Note that if you enable the heapless feature of this crate, you will receive an impl of aead::Buffer for heapless::Vec (re-exported from the aead crate as aead::heapless::Vec), which can then be passed as the buffer parameter to the in-place encrypt and decrypt methods:

use ascon_aead::{AsconAead128, AsconAead128Key, AsconAead128Nonce, Key, Nonce};
use ascon_aead::aead::{AeadInPlace, KeyInit};
use ascon_aead::aead::heapless::Vec;

let key = AsconAead128Key::from_slice(b"very secret key.");
let cipher = AsconAead128::new(key);

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

// Buffer needs 16-bytes overhead for authentication tag
let mut buffer: Vec<u8, 128> = Vec::new();
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");

Similarly, enabling the arrayvec feature of this crate will provide an impl of aead::Buffer for arrayvec::ArrayVec (re-exported from the aead crate as aead::arrayvec::ArrayVec), and enabling the bytes feature of this crate will provide an impl of aead::Buffer for bytes::BytesMut (re-exported from the aead crate as aead::bytes::BytesMut).

§Truncated Tags

Ascon-AEAD128 also supports truncated tags ranging from 32 to 128 bits. Currently, only byte lengths are supported. Support for truncated tags is available via [TruncatedAsconAEAD128].

use aead::consts::{U5};
use ascon_aead::{TruncatedAsconAead128, Key, Nonce};
use ascon_aead::aead::{Aead, KeyInit};

type TruncatedAscon = TruncatedAsconAead128<U5>;
let key = Key::<TruncatedAscon>::from_slice(b"very secret key.");
let cipher = TruncatedAscon::new(key);

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

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");

Re-exports§

pub use aead;

Structs§

AsconAead128
Ascon-AEAD128
Error
Error type.
TruncatedAsconAead128
Truncated Ascon-AEAD128

Type Aliases§

AsconAead128Key
Key for Ascon-AEAD128
AsconAead128Nonce
Nonce for Ascon-AEAD128
AsconAead128Tag
Tag for Ascon-AEAD128
Key
Key used by KeySizeUser implementors.
Nonce
Nonce: single-use value for ensuring ciphertexts are unique
Tag
Tag: authentication code which ensures ciphertexts are authentic
TruncatedAsconAead128Key
Key for Truncated Ascon-AEAD128
TruncatedAsconAead128Nonce
Nonce for Truncated Ascon-AEAD128
TruncatedAsconAead128Tag
Tag for Truncated Ascon-AEAD128