Skip to content

Commit

Permalink
Script updating gh-pages from eecf979. [ci skip]
Browse files Browse the repository at this point in the history
  • Loading branch information
ID Bot committed Jan 29, 2025
1 parent 4eaaf34 commit fc71f98
Show file tree
Hide file tree
Showing 3 changed files with 65 additions and 40 deletions.
42 changes: 26 additions & 16 deletions draft-ietf-lamps-pq-composite-kem.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1275,10 +1275,10 @@ <h2 id="name-copyright-notice">
<p id="section-toc.1-1.8.2.1.1"><a href="#section-8.1" class="auto internal xref">8.1</a>.  <a href="#name-underlying-components" class="internal xref">Underlying Components</a></p>
<ul class="compact toc ulBare ulEmpty">
<li class="compact toc ulBare ulEmpty" id="section-toc.1-1.8.2.1.2.1">
<p id="section-toc.1-1.8.2.1.2.1.1"><a href="#section-8.1.1" class="auto internal xref">8.1.1</a>.  <a href="#name-use-of-the-hkdf-based-key-d" class="internal xref">Use of the HKDF-based Key Derivation Function</a></p>
<p id="section-toc.1-1.8.2.1.2.1.1"><a href="#section-8.1.1" class="auto internal xref">8.1.1</a>.  <a href="#name-use-of-the-hkdf-based-key-d" class="internal xref">Use of the HKDF-based Key Derivation Function within CMS</a></p>
</li>
<li class="compact toc ulBare ulEmpty" id="section-toc.1-1.8.2.1.2.2">
<p id="section-toc.1-1.8.2.1.2.2.1"><a href="#section-8.1.2" class="auto internal xref">8.1.2</a>.  <a href="#name-use-of-the-kmac-based-key-d" class="internal xref">Use of the KMAC-based Key Derivation Function</a></p>
<p id="section-toc.1-1.8.2.1.2.2.1"><a href="#section-8.1.2" class="auto internal xref">8.1.2</a>.  <a href="#name-use-of-the-kmac-based-key-d" class="internal xref">Use of the KMAC-based Key Derivation Function within CMS</a></p>
</li>
</ul>
</li>
Expand Down Expand Up @@ -1765,11 +1765,16 @@ <h3 id="name-encapsulation">

4. Encode the ciphertext

ct = mlkemCT || tradCT
ct = mlkemCT || tradCT

5. Combine the KEM secrets and additional context to yield the composite shared secret

ss = KDF(mlkemSS || tradSS || tradCT || tradPK || Domain)
if KDF is "SHA3-256"
ss = SHA3-256(mlkemSS || tradSS || tradCT || tradPK || Domain)
else if KDF is "HKDF"
ss = HKDF-Extract(salt="", IKM=mlkemSS || tradSS || tradCT || tradPK || Domain)
# Note: salt is the empty string (0 octets), which will internally be mapped
# to the zero vector `0x00..00` of the correct input size for the underlying
# hash function as per [RFC 5869].

6. Output composite shared secret key and ciphertext

Expand Down Expand Up @@ -1846,7 +1851,13 @@ <h3 id="name-decapsulation">

5. Combine the KEM secrets and additional context to yield the composite shared secret

ss = KDF(mlkemSS || tradSS || tradCT || tradPK || Domain)
if KDF is "SHA3-256"
ss = SHA3-256(mlkemSS || tradSS || tradCT || tradPK || Domain)
else if KDF is "HKDF"
ss = HKDF-Extract(salt="", IKM=mlkemSS || tradSS || tradCT || tradPK || Domain)
# Note: salt is the empty string (0 octets), which will internally be mapped
# to the zero vector `0x00..00` of the correct input size for the underlying
# hash function as per [RFC 5869].

6. Output composite shared secret key

Expand Down Expand Up @@ -2633,10 +2644,10 @@ <h3 id="name-underlying-components">
</div>
<p id="section-8.1-3">Full specifications for the referenced algorithms can be found either further down in this section, or in <a href="#appdx_components" class="auto internal xref">Appendix B</a>.<a href="#section-8.1-3" class="pilcrow"></a></p>
<p id="section-8.1-4">Note that here we differ slightly from the internal KDF used within the KEM combiner in <a href="#sec-alg-ids" class="auto internal xref">Section 7</a> because <span>[<a href="#RFC9629" class="cite xref">RFC9629</a>]</span> requires that the KDF listed in the KEMRecipientInfo <code>kdf</code> field must have an interface which accepts <code>KDF(IKM, L, info)</code>, so here we need to use KMAC and cannot directly use SHA3. Since we require 256-bits of (2nd) pre-image resistance, we use KMAC256 for the Composite ML-KEM algorithms with internally use SHA3-256, as aligned with Table 3 of <span>[<a href="#SP.800-57pt1r5" class="cite xref">SP.800-57pt1r5</a>]</span>.<a href="#section-8.1-4" class="pilcrow"></a></p>
<div id="use-of-the-hkdf-based-key-derivation-function">
<div id="use-of-the-hkdf-based-key-derivation-function-within-cms">
<section id="section-8.1.1">
<h4 id="name-use-of-the-hkdf-based-key-d">
<a href="#section-8.1.1" class="section-number selfRef">8.1.1. </a><a href="#name-use-of-the-hkdf-based-key-d" class="section-name selfRef">Use of the HKDF-based Key Derivation Function</a>
<a href="#section-8.1.1" class="section-number selfRef">8.1.1. </a><a href="#name-use-of-the-hkdf-based-key-d" class="section-name selfRef">Use of the HKDF-based Key Derivation Function within CMS</a>
</h4>
<p id="section-8.1.1-1">The HMAC-based Extract-and-Expand Key Derivation Function (HKDF) is defined in <span>[<a href="#RFC5869" class="cite xref">RFC5869</a>]</span>.<a href="#section-8.1.1-1" class="pilcrow"></a></p>
<p id="section-8.1.1-2">The HKDF function is a composition of the HKDF-Extract and HKDF-Expand functions.<a href="#section-8.1.1-2" class="pilcrow"></a></p>
Expand Down Expand Up @@ -2672,10 +2683,10 @@ <h4 id="name-use-of-the-hkdf-based-key-d">
<p id="section-8.1.1-6">HKDF may be used with different hash functions, including SHA-256 <span>[<a href="#FIPS.180-4" class="cite xref">FIPS.180-4</a>]</span>. The object identifier id-alg-hkdf-with-sha256 is defined in <span>[<a href="#RFC8619" class="cite xref">RFC8619</a>]</span>, and specifies the use of HKDF with SHA-256. The parameter field MUST be absent when this algorithm identifier is used to specify the KDF for ML-KEM in KemRecipientInfo.<a href="#section-8.1.1-6" class="pilcrow"></a></p>
</section>
</div>
<div id="use-of-the-kmac-based-key-derivation-function">
<div id="use-of-the-kmac-based-key-derivation-function-within-cms">
<section id="section-8.1.2">
<h4 id="name-use-of-the-kmac-based-key-d">
<a href="#section-8.1.2" class="section-number selfRef">8.1.2. </a><a href="#name-use-of-the-kmac-based-key-d" class="section-name selfRef">Use of the KMAC-based Key Derivation Function</a>
<a href="#section-8.1.2" class="section-number selfRef">8.1.2. </a><a href="#name-use-of-the-kmac-based-key-d" class="section-name selfRef">Use of the KMAC-based Key Derivation Function within CMS</a>
</h4>
<p id="section-8.1.2-1">KMAC256-KDF is a KMAC-based KDF specified for use in CMS in <span>[<a href="#I-D.ietf-lamps-cms-sha3-hash" class="cite xref">I-D.ietf-lamps-cms-sha3-hash</a>]</span>. The definition of KMAC is copied here for convenience. Here, KMAC# indicates the use of either KMAC128-KDF or KMAC256-KDF, although only KMAC256 is used in this specification.<a href="#section-8.1.2-1" class="pilcrow"></a></p>
<p id="section-8.1.2-2">KMAC#(K, X, L, S) takes the following parameters:<a href="#section-8.1.2-2" class="pilcrow"></a></p>
Expand Down Expand Up @@ -3969,19 +3980,18 @@ <h3 id="name-fips-certification">
<a href="#appendix-D.1" class="section-number selfRef">D.1. </a><a href="#name-fips-certification" class="section-name selfRef">FIPS Certification</a>
</h3>
<p id="appendix-D.1-1">TODO -- update this once NIST SP 800-227 is published.<a href="#appendix-D.1-1" class="pilcrow"></a></p>
<p id="appendix-D.1-2">EDNOTE At time of writing, it is unclear that the KEM combiner presented in this document would pass a FIPS certification. The SHA3 instantiations should pass under SP 800-56Cr2 Option 1, but the HKDF-SHA2 combinations are technically not allowed under SP 800-56Cr2 even though Option 2 allows HMAC-based constructions, but unfortunately only HKDF-Extract is FIPS-allowed, not HKDF-Expand. The authors have been in contact with NIST to ensure compatibility either by NIST making SP 800-227 more flexible, or by changing this specification to only use HKDF-Extract.<a href="#appendix-D.1-2" class="pilcrow"></a></p>
<p id="appendix-D.1-3">One of the primary design goals of this specification is for the overall composite algorithm to be able to be considered FIPS-approved even when one of the component algorithms is not. Implementers seeking FIPS certification of a Composite ML-KEM algorithm where only one of the component algorithms has been FIPS-validated or FIPS-approved should credit the FIPS-validated component algorithm with full security strength, the non-FIPS-validated component algorithm with zero security, and the overall composite should be considered full strength and thus FIPS-approved.<a href="#appendix-D.1-3" class="pilcrow"></a></p>
<p id="appendix-D.1-4">The authors wish to note that this gives composite algorithms great future utility both for future cryptographic migrations as well as bridging across jurisdictions; for example defining composite algorithms which combine FIPS cryptography with cryptography from a different national standards body.<a href="#appendix-D.1-4" class="pilcrow"></a></p>
<p id="appendix-D.1-2">One of the primary design goals of this specification is for the overall composite algorithm to be able to be considered FIPS-approved even when one of the component algorithms is not. Implementers seeking FIPS certification of a Composite ML-KEM algorithm where only one of the component algorithms has been FIPS-validated or FIPS-approved should credit the FIPS-validated component algorithm with full security strength, the non-FIPS-validated component algorithm with zero security, and the overall composite should be considered full strength and thus FIPS-approved.<a href="#appendix-D.1-2" class="pilcrow"></a></p>
<p id="appendix-D.1-3">The authors wish to note that this gives composite algorithms great future utility both for future cryptographic migrations as well as bridging across jurisdictions; for example defining composite algorithms which combine FIPS cryptography with cryptography from a different national standards body.<a href="#appendix-D.1-3" class="pilcrow"></a></p>
<div id="fips-certification-of-combiner-function">
<section id="appendix-D.1.1">
<h4 id="name-fips-certification-of-combi">
<a href="#appendix-D.1.1" class="section-number selfRef">D.1.1. </a><a href="#name-fips-certification-of-combi" class="section-name selfRef">FIPS certification of Combiner Function</a>
</h4>
<p id="appendix-D.1.1-1">TODO: update this to NIST SP 800-227, once it is published.<a href="#appendix-D.1.1-1" class="pilcrow"></a></p>
<p id="appendix-D.1.1-2">One of the primary NIST documents which is relevant for certification of a composite algorithm is NIST SP.800-56Cr2 <span>[<a href="#SP.800-56Cr2" class="cite xref">SP.800-56Cr2</a>]</span> by using the allowed "hybrid" shared secret of the form <code>Z' = Z || T</code>. Compliance is achieved in the following way:<a href="#appendix-D.1.1-2" class="pilcrow"></a></p>
<p id="appendix-D.1.1-3">SP.800-56Cr2 section 4 "One-Step Key Derivation" requires a <code>counter</code> which begins at the 4-byte value 0x00000001. However, the counter is allowed to be omitted when the hash function is executed only once, as specified on page 159 of the FIPS 140-3 Implementation Guidance <span>[<a href="#FIPS-140-3-IG" class="cite xref">FIPS-140-3-IG</a>]</span>.<a href="#appendix-D.1.1-3" class="pilcrow"></a></p>
<p id="appendix-D.1.1-4">The HKDF-SHA2 options can be certified under SP.800-56Cr2 One-Step Key Derivation Option 1: <code>H(x) = hash(x)</code>.<a href="#appendix-D.1.1-4" class="pilcrow"></a></p>
<p id="appendix-D.1.1-5">The SHA3 options can be certified under SP.800-56Cr2 One-Step Key Derivation Option 2: <code>H(x) = HMAC-hash(salt, x)</code> with the salt omitted.<a href="#appendix-D.1.1-5" class="pilcrow"></a></p>
<p id="appendix-D.1.1-3"><span>[<a href="#SP.800-56Cr2" class="cite xref">SP.800-56Cr2</a>]</span> section 4 "One-Step Key Derivation" requires a <code>counter</code> which begins at the 4-byte value 0x00000001. However, the counter is allowed to be omitted when the hash function is executed only once, as specified on page 159 of the FIPS 140-3 Implementation Guidance <span>[<a href="#FIPS-140-3-IG" class="cite xref">FIPS-140-3-IG</a>]</span>.<a href="#appendix-D.1.1-3" class="pilcrow"></a></p>
<p id="appendix-D.1.1-4">The HKDF-SHA2 options can be certified under SP.800-56Cr2 One-Step Key Derivation Option 2: <code>H(x) = HMAC-hash(salt, x)</code> where <code>salt</code> is the empty (0 octet) string, which will internally be mapped to the zero vector <code>0x00..00</code> of the correct input size for the underlying hash function in order to satisfy the requirement in <span>[<a href="#SP.800-56Cr2" class="cite xref">SP.800-56Cr2</a>]</span> that "nn the absence of an agreed-upon alternative – the default_salt shall be an all-zero byte string whose bit length equals that specified as the bit length of an input block for the hash function, hash". Note that since the desired shared secret key output length of 256 bits for all security levels aligns with the block size of SHA256, we do not need to use the HKDF-Extract step specified in <span>[<a href="#RFC5869" class="cite xref">RFC5869</a>]</span>, which further simplifies FIPS certification by allowing us to use the One-Step KDF rather than the Two-Step KDF from <span>[<a href="#SP.800-56Cr2" class="cite xref">SP.800-56Cr2</a>]</span>.<a href="#appendix-D.1.1-4" class="pilcrow"></a></p>
<p id="appendix-D.1.1-5">The SHA3 options can be certified under <span>[<a href="#SP.800-56Cr2" class="cite xref">SP.800-56Cr2</a>]</span> One-Step Key Derivation Option 1: <code>H(x) = hash(x)</code>.<a href="#appendix-D.1.1-5" class="pilcrow"></a></p>
</section>
</div>
</section>
Expand Down
61 changes: 38 additions & 23 deletions draft-ietf-lamps-pq-composite-kem.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -110,8 +110,10 @@ Table of Contents
7.4. RSA-OAEP Parameters
8. Use in CMS
8.1. Underlying Components
8.1.1. Use of the HKDF-based Key Derivation Function
8.1.2. Use of the KMAC-based Key Derivation Function
8.1.1. Use of the HKDF-based Key Derivation Function within
CMS
8.1.2. Use of the KMAC-based Key Derivation Function within
CMS
8.2. RecipientInfo Conventions
8.3. Certificate Conventions
8.4. SMIMECapabilities Attribute Conventions
Expand Down Expand Up @@ -590,11 +592,16 @@ Encap Process:

4. Encode the ciphertext

ct = mlkemCT || tradCT
ct = mlkemCT || tradCT

5. Combine the KEM secrets and additional context to yield the composite shared secret

ss = KDF(mlkemSS || tradSS || tradCT || tradPK || Domain)
if KDF is "SHA3-256"
ss = SHA3-256(mlkemSS || tradSS || tradCT || tradPK || Domain)
else if KDF is "HKDF"
ss = HKDF-Extract(salt="", IKM=mlkemSS || tradSS || tradCT || tradPK || Domain)
# Note: salt is the empty string (0 octets), which will internally be mapped
# to the zero vector `0x00..00` of the correct input size for the underlying
# hash function as per [RFC 5869].

6. Output composite shared secret key and ciphertext

Expand Down Expand Up @@ -669,7 +676,13 @@ Decap Process:

5. Combine the KEM secrets and additional context to yield the composite shared secret

ss = KDF(mlkemSS || tradSS || tradCT || tradPK || Domain)
if KDF is "SHA3-256"
ss = SHA3-256(mlkemSS || tradSS || tradCT || tradPK || Domain)
else if KDF is "HKDF"
ss = HKDF-Extract(salt="", IKM=mlkemSS || tradSS || tradCT || tradPK || Domain)
# Note: salt is the empty string (0 octets), which will internally be mapped
# to the zero vector `0x00..00` of the correct input size for the underlying
# hash function as per [RFC 5869].

6. Output composite shared secret key

Expand Down Expand Up @@ -1379,7 +1392,7 @@ Deserialization Process:
resistance, we use KMAC256 for the Composite ML-KEM algorithms with
internally use SHA3-256, as aligned with Table 3 of [SP.800-57pt1r5].

8.1.1. Use of the HKDF-based Key Derivation Function
8.1.1. Use of the HKDF-based Key Derivation Function within CMS

The HMAC-based Extract-and-Expand Key Derivation Function (HKDF) is
defined in [RFC5869].
Expand Down Expand Up @@ -1417,7 +1430,7 @@ Deserialization Process:
The parameter field MUST be absent when this algorithm identifier is
used to specify the KDF for ML-KEM in KemRecipientInfo.

8.1.2. Use of the KMAC-based Key Derivation Function
8.1.2. Use of the KMAC-based Key Derivation Function within CMS

KMAC256-KDF is a KMAC-based KDF specified for use in CMS in
[I-D.ietf-lamps-cms-sha3-hash]. The definition of KMAC is copied
Expand Down Expand Up @@ -2641,16 +2654,6 @@ D.1. FIPS Certification

TODO -- update this once NIST SP 800-227 is published.

EDNOTE At time of writing, it is unclear that the KEM combiner
presented in this document would pass a FIPS certification. The SHA3
instantiations should pass under SP 800-56Cr2 Option 1, but the HKDF-
SHA2 combinations are technically not allowed under SP 800-56Cr2 even
though Option 2 allows HMAC-based constructions, but unfortunately
only HKDF-Extract is FIPS-allowed, not HKDF-Expand. The authors have
been in contact with NIST to ensure compatibility either by NIST
making SP 800-227 more flexible, or by changing this specification to
only use HKDF-Extract.

One of the primary design goals of this specification is for the
overall composite algorithm to be able to be considered FIPS-approved
even when one of the component algorithms is not. Implementers
Expand All @@ -2676,17 +2679,29 @@ D.1.1. FIPS certification of Combiner Function
the allowed "hybrid" shared secret of the form Z' = Z || T.
Compliance is achieved in the following way:

SP.800-56Cr2 section 4 "One-Step Key Derivation" requires a counter
[SP.800-56Cr2] section 4 "One-Step Key Derivation" requires a counter
which begins at the 4-byte value 0x00000001. However, the counter is
allowed to be omitted when the hash function is executed only once,
as specified on page 159 of the FIPS 140-3 Implementation Guidance
[FIPS-140-3-IG].

The HKDF-SHA2 options can be certified under SP.800-56Cr2 One-Step
Key Derivation Option 1: H(x) = hash(x).

The SHA3 options can be certified under SP.800-56Cr2 One-Step Key
Derivation Option 2: H(x) = HMAC-hash(salt, x) with the salt omitted.
Key Derivation Option 2: H(x) = HMAC-hash(salt, x) where salt is the
empty (0 octet) string, which will internally be mapped to the zero
vector 0x00..00 of the correct input size for the underlying hash
function in order to satisfy the requirement in [SP.800-56Cr2] that
"nn the absence of an agreed-upon alternative – the default_salt
shall be an all-zero byte string whose bit length equals that
specified as the bit length of an input block for the hash function,
hash". Note that since the desired shared secret key output length
of 256 bits for all security levels aligns with the block size of
SHA256, we do not need to use the HKDF-Extract step specified in
[RFC5869], which further simplifies FIPS certification by allowing us
to use the One-Step KDF rather than the Two-Step KDF from
[SP.800-56Cr2].

The SHA3 options can be certified under [SP.800-56Cr2] One-Step Key
Derivation Option 1: H(x) = hash(x).

D.2. Backwards Compatibility

Expand Down
2 changes: 1 addition & 1 deletion index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ <h2>Preview for branch <a href="mikeo_97">mikeo_97</a></h2>
<tr>
<td><a href="mikeo_97/draft-ietf-lamps-pq-composite-kem.html" class="html draft-ietf-lamps-pq-composite-kem" title="Composite ML-KEM for use in X.509 Public Key Infrastructure and CMS (HTML)">Composite ML-KEM</a></td>
<td><a href="mikeo_97/draft-ietf-lamps-pq-composite-kem.txt" class="txt draft-ietf-lamps-pq-composite-kem" title="Composite ML-KEM for use in X.509 Public Key Infrastructure and CMS (Text)">plain text</a></td>
<td>same as main</td>
<td><a href="https://author-tools.ietf.org/api/iddiff?url_1=https://lamps-wg.github.io/draft-composite-kem/draft-ietf-lamps-pq-composite-kem.txt&amp;url_2=https://lamps-wg.github.io/draft-composite-kem/mikeo_97/draft-ietf-lamps-pq-composite-kem.txt" class="diff draft-ietf-lamps-pq-composite-kem">diff with main</a></td>
</tr>
</table>
<h2>Preview for branch <a href="mikeo_hkdf">mikeo_hkdf</a></h2>
Expand Down

0 comments on commit fc71f98

Please sign in to comment.