Skip to main content

Crate tc_aead_cipher

Crate tc_aead_cipher 

Source
Expand description

Authenticated encryption with associated data (AEAD), ported from Bouncy Castle C#: the AeadCipher and AeadCipherInit contracts, and the modes that build them on any engine implementing the tc_block_cipher traits, such as tc_aes::AesEngine:

  • GcmBlockCipher — GCM (NIST SP 800-38D).
  • EaxBlockCipher — EAX, over 8- or 16-byte blocks.
  • CcmBlockCipher — CCM (NIST SP 800-38C, RFC 3610).
  • GcmSivBlockCipher — GCM-SIV (RFC 8452), which tolerates nonce reuse.
  • OcbBlockCipher — OCB3 (RFC 7253).
  • KccmBlockCipher — KCCM (DSTU 7624:2014), over 16-, 32- or 64-byte blocks.

Algorithms that carry their own primitive implement the same contracts in their own crates: tc_ascon_aead, tc_chacha_aead, tc_grain128_aead and tc_sparkle_aead.

The crate is no_std, needs no allocator by default and contains no unsafe code. The default-off alloc feature adds the four modes that buffer the whole message, CCM, GCM-SIV, OCB and KCCM, and AeadParamsOwned and ParamsWithAeadOwned, which own and wipe their bytes.

Every engine documents its timing. The modes are constant time exactly when their block cipher is, and lengths are public throughout. Decryption may write unauthenticated plaintext before do_final verifies the tag, so discard the output when do_final fails.

§Example

use tc_aead_cipher::{AeadCipher, AeadCipherInit, AeadParamsRef, GcmBlockCipher};
use tc_aes::AesEngine;
use tc_block_cipher::CipherDirection;

let (key, nonce) = ([0x42; 16], [0x24; 12]);
let params = AeadParamsRef::new(&key, &nonce, 16, b"header");
let mut gcm = GcmBlockCipher::new(AesEngine::new());

gcm.init(CipherDirection::Encrypt, &params)?;
let mut sealed = [0; 14 + 16];
let written = gcm.process_bytes(b"attack at dawn", &mut sealed)?;
gcm.do_final(&mut sealed[written..])?;

gcm.init(CipherDirection::Decrypt, &params)?;
let mut opened = [0; 14];
let written = gcm.process_bytes(&sealed, &mut opened)?;
gcm.do_final(&mut opened[written..])?;
assert_eq!(&opened, b"attack at dawn");

Structs§

AeadParamsOwned
Owned key, nonce, initial AAD, and authentication-tag size parameters, wiped on drop.
AeadParamsRef
Borrowed key, nonce, initial AAD, and authentication-tag size parameters.
CcmBlockCipher
Counter with CBC-MAC authenticated encryption over a 16-byte block cipher.
EaxBlockCipher
EAX authenticated encryption over a 64- or 128-bit block cipher.
GcmBlockCipher
Galois/Counter Mode authenticated encryption over a 16-byte block cipher.
GcmSivBlockCipher
GCM-SIV authenticated encryption over a 16-byte block cipher.
KccmBlockCipher
DSTU 7624 KCCM with a compile-time NB parameter.
OcbBlockCipher
OCB3 authenticated encryption over two instances of the same block cipher.
ParamsWithAeadOwned
A cipher’s own parameters with an owned nonce and initial associated data and a tag size, wiped on drop.
ParamsWithAeadRef
A cipher’s own parameters, a nonce and initial associated data, all borrowed, and a tag size.

Enums§

AeadError
A failure while processing or finalizing an AEAD operation; E is the underlying cipher’s error, Infallible for constructions without one.
AeadInitError
A failure while initializing an AEAD construction; E is the underlying cipher’s initialization error, Infallible for constructions without one.

Traits§

AeadBlockCipher
An AeadCipher built on a block cipher, which it exposes.
AeadCipher
An incremental AEAD engine: associated data first, then the message, then do_final.
AeadCipherInit
Prepares an AeadCipher from a parameter value of type P.
InitialAadParams
Parameters that carry associated data for AeadCipherInit::init to absorb before any AeadCipher::process_aad_bytes call.
MacSizeParams
Parameters that carry the authentication-tag size.
NonceParams
Parameters that carry the nonce.