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, ¶ms)?;
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, ¶ms)?;
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§
- Aead
Params Owned - Owned key, nonce, initial AAD, and authentication-tag size parameters, wiped on drop.
- Aead
Params Ref - Borrowed key, nonce, initial AAD, and authentication-tag size parameters.
- CcmBlock
Cipher - Counter with CBC-MAC authenticated encryption over a 16-byte block cipher.
- EaxBlock
Cipher - EAX authenticated encryption over a 64- or 128-bit block cipher.
- GcmBlock
Cipher - Galois/Counter Mode authenticated encryption over a 16-byte block cipher.
- GcmSiv
Block Cipher - GCM-SIV authenticated encryption over a 16-byte block cipher.
- Kccm
Block Cipher - DSTU 7624 KCCM with a compile-time
NBparameter. - OcbBlock
Cipher - OCB3 authenticated encryption over two instances of the same block cipher.
- Params
With Aead Owned - A cipher’s own parameters with an owned nonce and initial associated data and a tag size, wiped on drop.
- Params
With Aead Ref - A cipher’s own parameters, a nonce and initial associated data, all borrowed, and a tag size.
Enums§
- Aead
Error - A failure while processing or finalizing an AEAD operation;
Eis the underlying cipher’s error,Infalliblefor constructions without one. - Aead
Init Error - A failure while initializing an AEAD construction;
Eis the underlying cipher’s initialization error,Infalliblefor constructions without one.
Traits§
- Aead
Block Cipher - An
AeadCipherbuilt on a block cipher, which it exposes. - Aead
Cipher - An incremental AEAD engine: associated data first, then the message, then
do_final. - Aead
Cipher Init - Prepares an
AeadCipherfrom a parameter value of typeP. - Initial
AadParams - Parameters that carry associated data for
AeadCipherInit::initto absorb before anyAeadCipher::process_aad_bytescall. - MacSize
Params - Parameters that carry the authentication-tag size.
- Nonce
Params - Parameters that carry the nonce.