From 4e8aaf98c57a4bfff387dcde2c241f2c23f9eda2 Mon Sep 17 00:00:00 2001 From: Jim Schaad Date: Mon, 7 Mar 2016 15:15:46 -0800 Subject: [PATCH 1/2] Changes to switch from NIST to IETF version of HKDF These are the top level changes to switch from using the HKDF-CTR defined in NIST SP 800-108 to the IETF RFC 5869 HKDF function. Both salt and info have been defined as being optional as per the IETF algorithm. --- spec/Overview-WebCryptoAPI.xml | 117 +++++++++++++-------------------- 1 file changed, 44 insertions(+), 73 deletions(-) diff --git a/spec/Overview-WebCryptoAPI.xml b/spec/Overview-WebCryptoAPI.xml index 3bda45b..e960645 100644 --- a/spec/Overview-WebCryptoAPI.xml +++ b/spec/Overview-WebCryptoAPI.xml @@ -3547,7 +3547,7 @@ dictionary CryptoKeyPair { - HKDF-CTR + HKDF @@ -14570,18 +14570,16 @@ required HashAlgorithmIdentifier -
-

HKDF-CTR

-
+
+

HKDF

+

Description

This section is non-normative.

- The "HKDF-CTR" algorithm identifier is used to + The "HKDF" algorithm identifier is used to perform key derivation using the extraction-then-expansion approach described in - [NIST SP800-56C], using HMAC in counter mode, and - using the SHA hash functions defined in this specification - as described in Section 5.1 of - [NIST SP800-108]. + [RFC 5869] and + using the SHA hash functions defined in this specification.

Other specifications @@ -14589,11 +14587,11 @@ required HashAlgorithmIdentifier

-
+

Registration

The recognized algorithm name - for this algorithm is "HKDF-CTR". + for this algorithm is "HKDF".

@@ -14606,7 +14604,7 @@ required HashAlgorithmIdentifier - + @@ -14617,25 +14615,25 @@ required HashAlgorithmIdentifier - +
deriveBitsHkdfCtrParamsHkdfParams ArrayBuffer
Get key length NoneInteger or nullnull
-
-

HkdfCtrParams dictionary

+
+

HkdfParams dictionary

-dictionary HkdfCtrParams : Algorithm { -// The algorithm to use with HMAC (e.g.: SHA-256) -required HashAlgorithmIdentifier hash; -// A bit string that corresponds to the label that identifies the purpose for the derived keying material. -required BufferSource label; -// A bit string that corresponds to the context of the key derivation, as described in Section 5 of [NIST SP800-108] -required BufferSource context; +dictionary HkdfParams : Algorithm { + // The algorithm to use with HMAC (e.g.: SHA-256) + required HashAlgorithmIdentifier hash; + // A bit string that corresponds to the salt used in the extract step. + optional BufferSource salt; + // A bit string that corresponds to the context and application specific context for the derived keying material. + optional BufferSource info; };
-
+

Operations

Derive Bits
@@ -14648,7 +14646,7 @@ required BufferSource context;

  • - If the hash member of + If the hash member of normalizedAlgorithm does not describe a recognized algorithm that supports the digest operation, then throw a @@ -14657,58 +14655,42 @@ required BufferSource context;

  • - Let extractKey be a key equal to n zero bits where - n is the size of the output of the hash function described by the - hash member of - normalizedAlgorithm. -

    -
    • -
  • -

    - Let prf be the MAC Generation function described in Section 4 of - [FIPS PUB 198-1] using the hash function - described by the hash member of - normalizedAlgorithm. -

    -
    • -
  • -

    - Let keyDerivationKey be the result of performing prf - using extractKey as the key and the secret represented by [[keyDerivationKey be the secret represented by [[handle]] internal slot of key as the message.

  • - Let result be the result of performing the KDF in counter - mode operation described in Section 5.1 of - [NIST SP800-108] using: + Let result be the result of performing the HKDF extract and then + the HKDF expand step described in Section 2 of + [RFC 5869] using:

    • - prf as the Pseudo-Random Function, PRF, + the hash member of + normalizedAlgorithm as Hash,

    • - keyDerivationKey as the Key derivation key, - KI, + keyDerivationKey as the input keying material, + IKM,

    • - the contents of the label member of - normalizedAlgorithm as Label, + if present the contents of the salt member of + normalizedAlgorithm as salt,

    • - the contents of the context member of - normalizedAlgorithm as Context, + if present the contents of the info member of + normalizedAlgorithm as info,

    • @@ -14716,17 +14698,6 @@ required BufferSource context; length as the value of L,

      • -
    • -

      - 32 as the value of r, and -

      -
      • -
    • -

      - the 32-bit little-endian binary encoding of length - as the encoded length value [L]2. -

      -
  • @@ -14786,7 +14757,7 @@ required BufferSource context;

  • Set the name attribute of - algorithm to "HKDF-CTR". + algorithm to "HKDF".

  • @@ -15365,12 +15336,6 @@ window.crypto.subtle.generateKey(aesAlgorithmKeyGen, false, ["encrypt"]).then( NIST Special Publication 800-56C: Recommendation for Key Derivation through Extraction-then-Expansion, November 2011, NIST. - -
    NIST SP 800-108
    -
    - - NIST Special Publication 800-108: Recommendation for Key Derivation Using - Pseudorandom Functions (Revised), October 2009, NIST.
    RFC 2119
    @@ -15422,7 +15387,13 @@ window.crypto.subtle.generateKey(aesAlgorithmKeyGen, false, ["encrypt"]).then( Elliptic Curve Cryptography Subject Public Key Information, S. Turner, D. Brown, K. Yiu, R. Housley, T. Polk. IETF. -
    + +
    RFC 5869
    +
    + HMAC-based Extract-and-Expand Key + Derivation Function (HKDF)", + H. Krawczyk, P. Eronen. IETF. +
    RFC 5915
    Elliptic Curve Private Key Structure From 32a8ee4e6d8a8e60baf7c229588446a8197652b6 Mon Sep 17 00:00:00 2001 From: Jim Schaad Date: Wed, 24 Aug 2016 15:10:39 -0700 Subject: [PATCH 2/2] Make Salt and info required Change so that salt and info are now required fields --- spec/Overview-WebCryptoAPI.xml | 6 +++--- spec/Overview.html | 10 +++++----- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/spec/Overview-WebCryptoAPI.xml b/spec/Overview-WebCryptoAPI.xml index 4d51396..c9f9ea8 100644 --- a/spec/Overview-WebCryptoAPI.xml +++ b/spec/Overview-WebCryptoAPI.xml @@ -14732,7 +14732,7 @@ dictionary HmacKeyGenParams : HkdfParams : Algorithm { // The algorithm to use with HMAC (e.g.: SHA-256) required HashAlgorithmIdentifier hash; - // A bit string that corresponds to the salt used in the extract step. + // A bit string that corresponds to the salt used in the extract step. required BufferSource salt; // A bit string that corresponds to the context and application specific context for the derived keying material. required BufferSource info; @@ -14787,14 +14787,14 @@ dictionary HkdfParams :

  • - if present the contents of the the contents of the salt member of normalizedAlgorithm as salt,

  • - if present the contents of the the contents of the info member of normalizedAlgorithm as info,

    diff --git a/spec/Overview.html b/spec/Overview.html index 1a0cb31..44d4970 100644 --- a/spec/Overview.html +++ b/spec/Overview.html @@ -28,7 +28,7 @@ -

    Web Cryptography API

    W3C Editor’s Draft NaN @@ 2016

    Latest Editor’s Draft:
    http://w3c.github.io/webcrypto/Overview.html
    Latest Published Version:
    http://www.w3.org/TR/WebCryptoAPI/
    Previous Version(s):
    https://dvcs.w3.org/hg/webcrypto-api/raw-file/0fe9b34c13fb/spec/Overview.html
    Editor:
    Mark Watson, Netflix <watsonm@netflix.com>
    Participate:
    We are on GitHub. +

    Web Cryptography API

    W3C Editor’s Draft 24 August 2016

    Latest Editor’s Draft:
    http://w3c.github.io/webcrypto/Overview.html
    Latest Published Version:
    http://www.w3.org/TR/WebCryptoAPI/
    Previous Version(s):
    https://dvcs.w3.org/hg/webcrypto-api/raw-file/0fe9b34c13fb/spec/Overview.html
    Editor:
    Mark Watson, Netflix <watsonm@netflix.com>
    Participate:
    We are on GitHub.
    Send feedback to public-webcrypto@w3.org (archives).
    File a bug @@ -60,7 +60,7 @@

    Status of this Document

    report can be found in the W3C technical reports index at http://www.w3.org/TR/.

    - This document is the NaN @@ 2016 Editor’s Draft of the + This document is the 24 August 2016 Editor’s Draft of the Web Cryptography API specification. Please send comments about this document to @@ -14255,7 +14255,7 @@

    31.3. HkdfParams dictionary

    dictionary HkdfParams : Algorithm { // The algorithm to use with HMAC (e.g.: SHA-256) required HashAlgorithmIdentifier hash; - // A bit string that corresponds to the salt used in the extract step. + // A bit string that corresponds to the salt used in the extract step. required BufferSource salt; // A bit string that corresponds to the context and application specific context for the derived keying material. required BufferSource info; @@ -14309,13 +14309,13 @@

    31.4. Operations

  • - if present the contents of the salt member of + the contents of the salt member of normalizedAlgorithm as salt,

  • - if present the contents of the info member of + the contents of the info member of normalizedAlgorithm as info,