message-authentication-code-pattern

---
name: message-authentication-code-pattern
description: Security pattern for implementing Message Authentication Codes (MACs) to ensure data integrity and origin authentication. Use when implementing HMAC, CMAC, or other MAC algorithms, verifying message integrity, authenticating message origin with shared secrets, or when non-repudiation is NOT required. Specialization of Cryptographic action pattern.
license: MIT
---

# Message Authentication Code (MAC) Security Pattern

This pattern encapsulates common considerations for using Message Authentication Codes (MAC) to ensure the integrity of messages and authenticate the identity of the provider.

## What is a MAC?

A Message Authentication Code (MAC) is a tag computed from a message using a special hash function whose output depends on a secret cryptographic key. Generating a MAC requires:
1. The message itself
2. Possession of a secret key

Only parties possessing the agreed-upon secret key can generate and verify valid MACs.

## Properties Provided

Appending a MAC to a message provides two properties:

1. **Data Integrity**: Assurance that the received message is identical to the one used to calculate the MAC
2. **Data Origin Authentication**: Assurance of the identity of the party that originated the message (i.e., they possess the secret key)

## Properties NOT Provided

**Important Limitations**:
- Properties depend on **secrecy of the cryptographic key**
- Anyone possessing the key can generate valid MACs for any message
- An attacker with the secret can compute a new MAC after altering a message (undetectable)
- **MAC does NOT provide evidence that a specific party generated it** (all parties share the same key)
- **No non-repudiation**: Cannot prove which specific party created the MAC

**If non-repudiation is required**: Use digital signatures instead of MACs.

## Core Components

| Role | Type | Responsibility |
|------|------|----------------|
| **EntityA** | Entity | Wants to create a MAC for message(s) |
| **EntityB** | Entity | Wants to verify whether message was modified |
| **MAC Generator** | Cryptographic Primitive | Generates MAC for message and key |
| **MAC Verifier** | Cryptographic Primitive | Verifies message and MAC match |

**Note**: MAC Generator and MAC Verifier can be the same library instance. EntityA and EntityB can also be the same entity.

### Data Elements

- **m**: Message (plaintext data element or action request)
- **mac**: The generated MAC tag
- **keyInfo**: Information on the secret key
- **config**: Cipher configuration (optional)
- **confirmation**: Verification success indication
- **error**: Verification failure indication

### Actions

- **generate**: Create MAC for message m using secret key
- **verify**: Check if message m and MAC match using secret key

## Pattern Flow

### MAC Generation
```
EntityA → [generate(m, keyInfo)] → MAC Generator
MAC Generator → [mac] → EntityA
EntityA → [m + mac] → EntityB
```

### MAC Verification
```
EntityB → [verify(m, mac, keyInfo)] → MAC Verifier
MAC Verifier → [confirmation or error] → EntityB
```

The MAC Verifier checks whether the MAC generated from m using the given key is identical to the provided MAC. If so, confirms to EntityB; otherwise, returns error.

## Algorithm Recommendations

### Recommended Algorithms
- **HMAC-SHA-256** / **HMAC-SHA-384** / **HMAC-SHA-512**
- **AES-CMAC**
- **Blake2b**

### Deprecated/Avoid
- **HMAC-MD5**: Avoid except for verifying legacy MACs
- Ad hoc constructions (e.g., SHA(message || secret)): **Insecure - never use**

**Critical**: Always use dedicated MAC ciphers. Ad hoc constructions using unkeyed hash functions concatenated with secrets have been shown to be insecure.

### Key Length
- **Minimum 128 bits** for the secret key

### MAC Output Length

| Use Case | Recommended Length |
|----------|-------------------|
| Long-term (10+ years) | 256 bits |
| Standard (up to 10 years) | 128 bits |
| Short-lived (e.g., session tokens) | 64 bits minimum |

## Security Considerations

### Key Confidentiality and Integrity

A cryptographic key used to generate and verify MACs should:
- **Always be kept confidential**
- Have its **integrity protected**
- Be secured during persistent storage
- Be secured during transmission between entities

### Use Keys for Single Purpose

Specialization of Cryptographic action.Use keys for a single purpose:
- **Never use MAC keys for other purposes** (e.g., encryption)
- Dedicated key for MAC generation/verification only

### Design for Change

Specialization of Cryptographic action.Design for change:
- Algorithms may become deprecated
- Design for easy algorithm transitions

### Reuse Existing Libraries

Specialization of Cryptographic action.Reuse existing libraries:
- Use well-known cryptographic libraries
- Never implement custom MAC algorithms

### Authenticated Encryption Preference

**If protecting integrity of encrypted messages in transit**:
- Use **authenticated encryption** instead of separate encryption + MAC
- Authenticated encryption uses a single symmetric key for both confidentiality and authentication
- Separate encryption and MAC requires two distinct keys, complicating key management

## MAC vs. Digital Signature

| Aspect | MAC | Digital Signature |
|--------|-----|-------------------|
| Key type | Symmetric (shared secret) | Asymmetric (public/private) |
| Non-repudiation | No | Yes |
| Who can verify | Only key holders | Anyone with public key |
| Who can generate | Any key holder | Only private key holder |
| Performance | Faster | Slower |
| Use case | Internal integrity | External verification, legal |

## Implementation Checklist

- [ ] Using recommended algorithm (HMAC-SHA-256, AES-CMAC, Blake2b)
- [ ] **No HMAC-MD5** for new implementations
- [ ] **No ad hoc constructions** (hash(message || key))
- [ ] Secret key minimum 128 bits
- [ ] MAC output appropriate for use case (64-256 bits)
- [ ] Key used only for MAC (not encryption)
- [ ] Key confidentiality protected
- [ ] Key integrity protected
- [ ] Using authenticated encryption if combining with encryption
- [ ] Understood: MAC provides NO non-repudiation

## Related Patterns

- **Cryptographic action** (parent pattern)
- **Digital signature** (alternative when non-repudiation needed)
- **Encryption** (combine via authenticated encryption)
- **Cryptographic key management** (key handling)

## References

- Source: https://securitypatterns.distrinet-research.be/patterns/99_01_004__mac/
- P. C. van Oorschot, Computer Security and the Internet - Tools and Jewels, 2020
- E. Barker, 'Recommendation for Key Management: Part 1 – General', NIST SP 800-57 Part 1, May 2020
- Bundesamt für Sicherheit in der Informationstechnik, 'Cryptographic Mechanisms: Recommendations and Key Lengths', BSI TR-02102-1, Mar. 2020
- N. P. Smart et al., 'Algorithms, Key size and parameters report', ENISA, Nov. 2014
- S. Turner and L. Chen, 'Updated Security Considerations for the MD5 Message-Digest and the HMAC-MD5 Algorithms', IETF RFC 6151, Mar. 2011
- B. Preneel and P. C. van Oorschot, 'On the security of iterated message authentication codes', IEEE Transactions on Information Theory, vol. 45, no. 1, Jan. 1999
- Google Tink - Message Authentication Code (MAC): https://developers.google.com/tink/mac