Skip to content

Commit

Permalink
Fix #16: Changes to switch from NIST to IETF version of HKDF
Browse files Browse the repository at this point in the history
  • Loading branch information
@jimsch @mwatson2
jimsch authored and mwatson2 committed Aug 29, 2016
1 parent 2f02a2d commit 36bc668
Show file tree
Hide file tree
Showing 2 changed files with 81 additions and 123 deletions.
101 changes: 40 additions & 61 deletions spec/Overview-WebCryptoAPI.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3491,7 +3491,7 @@ dictionary <dfn id="dfn-CryptoKeyPair">CryptoKeyPair</dfn> {
<td />
</tr>
<tr>
<td><a href="#hkdf-ctr">HKDF-CTR</a></td>
<td><a href="#hkdf">HKDF</a></td>
<td />
<td />
<td />
Expand Down Expand Up @@ -14659,30 +14659,28 @@ dictionary <dfn id="dfn-HmacKeyGenParams">HmacKeyGenParams</dfn> : <a href="#dfn
</div>
</div>

<div id="hkdf-ctr" class="section">
<h3>HKDF-CTR</h3>
<div id="hkdf-ctr-description" class="section">
<div id="hkdf" class="section">
<h3>HKDF</h3>
<div id="hkdf-description" class="section">
<h4>Description</h4>
<p class="norm">This section is non-normative.</p>
<p>
The <code>"HKDF-CTR"</code> algorithm identifier is used to
The <code>"HKDF"</code> algorithm identifier is used to
perform key derivation using the extraction-then-expansion approach described in
[<a href="#SP800-56C">NIST SP800-56C</a>], using HMAC in counter mode, and
using the SHA hash functions defined in this specification
as described in Section 5.1 of
[<a href="#SP800-108">NIST SP800-108</a>].
[<a href="#RFC5869">RFC 5869</a>] and
using the SHA hash functions defined in this specification.
</p>
<p>
<a href="#dfn-applicable-specification">Other specifications</a>
may specify the use of additional hash algorithms with HKDF.
Such specifications must define the digest operation for the additional hash algorithms.
</p>
</div>
<div id="hkdf-ctr-registration" class="section">
<div id="hkdf-registration" class="section">
<h4>Registration</h4>
<p>
The <a href="#recognized-algorithm-name">recognized algorithm name</a>
for this algorithm is <code>"HKDF-CTR"</code>.
for this algorithm is <code>"HKDF"</code>.
</p>
<table>
<thead>
Expand All @@ -14695,7 +14693,7 @@ dictionary <dfn id="dfn-HmacKeyGenParams">HmacKeyGenParams</dfn> : <a href="#dfn
<tbody>
<tr>
<td>deriveBits</td>
<td><a href="#dfn-HkdfCtrParams">HkdfCtrParams</a></td>
<td><a href="#dfn-HkdfParams">HkdfParams</a></td>
<td><a href="#dfn-ArrayBuffer">ArrayBuffer</a></td>
</tr>
<tr>
Expand All @@ -14706,25 +14704,25 @@ dictionary <dfn id="dfn-HmacKeyGenParams">HmacKeyGenParams</dfn> : <a href="#dfn
<tr>
<td>Get key length</td>
<td>None</td>
<td>Integer or null</td>
<td>null</td>
</tr>
</tbody>
</table>
</div>
<div id="hkdf-ctr-params" class="section">
<h4>HkdfCtrParams dictionary</h4>
<div id="hkdf-params" class="section">
<h4>HkdfParams dictionary</h4>
<x:codeblock language="idl">
dictionary <dfn id="dfn-HkdfCtrParams">HkdfCtrParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
dictionary <dfn id="dfn-HkdfParams">HkdfParams</dfn> : <a href="#dfn-Algorithm">Algorithm</a> {
<span class="comment">// The algorithm to use with HMAC (e.g.: <a href="#alg-sha-256">SHA-256</a>)</span>
required <a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a> <dfn id="dfn-HkdfCtrParams-hash">hash</dfn>;
<span class="comment">// A bit string that corresponds to the label that identifies the purpose for the derived keying material.</span>
required BufferSource <dfn id="dfn-HkdfCtrParams-label">label</dfn>;
<span class="comment">// A bit string that corresponds to the context of the key derivation, as described in Section 5 of [<a href="#SP800-108">NIST SP800-108</a>]</span>
required BufferSource <dfn id="dfn-HkdfCtrParams-context">context</dfn>;
required <a href="#dfn-HashAlgorithmIdentifier">HashAlgorithmIdentifier</a> <dfn id="dfn-HkdfParams-hash">hash</dfn>;
<span class="comment">// A bit string that corresponds to the salt used in the extract step.</span>
required BufferSource <dfn id="dfn-HkdfParams-salt">salt</dfn>;
<span class="comment">// A bit string that corresponds to the context and application specific context for the derived keying material.</span>
required BufferSource <dfn id="dfn-HkdfParams-info">info</dfn>;
};
</x:codeblock>
</div>
<div id="hkdf2-ctr-operations" class="section">
<div id="hkdf2-operations" class="section">
<h4>Operations</h4>
<dl>
<dt>Derive Bits</dt>
Expand All @@ -14745,68 +14743,49 @@ dictionary <dfn id="dfn-HkdfCtrParams">HkdfCtrParams</dfn> : <a href="#dfn-Algor
</li>
<li>
<p>
Let <var>prf</var> be the MAC Generation function described in Section 4 of
[<a href="#fips-pub-198-1">FIPS PUB 198-1</a>] using the hash function
described by the <a href="#dfn-HkdfCtrParams-hash">hash</a> member of
<var>normalizedAlgorithm</var>.
</p>
</li>
<li>
<p>
Let <var>keyDerivationKey</var> be the result of performing <var>prf</var>
using <var>extractKey</var> as the key and the secret represented by [[<a
Let <var>keyDerivationKey</var> be the secret represented by [[<a
href="#dfn-CryptoKey-slot-handle">handle</a>]] internal slot of <var>key</var>
as the message.
</p>
</li>
<li>
<p>
Let <var>result</var> be the result of performing the KDF in counter
mode operation described in Section 5.1 of
[<a href="#SP800-108">NIST SP800-108</a>] using:
Let <var>result</var> be the result of performing the HKDF extract and then
the HKDF expand step described in Section 2 of
[<a href="#RFC5869">RFC 5869</a>] using:
</p>
<ul>
<li>
<p>
<var>prf</var> as the Pseudo-Random Function, <var>PRF</var>,
the <a href="#dfn-HkdfParams-hash">hash</a> member of
<var>normalizedAlgorithm</var> as <var>Hash</var>,
</p>
</li>
<li>
<p>
<var>keyDerivationKey</var> as the Key derivation key,
<var>K<sub>I</sub></var>,
<var>keyDerivationKey</var> as the input keying material,
<var>IKM</var>,
</p>
</li>
<li>
<p>
<a href="#concept-contents-of-arraybuffer">the contents of</a> the <a
href="#dfn-HkdfCtrParams-label">label</a> member of
<var>normalizedAlgorithm</var> as <var>Label</var>,
href="#dfn-HkdfParams-salt">salt</a> member of
<var>normalizedAlgorithm</var> as <var>salt</var>,
</p>
</li>
<li>
<p>
<a href="#concept-contents-of-arraybuffer">the contents of</a> the <a
href="#dfn-HkdfCtrParams-label">context</a> member of
<var>normalizedAlgorithm</var> as <var>Context</var>,
href="#dfn-HkdfParams-info">info</a> member of
<var>normalizedAlgorithm</var> as <var>info</var>,
</p>
</li>
<li>
<p>
<var>length</var> as the value of <var>L</var>,
</p>
</li>
<li>
<p>
32 as the value of <var>r</var>, and
</p>
</li>
<li>
<p>
the 32-bit little-endian binary encoding of <var>length</var>
as the encoded length value [<var>L</var>]<sub>2</sub>.
</p>
</li>
</ul>
</li>
<li>
Expand Down Expand Up @@ -14879,7 +14858,7 @@ dictionary <dfn id="dfn-HkdfCtrParams">HkdfCtrParams</dfn> : <a href="#dfn-Algor
<li>
<p>
Set the <a href="#dfn-KeyAlgorithm-name">name</a> attribute of
<var>algorithm</var> to <code>"HKDF-CTR"</code>.
<var>algorithm</var> to <code>"HKDF"</code>.
</p>
</li>
<li>
Expand Down Expand Up @@ -15389,12 +15368,6 @@ window.crypto.subtle.generateKey(aesAlgorithmKeyGen, false, ["encrypt"]).then(
<cite><a href="http://csrc.nist.gov/publications/nistpubs/800-56C/SP-800-56C.pdf">
NIST Special Publication 800-56C: Recommendation for Key Derivation through
Extraction-then-Expansion</a></cite>, November 2011, NIST.
</dd>
<dt id="SP800-108">NIST SP 800-108</dt>
<dd>
<cite><a href="http://csrc.nist.gov/publications/nistpubs/800-108/sp800-108.pdf">
NIST Special Publication 800-108: Recommendation for Key Derivation Using
Pseudorandom Functions (Revised)</a></cite>, October 2009, NIST.
</dd>
<dt id="RFC2119">RFC 2119</dt>
<dd>
Expand Down Expand Up @@ -15446,7 +15419,13 @@ window.crypto.subtle.generateKey(aesAlgorithmKeyGen, false, ["encrypt"]).then(
<cite><a href="http://www.ietf.org/rfc/rfc5480.txt">Elliptic Curve Cryptography Subject
Public Key Information</a></cite>,
S. Turner, D. Brown, K. Yiu, R. Housley, T. Polk. IETF.
</dd>
</dd>
<dt id="RFC5869">RFC 5869</dt>
<dd>
<cite><a href="https://www.ietf.org/rfc/rfc5869.txt">HMAC-based Extract-and-Expand Key
Derivation Function (HKDF)"</a></cite>,
H. Krawczyk, P. Eronen. IETF.
</dd>
<dt id="RFC5915">RFC 5915</dt>
<dd>
<cite><a href="http://www.ietf.org/rfc/rfc5915.txt">Elliptic Curve Private Key Structure
Expand Down
Loading

0 comments on commit 36bc668

Please sign in to comment.