Message Authentication Codes (MAC) — Botan

Botan Message Authentication Codes (MAC)¶

A Message Authentication Code algorithm computes a tag over a message utilizing a shared secret key. Thus a valid tag confirms the authenticity and integrity of the message. Only entities in possession of the shared secret key are able to verify the tag.

Note

When combining a MAC with unauthenticated encryption mode, prefer to first encrypt the message and then MAC the ciphertext. The alternative is to MAC the plaintext, which depending on exact usage can suffer serious security issues. For a detailed discussion of this issue see the paper “The Order of Encryption and Authentication for Protecting Communications” by Hugo Krawczyk

The Botan MAC computation is split into five stages.

1. Instantiate the MAC algorithm.

2. Set the secret key.

3. Process IV.

4. Process data.

5. Finalize the MAC computation.

classMessageAuthenticationCode¶ std::stringname()const¶

Returns a human-readable string of the name of this algorithm.

voidclear()¶

Clear the key.

std::unique_ptr<MessageAuthenticationCode>new_object()const¶

Return a newly allocated object of the same type as this one. The new object is unkeyed.

voidset_key(constuint8_t*key, size_tlength)¶

Set the shared MAC key for the calculation. This function has to be called before the data is processed.

boolvalid_keylength(size_tlength)const¶

This function returns true if and only if length is a valid keylength for the algorithm.

size_tminimum_keylength()const¶

Return the smallest key length (in bytes) that is acceptable for the algorithm.

size_tmaximum_keylength()const¶

Return the largest key length (in bytes) that is acceptable for the algorithm.

voidstart(constuint8_t*nonce, size_tnonce_len)¶

Set the IV for the MAC calculation. Note that not all MAC algorithms require an IV. If an IV is required, the function has to be called before the data is processed. For algorithms that don’t require it, the call can be omitted, or else called with nonce_len of zero.

voidupdate(constuint8_t*input, size_tlength)¶

Process the passed data.

voidupdate(constsecure_vector<uint8_t>&in)¶

Process the passed data.

voidupdate(uint8_tin)¶

Process a single byte.

voidfinal(uint8_t*out)¶

Complete the MAC computation and write the calculated tag to the passed byte array.

secure_vector<uint8_t>final()¶

Complete the MAC computation and return the calculated tag.

boolverify_mac(constuint8_t*mac, size_tlength)¶

Finalize the current MAC computation and compare the result to the passed mac. Returns true, if the verification is successful and false otherwise.

Code Examples¶

The following example computes an HMAC with a random key then verifies the tag.

#include<botan/auto_rng.h> #include<botan/hex.h> #include<botan/mac.h> #include<assert.h> namespace{ std::stringcompute_mac(std::string_viewmsg,std::span<constuint8_t>key){ autohmac=Botan::MessageAuthenticationCode::create_or_throw("HMAC(SHA-256)"); hmac->set_key(key); hmac->update(msg); returnBotan::hex_encode(hmac->final()); } }// namespace intmain(){ Botan::AutoSeeded_RNGrng; constautokey=rng.random_vec(32);// 256 bit random key // "Message" != "Mussage" so tags will also not match std::stringtag1=compute_mac("Message",key); std::stringtag2=compute_mac("Mussage",key); assert(tag1!=tag2); // Recomputing with original input message results in identical tag std::stringtag3=compute_mac("Message",key); assert(tag1==tag3); return0; }

The following example code computes a AES-256 GMAC and subsequently verifies the tag. Unlike most other MACs, GMAC requires a nonce which must not repeat or all security is lost.

#include<botan/hex.h> #include<botan/mac.h> #include<iostream> intmain(){ constautokey=Botan::hex_decode_locked("1337133713371337133713371337133713371337133713371337133713371337"); constautononce=Botan::hex_decode("FFFFFFFFFFFFFFFFFFFFFFFF"); constautodata=Botan::hex_decode_locked("6BC1BEE22E409F96E93D7E117393172A"); constautomac=Botan::MessageAuthenticationCode::create_or_throw("GMAC(AES-256)"); mac->set_key(key); mac->start(nonce); mac->update(data); constautotag=mac->final(); std::cout<<mac->name()<<": "<<Botan::hex_encode(tag)<<'\n'; // Verify created MAC mac->start(nonce); mac->update(data); std::cout<<"Verification: "<<(mac->verify_mac(tag)?"success":"failure"); return0; }

The following example code computes a valid AES-128 CMAC tag and modifies the data to demonstrate a MAC verification failure.

#include<botan/hex.h> #include<botan/mac.h> #include<iostream> intmain(){ constautokey=Botan::hex_decode_locked("2B7E151628AED2A6ABF7158809CF4F3C"); autodata=Botan::hex_decode("6BC1BEE22E409F96E93D7E117393172A"); constautomac=Botan::MessageAuthenticationCode::create_or_throw("CMAC(AES-128)"); mac->set_key(key); mac->update(data); constautotag=mac->final(); // Corrupting data data.back()++; // Verify with corrupted data mac->update(data); std::cout<<"Verification with malformed data: "<<(mac->verify_mac(tag)?"success":"failure"); return0; }

Available MACs¶

Currently the following MAC algorithms are available in Botan. In new code, default to HMAC with a strong hash like SHA-256 or SHA-384.

Blake2B MAC¶

Available if BOTAN_HAS_BLAKE2BMAC is defined.

Algorithm specification name: BLAKE2b(<optional output bits>) (reported name) / Blake2b(<optional output bits>)

• Output bits defaults to 512.

• Examples: BLAKE2b(256), BLAKE2b

CMAC¶

A modern CBC-MAC variant that avoids the security problems of plain CBC-MAC. Approved by NIST. Also sometimes called OMAC.

Available if BOTAN_HAS_CMAC is defined.

Algorithm specification name: CMAC(<BlockCipher>) (reported name) / OMAC(<BlockCipher>), e.g. CMAC(AES-256)

GMAC¶

GMAC is related to the GCM authenticated cipher mode. It is quite slow unless hardware support for carryless multiplications is available. A new nonce must be used with each message authenticated, or otherwise all security is lost.

Available if BOTAN_HAS_GMAC is defined.

Warning

Due to the nonce requirement, GMAC is exceptionally fragile. Avoid it unless absolutely required.

Algorithm specification name: GMAC(<BlockCipher>), e.g. GMAC(AES-256)

HMAC¶

A message authentication code based on a hash function. Very commonly used.

Available if BOTAN_HAS_HMAC is defined.

Algorithm specification name: HMAC(<HashFunction>), e.g. HMAC(SHA-512)

KMAC¶

Added in version 3.2.

A SHA-3 derived message authentication code defined by NIST in SP 800-185.

There are two variants, KMAC-128 and KMAC-256. Both take a parameter which specifies the output length in bits, for example KMAC-128(256).

Available if BOTAN_HAS_KMAC is defined.

Algorithm specification names:

• KMAC-128(<output size>), e.g. KMAC-128(256)

• KMAC-256(<output size>), e.g. KMAC-256(256)

Poly1305¶

A polynomial mac (similar to GMAC). Very fast, but tricky to use safely. Forms part of the ChaCha20Poly1305 AEAD mode. A new key must be used for each message, or all security is lost.

Available if BOTAN_HAS_POLY1305 is defined.

Warning

Due to the nonce requirement, Poly1305 is exceptionally fragile. Avoid it unless absolutely required.

Algorithm specification name: Poly1305

SipHash¶

Deprecated since version 3.8.0.

SipHash is primarily designed for hash table randomization and, while not known to be insecure for message authentication, is not advisable for this use due to the small output size (just 64 bits).

Defaults to “SipHash(2,4)” which is the recommended configuration, using 2 rounds for each input block and 4 rounds for finalization.

Available if BOTAN_HAS_SIPHASH is defined.

Algorithm specification name: SipHash(<optional C>,<optional D>)

• C defaults to 2

• D defaults to 4

• Examples: SipHash(2,4), SipHash(2), SipHash

X9.19-MAC¶

Deprecated since version 3.7.0.

A CBC-MAC variant sometimes used in finance. Always uses DES. Sometimes called the “DES retail MAC”, also standardized in ISO 9797-1.

It is slow and has known attacks. Avoid unless required.

Available if BOTAN_HAS_X919_MAC is defined.

Algorithm specification name: X9.19-MAC

Table of Contents

• Getting Started
• Project Goals
• Support Information
• Building The Library
• Semantic Versioning
• Botan 2.x to 3.x Migration
• OpenSSL 1.1 to Botan 3.x Migration
• API Reference
  • Footguns
  • Versioning
  • Memory container
  • Random Number Generators
  • Hash Functions and Checksums
  • Block Ciphers
  • Stream Ciphers
  • Message Authentication Codes (MAC)
    • MessageAuthenticationCode
      • MessageAuthenticationCode::name
      • MessageAuthenticationCode::clear
      • MessageAuthenticationCode::new_object
      • MessageAuthenticationCode::set_key
      • MessageAuthenticationCode::valid_keylength
      • MessageAuthenticationCode::minimum_keylength
      • MessageAuthenticationCode::maximum_keylength
      • MessageAuthenticationCode::start
      • MessageAuthenticationCode::update
      • MessageAuthenticationCode::update
      • MessageAuthenticationCode::update
      • MessageAuthenticationCode::final
      • MessageAuthenticationCode::final
      • MessageAuthenticationCode::verify_mac
    • Code Examples
    • Available MACs
      • Blake2B MAC
      • CMAC
      • GMAC
      • HMAC
      • KMAC
      • Poly1305
      • SipHash
      • X9.19-MAC
  • Cipher Modes
  • Public Key Cryptography
  • X.509 Certificates and CRLs
  • Transport Layer Security (TLS)
  • Credentials Manager
  • BigInt
  • Key Derivation Functions (KDF)
  • Password Based Key Derivation
  • AES Key Wrapping
  • Password Hashing
  • Cryptobox
  • Secure Remote Password
  • PSK Database
  • Pipe/Filter Message Processing
  • Format Preserving Encryption
  • Threshold Secret Sharing
  • EC_Group
  • Elliptic Curve Operations
  • Lossless Data Compression
  • External Providers
  • PKCS#11
  • Trusted Platform Module (TPM)
  • One Time Passwords
  • Roughtime
  • libsodium Compatible Interfaces
  • ZFEC Forward Error Correction
  • FFI (C Binding)
  • Environment Variables
  • Python Binding
• Command Line Interface
• Hardware Acceleration
• Deprecated Features
• Development Roadmap
• Credits
• ABI Stability
• Notes for Distributors
• Security Advisories
• Threat Model
• Side Channels
• Developer Reference

Search

previous | next | modules | index Last updated on 2025-11-06.