View source for HMAC

{{Short description|Computer communications authentication algorithm}}
{{pp|small=yes}}
{{Use dmy dates|date=June 2024}}
{{Redirect|NMAC|the Nissan Motor Acceptance Corp|Nissan USA}}
[[File:SHAhmac.svg|thumb|upright=1.5|HMAC-SHA1 generation]]

In [[cryptography]], an '''HMAC''' (sometimes expanded as either '''keyed-hash message authentication code''' or '''hash-based message authentication code''') is a specific type of [[message authentication code]] (MAC) involving a [[cryptographic hash function]] and a secret cryptographic key. As with any MAC, it may be used to simultaneously verify both the [[data integrity]] and authenticity of a message. An HMAC is a type of keyed hash function that can also be used in a key derivation scheme or a key stretching scheme.

HMAC can provide authentication using a [[shared secret]] instead of using [[digital signature]]s with [[Public-key cryptography|asymmetric cryptography]]. It trades off the need for a complex [[public key infrastructure]] by delegating the key exchange to the communicating parties, who are responsible for establishing and using a trusted channel to agree on the key prior to communication.

== Details ==
Any cryptographic hash function, such as [[SHA-2]] or [[SHA-3]], may be used in the calculation of an HMAC; the resulting MAC algorithm is termed HMAC-''x'', where ''x'' is the hash function used (e.g. HMAC-SHA256 or HMAC-SHA3-512). The [[cryptographic strength]] of the HMAC depends upon the cryptographic strength of the underlying hash function, the size of its hash output, and the size and quality of the key.<ref name="BCK96" />

HMAC uses two passes of hash computation. Before either pass, the secret key is used to derive two keys – inner and outer. Next, the first pass of the hash algorithm produces an internal hash derived from the message and the inner key. The second pass produces the final HMAC code derived from the inner hash result and the outer key. Thus the algorithm provides better immunity against [[length extension attack]]s.

An iterative hash function (one that uses the [[Merkle–Damgård construction]]) breaks up a message into blocks of a fixed size and iterates over them with a [[one-way compression function|compression function]]. For example, SHA-256 operates on 512-bit blocks. The size of the output of HMAC is the same as that of the underlying hash function (e.g., 256 and 512 bits in the case of SHA-256 and SHA3-512, respectively), although it can be truncated if desired.

HMAC does not encrypt the message. Instead, the message (encrypted or not) must be sent alongside the HMAC hash. Parties with the secret key will hash the message again themselves, and if it is authentic, the received and computed hashes will match.

The definition and analysis of the HMAC construction was first published in 1996 in a paper by [[Mihir Bellare]], [[Ran Canetti]], and [[Hugo Krawczyk]],<ref name=BCK96/><ref name=":1">{{Cite journal |last1=Bellare |first1=Mihir |last2=Canetti |first2=Ran |last3=Krawczyk |first3=Hugo |date=Spring 1996 |title=Message Authentication using Hash Functions—The HMAC Construction |url=https://cseweb.ucsd.edu/~mihir/papers/hmac-cb.pdf |journal=CryptoBytes |volume=2 |issue=1}}</ref> and they also wrote RFC 2104 in 1997.{{Ref RFC|2104|rsection=2}} The 1996 paper also defined a nested variant called NMAC (Nested MAC). [[Federal Information Processing Standards|FIPS]] PUB 198 generalizes and standardizes the use of HMACs.<ref>{{Cite journal |date=16 July 2008 |title=FIPS 198-1: The Keyed-Hash Message Authentication Code (HMAC) |url=https://csrc.nist.gov/publications/detail/fips/198/1/final |journal=Federal Information Processing Standards}}</ref> HMAC is used within the [[IPsec]],<ref name=":1" /> [[Secure Shell|SSH]] and [[Transport Layer Security|TLS]] protocols and for [[JSON Web Token]]s.

==Definition==
This definition is taken from RFC 2104:

:<math>\begin{align}
  \operatorname{HMAC}(K, m) &= \operatorname{H}\Bigl(\bigl(K' \oplus opad\bigr) \parallel 
\operatorname{H} \bigl(\left(K' \oplus ipad\right) \parallel m\bigr)\Bigr) \\
                         K' &= \begin{cases}
                                 \operatorname{H}\left(K\right) & \text{if}\ K\text{ is larger than block size} \\
                                 K                              & \text{otherwise}
                                \end{cases}
\end{align}</math>

where
: <math>\operatorname{H}</math> is a cryptographic hash function.
: <math>m</math> is the message to be authenticated.
: <math>K</math> is the secret key.
: <math>K'</math> is a block-sized key derived from the secret key, ''K''; either by padding to the right with 0s up to the block size, or by hashing down to less than or equal to the block size first and then padding to the right with zeros.
: <math>\parallel</math> denotes [[concatenation]].
: <math>\oplus</math> denotes bitwise [[exclusive or]] (XOR).
: <math>opad</math> is the block-sized outer padding, consisting of repeated bytes valued 0x5c.
: <math>ipad</math> is the block-sized inner padding, consisting of repeated bytes valued 0x36.{{Ref RFC|2104|rsection=2}}

{| class="wikitable"
! [[Hash function]] <code>H</code>
! <code>b</code>, [[byte]]s
! <code>L</code>, [[byte]]s
|-
| [[MD5]] || 64 || 16
|-
| [[SHA-1]] || 64 || 20
|-
| [[SHA-2|SHA-224]] || 64 || 28
|-
| [[SHA-2|SHA-256]] || 64 || 32
|-
| [[SHA-2|SHA-512/224]] || 128 || 28
|-
| [[SHA-2|SHA-512/256]] || 128 || 32
|-
| [[SHA-2|SHA-384]] || 128 || 48
|-
| [[SHA-2|SHA-512]] || 128 || 64<ref>{{cite web |title=FIPS 180-2 with Change Notice 1 |url=https://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf |website=csrc.nist.gov}}</ref>
|-
| [[SHA-3|SHA3-224]] || 144 || 28
|-
| [[SHA-3|SHA3-256]] || 136 || 32
|-
| [[SHA-3|SHA3-384]] || 104 || 48
|-
| [[SHA-3|SHA3-512]] || 72 || 64<ref>{{Cite journal |last=Dworkin |first=Morris |date=4 August 2015 |title=SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions |url=https://www.nist.gov/publications/sha-3-standard-permutation-based-hash-and-extendable-output-functions |journal=[[Federal Information Processing Standards]] |via=NIST Publications}}</ref>
|-
| colspan=3 |<code>out = H(in)</code><br /><code>L = length(out)</code><br /><code>b = H's internal block length</code>{{Ref RFC|2104|rsection=2}}
|}

==Implementation==
The following [[pseudocode]] demonstrates how HMAC may be implemented. The block size is 512 bits (64 bytes) when using one of the following hash functions: SHA-1, MD5, RIPEMD-128.{{Ref RFC|2104|rsection=2}}
 '''{{blue|function}}''' hmac '''{{blue|is}}'''
     '''{{blue|input:}}'''
         key:        Bytes    {{green|// Array of bytes}}
         message:    Bytes    {{green|// Array of bytes to be hashed}}
         hash:       Function {{green|// The hash function to use (e.g. SHA-1)}}
         blockSize:  Integer  {{green|// The block size of the hash function (e.g. 64 bytes for SHA-1)}}
         outputSize: Integer  {{green|// The output size of the hash function (e.g. 20 bytes for SHA-1)}}
 
     {{green|// Compute the block sized key}}
     block_sized_key = computeBlockSizedKey(key, hash, blockSize)
 
     o_key_pad ← block_sized_key xor [0x5c blockSize]   {{green|// Outer padded key}}
     i_key_pad ← block_sized_key xor [0x36 blockSize]   {{green|// Inner padded key}}
 
     '''{{blue|return}}'''  hash(o_key_pad ∥ hash(i_key_pad ∥ message))
 
 '''{{blue|function}}''' computeBlockSizedKey '''{{blue|is}}'''
     '''{{blue|input:}}'''
         key:        Bytes    {{green|// Array of bytes}}
         hash:       Function {{green|// The hash function to use (e.g. SHA-1)}}
         blockSize:  Integer  {{green|// The block size of the hash function (e.g. 64 bytes for SHA-1)}}
  
     {{green|// Keys longer than ''blockSize'' are shortened by hashing them}}
     '''{{blue|if}}''' (length(key) > blockSize) '''{{Font color|blue|then}}'''
         key = hash(key)
 
     {{green|// Keys shorter than ''blockSize'' are padded to ''blockSize'' by padding with zeros on the right}}
     '''{{blue|if}}''' (length(key) < blockSize) '''{{Font color|blue|then}}'''
         '''{{blue|return}}'''  Pad(key, blockSize) {{green|// Pad key with zeros to make it ''blockSize'' bytes long}}
 
     '''{{blue|return}}'''  key

==Design principles==
The design of the HMAC specification was motivated by the existence of attacks on more trivial mechanisms for combining a key with a hash function. For example, one might assume the same security that HMAC provides could be achieved with MAC = '''H'''(''key'' ∥ ''message''). However, this method suffers from a serious flaw: with most hash functions, it is easy to append data to the message without knowing the key and obtain another valid MAC ("[[Length extension attack|length-extension attack]]"). The alternative, appending the key using MAC = '''H'''(''message'' ∥ ''key''), suffers from the problem that an attacker who can find a collision in the (unkeyed) hash function has a collision in the MAC (as two messages m1 and m2 yielding the same hash will provide the same start condition to the hash function before the appended key is hashed, hence the final hash will be the same). Using MAC = '''H'''(''key'' ∥ ''message'' ∥ ''key'') is better, but various security papers have suggested vulnerabilities with this approach, even when two different keys are used.<ref name=BCK96>{{Cite web|url=https://cseweb.ucsd.edu/~mihir/papers/kmd5.pdf |title=Keying Hash Functions for Message Authentication |pages=1–15 |first1=Mihir |last1=Bellare |author-link1=Mihir Bellare |first2=Ran |last2=Canetti |first3=Hugo |last3=Krawczyk |year=1996 |citeseerx=10.1.1.134.8430 }}</ref><ref>{{Cite journal|title=MDx-MAC and Building Fast MACs from Hash Functions |year=1995 |first1=Bart |last1=Preneel |author-link1=Bart Preneel |first2=Paul C. |last2=van Oorschot |author-link2=Paul van Oorschot |citeseerx=10.1.1.34.3855 }}</ref><ref>{{Cite journal|title=On the Security of Two MAC Algorithms |year=1995 |first1=Bart |last1=Preneel |author-link1=Bart Preneel |first2=Paul C. |last2=van Oorschot |author-link2=Paul van Oorschot |citeseerx=10.1.1.42.8908 }}</ref>

No known extension attacks have been found against the current HMAC specification which is defined as '''H'''(''key'' ∥ '''H'''(''key'' ∥ ''message'')) because the outer application of the hash function masks the intermediate result of the internal hash. The values of ''ipad'' and ''opad'' are not critical to the security of the algorithm, but were defined in such a way to have a large [[Hamming distance]] from each other and so the inner and outer keys will have fewer bits in common. The security reduction of HMAC does require them to be different in at least one bit.{{citation needed|date=June 2015}}

The [[Keccak]] hash function, that was selected by [[NIST]] as the [[SHA-3]] competition winner, doesn't need this nested approach and can be used to generate a MAC by simply prepending the key to the message, as it is not susceptible to length-extension attacks.<ref>{{cite web
| url=https://keccak.team/keccak_strengths.html
| title=Keccak Team – Design and security
| quote=Unlike SHA-1 and SHA-2, Keccak does not have the length-extension weakness, hence does not need the HMAC nested construction. Instead, MAC computation can be performed by simply prepending the message with the key.
| author=Keccak team
| access-date=31 October 2019}}
</ref>

==Security==
The cryptographic strength of the HMAC depends upon the size of the secret key that is used and the security of the underlying hash function used. It has been proven that the security of an HMAC construction is directly related to security properties of the hash function used. The most common attack against HMACs is brute force to uncover the secret key. HMACs are substantially less affected by collisions than their underlying hashing algorithms alone.<ref name=":1" /><ref>{{cite web |author=Schneier |first=Bruce |date=August 2005 |title=SHA-1 Broken |url=http://www.schneier.com/blog/archives/2005/02/sha1_broken.html |access-date=9 January 2009 |quote=''although it doesn't affect applications such as HMAC where collisions aren't important''}}
</ref><ref name=rfc2104.6>{{Ref RFC|2104|ref=no|section=6|quote=The strongest attack known against HMAC is based on the frequency of collisions for the hash function H ("birthday attack") [PV,BCK2], and is totally impractical for minimally reasonable hash functions.}}</ref>
In particular, Mihir Bellare proved that HMAC is a [[Pseudorandom function family|pseudo-random function]] (PRF) under the sole assumption that the compression function is a PRF.<ref>{{cite conference
| first=Mihir
| last=Bellare
| title=New Proofs for NMAC and HMAC: Security without Collision-Resistance
| book-title=Journal of Cryptology
| url=https://eprint.iacr.org/2006/043.pdf
| quote=This paper proves that HMAC is a [[Pseudo-random function|PRF]] under the sole assumption that the compression function is a PRF. This recovers a proof based guarantee since no known attacks compromise the pseudorandomness of the compression function, and it also helps explain the resistance-to-attack that HMAC has shown even when implemented with hash functions whose (weak) collision resistance is compromised.
| access-date=2021-12-15}}
</ref> Therefore, HMAC-MD5 does not suffer from the same weaknesses that have been found in MD5.{{Ref RFC|6151}}

RFC 2104 requires that "keys longer than ''B'' bytes are first hashed using ''H''" which leads to a confusing pseudo-collision: if the key is longer than the hash block size (e.g. 64 bytes for SHA-1), then <code>HMAC(k, m)</code> is computed as <code>HMAC(H(k), m)</code>. This property is sometimes raised as a possible weakness of HMAC in password-hashing scenarios: it has been demonstrated that it's possible to find a long ASCII string and a random value whose hash will be also an ASCII string, and both values will produce the same HMAC output.<ref>{{Cite web|url=https://mathiasbynens.be/notes/pbkdf2-hmac|title=PBKDF2+HMAC hash collisions explained · Mathias Bynens|website=mathiasbynens.be|access-date=2019-08-07}}</ref><ref>{{Cite web|url=https://pthree.org/2016/07/29/breaking-hmac/|title=Aaron Toponce : Breaking HMAC|language=en-US|access-date=2019-08-07}}</ref><ref>{{Cite web|url=https://www.rfc-editor.org/errata/eid4809|title=RFC 2104 Errata Held for Document Update · Erdem Memisyazici|website=www.rfc-editor.org|access-date=2016-09-23}}</ref>

In 2006, [[Jongsung Kim]], [[Alex Biryukov]], [[Bart Preneel]], and [[Seokhie Hong]] showed how to distinguish HMAC with reduced versions of MD5 and SHA-1 or full versions of [[HAVAL]], [[MD4]], and [[SHA-1#SHA-0|SHA-0]] from a [[random function]] or HMAC with a random function. Differential distinguishers allow an attacker to devise a forgery attack on HMAC. Furthermore, differential and rectangle distinguishers can lead to [[preimage attack|second-preimage attacks]]. HMAC with the full version of MD4 can be [[forgery (Cryptography)|forged]] with this knowledge. These attacks do not contradict the security proof of HMAC, but provide insight into HMAC based on existing cryptographic hash functions.<ref>
{{cite journal

| journal=SCN 2006

| publisher=Springer-Verlag

| last = Jongsung
| first = Kim |author2=Biryukov, Alex |author3=Preneel, Bart |author4=Hong, Seokhie
| year = 2006
| title = On the Security of HMAC and NMAC Based on HAVAL, MD4, MD5, SHA-0 and SHA-1
| url=http://eprint.iacr.org/2006/187.pdf
}}</ref>

In 2009, [[Xiaoyun Wang]] ''et al.'' presented a distinguishing attack on HMAC-MD5 without using related keys. It can distinguish an instantiation of HMAC with MD5 from an instantiation with a random function with 2<sup>97</sup> queries with probability 0.87.<ref>
{{cite journal
| last = Wang
| first = Xiaoyun|author2=Yu, Hongbo |author3=Wang, Wei |author4=Zhang, Haina |author5=Zhan, Tao
| year = 2009
| title = Cryptanalysis on HMAC/NMAC-MD5 and MD5-MAC
| url=https://www.iacr.org/archive/eurocrypt2009/54790122/54790122.pdf
| access-date=15 June 2015
}}</ref>

In 2011 an informational RFC 6151 was published to summarize security considerations in [[MD5]] and HMAC-MD5. For HMAC-MD5 the RFC summarizes that – although the security of the [[MD5]] hash function itself is severely compromised – the currently known ''"attacks on HMAC-MD5 do not seem to indicate a practical vulnerability when used as a message authentication code"'', but it also adds that ''"for a new protocol design, a ciphersuite with HMAC-MD5 should not be included"''.{{Ref RFC|6151}}

In May 2011, RFC 6234 was published detailing the abstract theory and source code for SHA-based HMACs.{{Ref RFC|6234}}

==Examples==
Here are some HMAC values, assuming 8-bit ASCII for the input and hexadecimal encoding for the output:

<pre>
HMAC_MD5("key", "The quick brown fox jumps over the lazy dog")    = 80070713463e7749b90c2dc24911e275

HMAC_SHA1("key", "The quick brown fox jumps over the lazy dog")   = de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9

HMAC_SHA256("key", "The quick brown fox jumps over the lazy dog") = f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8

HMAC_SHA512("key", "The quick brown fox jumps over the lazy dog") = b42af09057bac1e2d41708e48a902e09b5ff7f12ab428a4fe86653c73dd248fb82f948a549f7b791a5b41915ee4d1ec3935357e4e2317250d0372afa2ebeeb3a
</pre>

==See also==
* [[HMAC-based one-time password]]

==References==
{{reflist}}

==External links==
* [https://codebeautify.org/hmac-generator Online HMAC Generator / Tester Tool]
* [http://csrc.nist.gov/publications/fips/fips198-1/FIPS-198-1_final.pdf FIPS PUB 198-1, ''The Keyed-Hash Message Authentication Code (HMAC)'']
* [http://www.ouah.org/ogay/hmac/ C HMAC implementation]
* [https://docs.python.org/library/hmac.html Python HMAC implementation]
* [http://docs.oracle.com/javase/1.5.0/docs/guide/security/jce/JCERefGuide.html#HmacEx Java implementation]
* [https://github.com/RustCrypto/MACs/tree/master/hmac Rust HMAC implementation]

{{Cryptography navbox|hash}}
{{Authority control}}

{{DEFAULTSORT:Hmac}}
[[Category:Message authentication codes]]
[[Category:Hashing]]