Crate ascon_aead
source ·Expand description
RustCrypto: Ascon
Pure Rust implementation of the lightweight Authenticated Encryption with Associated Data (AEAD) algorithms Ascon-128, Ascon-128a, and Ascon-80pq.
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.56 at a minimum.
We may change the MSRV in the future, but it will be accompanied by a minor version bump.
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::{Ascon128, Key, Nonce}; // Or `Ascon128a`
use ascon_aead::aead::{Aead, KeyInit};
let key = Key::<Ascon128>::from_slice(b"very secret key.");
let cipher = Ascon128::new(key);
let nonce = Nonce::<Ascon128>::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, KeyInit};
use ascon_aead::aead::heapless::Vec;
let key = Key::<Ascon128>::from_slice(b"very secret key.");
let cipher = Ascon128::new(key);
let nonce = Nonce::<Ascon128>::from_slice(b"unique nonce 012"); // 128-bits; unique per message
let mut buffer: Vec<u8, 128> = 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-80pq
- Ascon-128
- Ascon-128a
- Error type.
Type Definitions
- Key for Ascon-80pq
- Nonce for Ascon-80pq
- Tag for Ascon-80pq
- Key for Ascon-128
- Nonce for Ascon-128
- Tag for Ascon-128
- Key for Ascon-128a
- Nonce for Ascon-128a
- Tag for Ascon-128a
- Key used by [
KeySizeUser
] implementors. - Nonce: single-use value for ensuring ciphertexts are unique
- Tag: authentication code which ensures ciphertexts are authentic