Expand description
The Deoxys Authenticated Encryption and Associated Data (AEAD) cipher.
The Deoxys-II variant has been selected as the first choice for defense in-depth scenario during the CAESAR competition.
§Security Notes
This crate has NOT received any security audit.
Although encryption and decryption passes the test vector, there is no guarantee of constant-time operation.
USE AT YOUR OWN RISK.
§Usage
use deoxys::{
aead::{Aead, KeyInit, OsRng},
DeoxysII256, // Can be `DeoxysI128`, `DeoxysI256`, `DeoxysII128` of `DeoxysII256`
Nonce // Or `Aes128Gcm`
};
let key = DeoxysII256::generate_key(&mut OsRng);
let cipher = DeoxysII256::new(&key);
let nonce = Nonce::from_slice(b"unique nonce123"); // 64-bits for Deoxys-I or 120-bits for Deoxys-II; 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");
§Usage with AAD
Deoxys can authenticate additionnal data that is not encrypted alongside with the ciphertext.
use deoxys::{DeoxysII256, Key, Nonce}; // Can be `DeoxysI128`, `DeoxysI256`, `DeoxysII128` of `DeoxysII256`
use deoxys::aead::{Aead, KeyInit, Payload};
let key = Key::<DeoxysII256>::from_slice(b"an example very very secret key.");
let cipher = DeoxysII256::new(key);
let nonce = Nonce::from_slice(b"unique nonce123"); // 64-bits for Deoxys-I or 120-bits for Deoxys-II; unique per message
let payload = Payload {
msg: &b"this will be encrypted".as_ref(),
aad: &b"this will NOT be encrypted, but will be authenticated".as_ref(),
};
let ciphertext = cipher.encrypt(nonce, payload)
.expect("encryption failure!"); // NOTE: handle this error to avoid panics!
let payload = Payload {
msg: &ciphertext,
aad: &b"this will NOT be encrypted, but will be authenticated".as_ref(),
};
let plaintext = cipher.decrypt(nonce, payload)
.expect("decryption failure!"); // NOTE: handle this error to avoid panics!
assert_eq!(&plaintext, b"this will be encrypted");
§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 deoxys::{DeoxysII256, Key, Nonce}; // Can be `DeoxysI128`, `DeoxysI256`, `DeoxysII128` of `DeoxysII256`
use deoxys::aead::{AeadInPlace, KeyInit};
use deoxys::aead::heapless::Vec;
let key = Key::<DeoxysII256>::from_slice(b"an example very very secret key.");
let cipher = DeoxysII256::new(key);
let nonce = Nonce::from_slice(b"unique nonce123"); // 64-bits for Deoxys-I or 120-bits for Deoxys-II; unique per message
let mut buffer: Vec<u8, 128> = Vec::new(); // Buffer needs 16-bytes overhead for 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;
Modules§
- Type aliases for many constants.
Structs§
- Generic Deoxys implementation.
- Error type.
Traits§
- Authenticated Encryption with Associated Data (AEAD) algorithm core trait.
- In-place stateless AEAD trait.
- Deoxys-BC trait. This type contains the public API for Deoxys-BC implementations, which varies depending on the size of the key.
- Deoxys encryption modes. This type contains the public API for a Deoxys mode, like Deoxys-I and Deoxys-II.
- Types which can be initialized from key.
- Types which use key for initialization.
Type Aliases§
- Deoxys-I with 128-bit keys
- Deoxys-I with 256-bit keys
- Deoxys-II with 128-bit keys
- Deoxys-II with 256-bit keys
- Key used by
KeySizeUser
implementors. - Deoxys nonces
- Deoxys tags