README.rst
1HKDF - HMAC Key Derivation Function
2===================================
3
4This module implements the HMAC Key Derivation function, defined at
5
6 http://tools.ietf.org/html/draft-krawczyk-hkdf-01
7
8There are two interfaces: a functional interface, with separate extract
9and expand functions as defined in the draft RFC, and a wrapper class for
10these functions.
11
12Functional interface
13--------------------
14
15To use the functional interface, pass the pseudorandom key generated
16by hmac_extract([salt], [input key material]) to hmac_expand(...).
17``salt`` should be a random, non-secret, site-specific string, but may be
18set to None. See section 3.1 of the HKDF draft for more details.
19
20In addition to the PRK output by hmac_extract, hmac_expand takes an
21``info`` argument, which permits generating multiple keys based on the
22same PRK, and a ``length`` argument, which defines the number of bytes
23of output key material to generate. ``length`` must be less than or equal
24to 255 time the block size, in bytes, of the hash function being used.
25See section 3.2 of the HKDF draft for more information on using the ``info``
26argument.
27
28The hash function to use can be specified for both hmac_extract and
29hmac_expand as the ``hash`` kw argument, and defaults to SHA-256 as implemented
30by the hashlib module. It must be the same for both extracting and expanding.
31
32Example::
33
34 prk = hkdf_extract("8e94ef805b93e683ff18".decode("hex"), "asecretpassword")
35 key = hkdf_expand(prk, "context1", 16)
36
37``Hkdf`` wrapper class
38----------------------
39
40To use the wrapper class, instantiate the Hkdf() class with a salt, input
41key material, and optionally, a hash function. You may then call
42expand([info], [length]) on the Hkdf instance to generate output key
43material::
44
45 kdf = Hkdf("8e94ef805b93e683ff18".decode("hex"), "asecretpassword")
46 key = kdf.expand("context1", 16)
47
48HKDF-Extract and HKDF-Expand definitions from the draft RFC
49-----------------------------------------------------------
50
51> Step 1: Extract
52>
53> PRK = HKDF-Extract(salt, IKM)
54>
55> Options:
56> Hash a hash function; HashLen denotes the length of the
57> hash function output in octets
58> Inputs:
59> salt optional salt value (a non-secret random value);
60> if not provided, it is set to a string of HashLen zeros.
61> IKM input keying material
62> Output:
63> PRK a pseudo-random key (of HashLen octets)
64>
65> The output PRK is calculated as follows:
66>
67> PRK = HMAC-Hash(salt, IKM)
68>
69> Step 2: Expand
70>
71> OKM = HKDF-Expand(PRK, info, L)
72>
73> Options:
74> Hash a hash function; HashLen denotes the length of the
75> hash function output in octets
76> Inputs:
77> PRK a pseudo-random key of at least HashLen octets
78> (usually, the output from the Extract step)
79> info optional context and application specific information
80> (can be a zero-length string)
81> L length of output keying material in octets
82> (<= 255*HashLen)
83> Output:
84> OKM output keying material (of L octets)
85>
86> The output OKM is calculated as follows:
87>
88> N = ceil(L/HashLen)
89> T = T(1) | T(2) | T(3) | ... | T(N)
90> OKM = first L octets of T
91>
92> where:
93> T(0) = empty string (zero length)
94> T(1) = HMAC-Hash(PRK, T(0) | info | 0x01)
95> T(2) = HMAC-Hash(PRK, T(1) | info | 0x02)
96> T(3) = HMAC-Hash(PRK, T(2) | info | 0x03)
97> ...
98>
99> (where the constant concatenated to the end of each T(n) is a
100> single octet.)
101
102Changelog
103---------
104
105- 0.0.3 – Move documentation from module docstring to README.rst
106- 0.0.2 – Python 3.3, 3.4 support
107- 0.0.1 – Initial release
108
109Please report any bugs at
110
111 https://www.github.com/casebeer/python-hkdf
112
113
114