| 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. |
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:
- The message itself
- 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:
- Data Integrity: Assurance that the received message is identical to the one used to calculate the MAC
- 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
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
