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