Expand description
Message authentication codes over block ciphers and digests, and the
Mac and MacInit contracts they share with MAC crates built on this
one, such as tc_poly1305.
The default build carries only the contracts, their errors and the key containers, so a MAC crate that implements the contracts depends on nothing more. Each MAC is behind its own default-off feature:
cbc-mac—FixedCbcMac, andFixedPaddedCbcMac, which pads the final block; addstc_block_modesandtc_block_padding.cfb-mac—FixedCfbMac, andFixedPaddedCfbMac, which pads a partial final segment; addstc_block_modesandtc_block_padding.cmac—FixedCmac, CMAC (NIST SP 800-38B, RFC 4493) over a 64- or 128-bit block cipher; adds no dependency.gmac—Gmac, GMAC (NIST SP 800-38D) over a 128-bit block cipher; addstc_aead_cipherandtc_block_modes.hmac—FixedHmac, HMAC (RFC 2104) over a digest; addstc_digest.siphash—SipHash, SipHash-c-d; adds no dependency.vmpc-mac—VmpcMac, VMPC-MAC; addstc_block_modes.alloc—KeyOwned, and for each MAC enabled the form that sizes its buffers from the cipher or digest at run time:CbcMac,PaddedCbcMac,CfbMac,PaddedCfbMac,CmacandHmac.
The block-cipher MACs run over any engine that implements the
tc_block_cipher traits, such as tc_aes, and HMAC over any digest that
implements tc_digest::Digest, such as those of tc_sha. Each follows the
Bouncy Castle class of its family, including its default tag size and its
name.
Every MAC takes its key through KeyParams; KeyRef, KeyFixed and
KeyOwned (alloc) are re-exported from tc_block_cipher. CBC-MAC,
CFB-MAC, GMAC and VMPC-MAC also take an IV through IvParams, which
KeyWithIvRef, KeyWithIvFixed and KeyWithIvOwned (alloc) provide
together with the key; with any of those four features, these are
re-exported from tc_block_modes.
The crate is no_std and contains no unsafe code. Only alloc reaches
the heap; the Fixed forms keep their buffers inline, with the block size
as the const parameter N.
Every MAC documents its timing: each that wraps a cipher or digest is
constant time exactly when that primitive is, SipHash is constant time and
VmpcMac is variable time; lengths are public. Every MAC wipes its
buffers on drop, and the cipher or digest it wraps wipes its own state when
that type does, as the engines of tc_aes, tc_des and tc_sha do.
§Example
With the cmac and hmac features, generic code authenticates a message
through the same calls whatever the MAC:
use tc_aes::AesEngine;
use tc_macs::{FixedCmac, FixedHmac, KeyRef, Mac, MacInit};
use tc_sha::Sha256Digest;
fn tag<M: Mac>(mac: &mut M, message: &[u8]) -> Result<Vec<u8>, M::Error> {
mac.update(message)?;
let mut tag = vec![0; mac.mac_size()];
mac.do_final(&mut tag)?;
Ok(tag)
}
let key = KeyRef::new(&[0x42; 16]);
let mut cmac = FixedCmac::<_, 16>::new(AesEngine::new());
cmac.init(&key)?;
assert_eq!(tag(&mut cmac, b"attack at dawn")?.len(), 16);
let mut hmac = FixedHmac::new(Sha256Digest::new());
hmac.init(&key)?;
assert_eq!(tag(&mut hmac, b"attack at dawn")?.len(), 32);Structs§
- CbcMac
- CBC-MAC over the block cipher
C, with buffers sized from its block size at run time; Bouncy Castle’sCbcBlockCipherMacwithout padding. - CfbMac
- CFB-MAC over the block cipher
C, with buffers sized from its block size at run time; Bouncy Castle’sCfbBlockCipherMacwithout padding. - Cmac
- CMAC (NIST SP 800-38B, RFC 4493) over the block cipher
C, with buffers sized from its block size at run time; Bouncy Castle’sCMac. - Fixed
CbcMac - CBC-MAC over the block cipher
Cwith blocks ofNbytes, keeping its buffers inline for builds without an allocator; Bouncy Castle’sCbcBlockCipherMacwithout padding. - Fixed
CfbMac - CFB-MAC over the block cipher
Cwith blocks ofNbytes, keeping its buffers inline for builds without an allocator; Bouncy Castle’sCfbBlockCipherMacwithout padding. - Fixed
Cmac - CMAC (NIST SP 800-38B, RFC 4493), also known as OMAC1, over the block
cipher
Cwith blocks ofNbytes, keeping its buffers inline for builds without an allocator; Bouncy Castle’sCMac. - Fixed
Hmac - HMAC (RFC 2104) over the cloneable digest
D, without an allocator; Bouncy Castle’sHMac. - Fixed
Padded CbcMac - CBC-MAC over the block cipher
Cwith blocks ofNbytes that pads the final block withP, keeping its buffers inline for builds without an allocator; Bouncy Castle’sCbcBlockCipherMacwith padding. - Fixed
Padded CfbMac - CFB-MAC over the block cipher
Cwith blocks ofNbytes that pads a partial final segment withP, keeping its buffers inline for builds without an allocator; Bouncy Castle’sCfbBlockCipherMacwith padding. - Gmac
- GMAC (NIST SP 800-38D) over the 128-bit block cipher
C: GCM that authenticates the message as associated data and encrypts nothing; Bouncy Castle’sGMac. It needs no allocator. - Hmac
- HMAC (RFC 2104) over the digest
D, with its pads sized from the digest’s block length at run time; Bouncy Castle’sHMac. - KeyFixed
- An owned, fixed-size key array that is wiped on drop.
- KeyOwned
- An owned key vector that is wiped on drop.
- KeyRef
- A borrowed key slice with no allocation or copying.
- KeyWith
IvFixed - Owned, fixed-size key and initialization-vector parameters, wiped on drop.
- KeyWith
IvOwned - Owned key and initialization-vector vectors, wiped on drop.
- KeyWith
IvRef - Borrowed key and initialization-vector parameters.
- Padded
CbcMac - CBC-MAC over the block cipher
Cthat pads the final block withP, with buffers sized from its block size at run time; Bouncy Castle’sCbcBlockCipherMacwith padding. - Padded
CfbMac - CFB-MAC over the block cipher
Cthat pads a partial final segment withP, with buffers sized from its block size at run time; Bouncy Castle’sCfbBlockCipherMacwith padding. - SipHash
- SipHash-c-d, the short-input PRF of Aumasson and Bernstein, with a 16-byte
key and an 8-byte tag; Bouncy Castle’s
SipHash. - VmpcMac
- VMPC-MAC, the MAC of Bartosz Zoltak’s VMPC stream cipher, with a key and an
IV of 16 to 64 bytes and a 20-byte tag; Bouncy Castle’s
VmpcMac.
Enums§
- Init
Error - A failure while initializing a message authentication code.
- MacError
- A failure while processing or finalizing a message authentication code.
Traits§
- IvParams
- Parameters that provide an initialization vector.
- KeyParams
- Provides borrowed access to cipher key bytes.
- Mac
- A message authentication code that takes a message in pieces of any size
and writes its tag in
do_final; the Rust form of Bouncy Castle’sIMac. - MacInit
- Keys a
Macfrom parameters of typeP.