Crate ascon_aead128

Expand description

§RustCrypto: Ascon

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!

§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):

// NOTE: requires the `getrandom` feature is enabled

use ascon_aead128::{
    aead::{Aead, Generate, KeyInit, AeadCore},
    AsconAead128, AsconAead128Key, AsconAead128Nonce
};

let key = AsconAead128Key::generate();
let cipher = AsconAead128::new(&key);

let nonce = AsconAead128Nonce::generate(); // MUST be unique per message
let ciphertext = cipher.encrypt(&nonce, b"plaintext message".as_ref())?;

let plaintext = cipher.decrypt(&nonce, ciphertext.as_ref())?;
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 AeadInOut::encrypt_in_place and AeadInOut::decrypt_in_place methods accept any type that impls the aead::Buffer trait which contains the plaintext for encryption or ciphertext for decryption.

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).

It can then be passed as the buffer parameter to the in-place encrypt and decrypt methods:

// NOTE: requires the `arrayvec` and `getrandom` features are enabled

use ascon_aead128::{
    aead::{AeadCore, AeadInOut, Generate, KeyInit, arrayvec::ArrayVec},
    AsconAead128, AsconAead128Key, AsconAead128Nonce
};

let key = AsconAead128Key::generate();
let cipher = AsconAead128::new(&key);

let nonce = AsconAead128Nonce::generate(); // MUST be unique per message
let mut buffer: ArrayVec<u8, 128> = ArrayVec::new(); // Buffer needs 16-bytes overhead for authentication tag
buffer.try_extend_from_slice(b"plaintext message").unwrap();

// 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.as_ref(), 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.as_ref(), b"plaintext message");

Re-exports§

pub use aead;
pub use zeroize;zeroize

Structs§

AsconAead128: Ascon-AEAD128
Error: Error type.

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