Crate deoxys[−][src]
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::{DeoxysII256, Key, Nonce}; // Can be `DeoxysI128`, `DeoxysI256`, `DeoxysII128` of `DeoxysII256` use deoxys::aead::{Aead, NewAead}; let key = Key::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 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");
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, NewAead, Payload}; let key = Key::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, NewAead}; use deoxys::aead::heapless::Vec; let key = Key::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;
Structs
Generic Deoxys implementation.
Traits
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.
Type Definitions
Deoxys-I with 128-bit keys
Deoxys-I with 256-bit keys
Deoxys-II with 128-bit keys
Deoxys-II with 256-bit keys
Deoxys keys
Deoxys nonces
Deoxys tags