View source for HKDF

{{Short description|Key derivation function based on an HMAC}}
'''HKDF''' is a simple [[Key derivation function|key derivation function]] (KDF) based on the [[HMAC]] [[Message authentication code|message authentication code]].<ref name="iacr" /><ref name=rfc/> It was initially proposed by its authors as a building block in various protocols and applications, as well as to discourage the proliferation of multiple KDF mechanisms.<ref name=rfc/> The main approach HKDF follows is the "extract-then-expand" paradigm, where the KDF logically consists of two modules: the first stage takes the input keying material and "extracts" from it a fixed-length pseudorandom key, and then the second stage "expands" this key into several additional pseudorandom keys (the output of the KDF).<ref name=rfc/>

It can be used, for example, to convert shared secrets exchanged via Diffie–Hellman into key material suitable for use in encryption, integrity checking or authentication.<ref name=iacr/>

It is formally described in RFC 5869.<ref name=rfc>{{cite journal |title=RFC 5869 |last1=Krawczyk |first1=H. |last2=Eronen |first2=P. |url=https://tools.ietf.org/html/rfc5869 |website=Internet Engineering Task Force |date=May 2010|doi=10.17487/RFC5869 }}</ref> One of its authors also described the algorithm in a companion paper in 2010.<ref name=iacr>{{cite journal |last=Krawczyk |first=Hugo |title=Cryptographic Extraction and Key Derivation: The HKDF Scheme |journal=Cryptology ePrint Archive |publisher=International Association for Cryptologic Research |date=2010 |url=https://eprint.iacr.org/2010/264}}</ref>

NIST SP800-56Cr2<ref>{{cite journal|url=https://doi.org/10.6028/NIST.SP.800-56Cr2 |title=NIST Special Publication 800-56C: Recommendation for Key-Derivation Methods in Key-Establishment Schemes |author1=Elaine Barker|author2=Lily Chen|author3=Richard Davis|date=August 2020|doi=10.6028/NIST.SP.800-56Cr2 }}</ref> specifies a parameterizable extract-then-expand scheme, noting that RFC 5869 HKDF is a version of it and citing its paper<ref name=iacr/> for the rationale for the recommendations' extract-and-expand mechanisms.

There are implementations of HKDF for [[C Sharp (programming language)|C#]], [[Go (programming language)|Go]],<ref>{{cite web|url=https://pkg.go.dev/golang.org/x/crypto/hkdf|title=package hkdf |website=pkg.go.dev}}</ref> [[Java (programming language)|Java]],<ref>{{cite web|url=https://github.com/patrickfav/hkdf|title=A standalone Java 7 implementation of HMAC-based key derivation function |website=github.com|date=27 September 2022 }}</ref> [[JavaScript]],<ref>{{cite web|url=https://www.npmjs.com/package/futoin-hkdf|title=Node.js implementation of RFC5869: HMAC-based Extract-and-Expand Key Derivation Function |website=npmjs.com|date=30 July 2023 }}</ref> [[Perl]], [[Organization:PHP|PHP]],<ref>{{cite web|url=https://www.php.net/manual/en/function.hash-hkdf.php|title=hash_hkdf — Generate a HKDF key derivation of a supplied key input |website=php.net}}</ref> [[Python (programming language)|Python]],<ref>{{cite web|url=https://github.com/casebeer/python-hkdf|title=HMAC-based Extract-and-Expand Key Derivation Function (HKDF) implemented in Python. |website=github.com|date=17 March 2022 }}</ref> [[Ruby (programming language)|Ruby]], [[Rust (programming language)|Rust]],<ref>{{cite web|url=https://docs.rs/ring/0.17.5/ring/hkdf/index.html|title=Module ring::hkdf|date=19 October 2023|access-date=25 October 2023}}</ref> and other [[Programming language|programming language]]s.

==Mechanism==
HKDF is the composition of two functions, HKDF-Extract and HKDF-Expand: HKDF(salt, IKM, info, length) = HKDF-Expand(HKDF-Extract(salt, IKM), info, length)

===HKDF-Extract===

HKDF-Extract takes "input key material" (IKM) such as a shared secret generated using Diffie-Hellman, and an optional [[Salt (cryptography)|salt]], and generates a cryptographic key called the PRK ("pseudorandom key"). This acts as a "randomness extractor", taking a potentially non-uniform value of high min-[[Entropy (information theory)|entropy]] and generating a value indistinguishable from a uniform random value.

HKDF-Extract is the output of HMAC with the "salt" as the key and the "IKM" as the message.

===HKDF-Expand===

HKDF-Expand takes the PRK, some "info", and a length, and generates output of the desired length. HKDF-Expand acts as a [[Pseudorandom function family|pseudorandom function]] keyed on PRK. This means that multiple outputs can be generated from a single IKM value by using different values for the "info" field.

HKDF-Expand works by repeatedly calling HMAC using the PRK as the key and the "info" field as the message. The HMAC inputs are chained by prepending the previous hash block to the "info" field and appending with an incrementing 8-bit counter.<ref name=rfc/>

== Example: Python implementation ==
<source lang="python3">
#!/usr/bin/env python3

import hashlib
import hmac

hash_function = hashlib.sha256  # RFC5869 also includes SHA-1 test vectors


def hmac_digest(key: bytes, data: bytes) -> bytes:
    return hmac.new(key, data, hash_function).digest()


def hkdf_extract(salt: bytes, ikm: bytes) -> bytes:
    if len(salt) == 0:
        salt = bytes([0] * hash_function().digest_size)
    return hmac_digest(salt, ikm)


def hkdf_expand(prk: bytes, info: bytes, length: int) -> bytes:
    t = b""
    okm = b""
    i = 0
    while len(okm) < length:
        i += 1
        t = hmac_digest(prk, t + info + bytes([i]))
        okm += t
    return okm[:length]


def hkdf(salt: bytes, ikm: bytes, info: bytes, length: int) -> bytes:
    prk = hkdf_extract(salt, ikm)
    return hkdf_expand(prk, info, length)


okm = hkdf(
    salt=bytes.fromhex("000102030405060708090a0b0c"),
    ikm=bytes.fromhex("0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b"),
    info=bytes.fromhex("f0f1f2f3f4f5f6f7f8f9"),
    length=42,
)
assert okm == bytes.fromhex(
    "3cb25f25faacd57a90434f64d0362f2a2d2d0a90cf1a5a4c5db02d56ecc4c5bf34007208d5b887185865"
)

# Zero-length salt
assert hkdf(
    salt=b"",
    ikm=bytes.fromhex("0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b"),
    info=b"",
    length=42,
) == bytes.fromhex(
    "8da4e775a563c18f715f802a063c5a31b8a11f5c5ee1879ec3454e5f3c738d2d9d201395faa4b61a96c8"
)
</source>

== References ==
{{Reflist}}

== External links ==
{{Cryptography navbox | hash}}

[[Category:Cryptography]]
[[Category:Key derivation functions]]

{{Sourceattribution|HKDF}}