Crate deoxys 

RustCrypto: Deoxys Cipher

Pure Rust implementation of the Deoxys cipher which provides Authenticated Encryption with Associated Data (AEAD), including the Deoxys-II variant which was selected by the CAESAR competition as the best choice for in-depth security.

Documentation

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.

License

Licensed under either of:

• Apache License, Version 2.0
• MIT license

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

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

use deoxys::{
    aead::{Aead, AeadCore, Generate, Key, KeyInit},
    DeoxysII256, // Can be `DeoxysI128`, `DeoxysI256`, `DeoxysII128` of `DeoxysII256`
    Nonce
};

let key = Key::<DeoxysII256>::generate();
let cipher = DeoxysII256::new(&key);

let nonce = Nonce::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");

Usage with AAD

Deoxys can authenticate additional data that is not encrypted alongside with the ciphertext.

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

use deoxys::{
    aead::{Aead, AeadCore, Generate, Key, KeyInit, Payload},
    DeoxysII256, // Can be `DeoxysI128`, `DeoxysI256`, `DeoxysII128` of `DeoxysII256`
    Nonce
};

let key = Key::<DeoxysII256>::generate();
let cipher = DeoxysII256::new(&key);

let nonce = Nonce::generate(); // MUST be 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)?;

let payload = Payload {
   msg: &ciphertext,
   aad: &b"this will NOT be encrypted, but will be authenticated".as_ref(),
};

let plaintext = cipher.decrypt(&nonce, payload)?;
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 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 deoxys::{
    aead::{AeadCore, AeadInOut, Generate, Key, KeyInit, arrayvec::ArrayVec},
    DeoxysII256, // Can be `DeoxysI128`, `DeoxysI256`, `DeoxysII128` of `DeoxysII256`
    Nonce
};

let key = Key::<DeoxysII256>::generate();
let cipher = DeoxysII256::new(&key);

let nonce = Nonce::generate(); // MUST be unique per message

let mut buffer: ArrayVec<u8, 128> = ArrayVec::new(); // Buffer needs 16-bytes overhead for 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)?;

// `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)?;
assert_eq!(buffer.as_ref(), b"plaintext message");

Re-exports

pub use aead;

Modules

consts

Structs

Deoxys

Generic Deoxys implementation.

Error

Error type.

Traits

AeadCore

Authenticated Encryption with Associated Data (AEAD) algorithm.

AeadInOut

In-place and inout AEAD trait which handles the authentication tag as a return value/separate parameter.

DeoxysBcType

Deoxys-BC trait. This type contains the public API for Deoxys-BC implementations, which varies depending on the size of the key.

DeoxysMode

Deoxys encryption modes. This type contains the public API for a Deoxys mode, like Deoxys-I and Deoxys-II.

KeyInit

Types which can be initialized from a key.

KeySizeUser

Types which use key for initialization.

Type Aliases

DeoxysI128

Deoxys-I with 128-bit keys

DeoxysI256

Deoxys-I with 256-bit keys

DeoxysII128

Deoxys-II with 128-bit keys

DeoxysII256

Deoxys-II with 256-bit keys

Key

Key used by KeySizeUser implementors.

Nonce

Deoxys nonces

Tag

Deoxys tags