Crate deoxys

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