Skip to main content

Crate tc_macs

Crate tc_macs 

Source
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, and FixedPaddedCbcMac, which pads the final block; adds tc_block_modes and tc_block_padding.
  • cfb-mac — FixedCfbMac, and FixedPaddedCfbMac, which pads a partial final segment; adds tc_block_modes and tc_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; adds tc_aead_cipher and tc_block_modes.
  • hmac — FixedHmac, HMAC (RFC 2104) over a digest; adds tc_digest.
  • siphash — SipHash, SipHash-c-d; adds no dependency.
  • vmpc-mac — VmpcMac, VMPC-MAC; adds tc_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, Cmac and Hmac.

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’s CbcBlockCipherMac without padding.
CfbMac
CFB-MAC over the block cipher C, with buffers sized from its block size at run time; Bouncy Castle’s CfbBlockCipherMac without 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’s CMac.
FixedCbcMac
CBC-MAC over the block cipher C with blocks of N bytes, keeping its buffers inline for builds without an allocator; Bouncy Castle’s CbcBlockCipherMac without padding.
FixedCfbMac
CFB-MAC over the block cipher C with blocks of N bytes, keeping its buffers inline for builds without an allocator; Bouncy Castle’s CfbBlockCipherMac without padding.
FixedCmac
CMAC (NIST SP 800-38B, RFC 4493), also known as OMAC1, over the block cipher C with blocks of N bytes, keeping its buffers inline for builds without an allocator; Bouncy Castle’s CMac.
FixedHmac
HMAC (RFC 2104) over the cloneable digest D, without an allocator; Bouncy Castle’s HMac.
FixedPaddedCbcMac
CBC-MAC over the block cipher C with blocks of N bytes that pads the final block with P, keeping its buffers inline for builds without an allocator; Bouncy Castle’s CbcBlockCipherMac with padding.
FixedPaddedCfbMac
CFB-MAC over the block cipher C with blocks of N bytes that pads a partial final segment with P, keeping its buffers inline for builds without an allocator; Bouncy Castle’s CfbBlockCipherMac with 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’s GMac. 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’s HMac.
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.
KeyWithIvFixed
Owned, fixed-size key and initialization-vector parameters, wiped on drop.
KeyWithIvOwned
Owned key and initialization-vector vectors, wiped on drop.
KeyWithIvRef
Borrowed key and initialization-vector parameters.
PaddedCbcMac
CBC-MAC over the block cipher C that pads the final block with P, with buffers sized from its block size at run time; Bouncy Castle’s CbcBlockCipherMac with padding.
PaddedCfbMac
CFB-MAC over the block cipher C that pads a partial final segment with P, with buffers sized from its block size at run time; Bouncy Castle’s CfbBlockCipherMac with 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§

InitError
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’s IMac.
MacInit
Keys a Mac from parameters of type P.