Skip to content

Commit fb7c34b

Browse files
panvapanva
authored
Define JWK for ML-KEM (#64)
1 parent 2ff1a92 commit fb7c34b

1 file changed

Lines changed: 81 additions & 33 deletions

File tree

‎index.html‎

Lines changed: 81 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,11 @@
4242
"JWA": {
4343
aliasOf: "RFC7518"
4444
},
45+
"IANA-JOSE-Algorithms": {
46+
"title": "IANA JSON Web Signature and Encryption Algorithms",
47+
"href": "https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms",
48+
"publisher": "IANA"
49+
},
4550
// TODO: move to specref?
4651
"FIPS-202": {
4752
"title": "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions",
@@ -83,12 +88,6 @@
8388
"publisher": "IETF",
8489
"date": "October 2025"
8590
},
86-
"draft-ietf-jose-pqc-kem-05": {
87-
"title": "Post-Quantum Key Encapsulation Mechanisms (PQ KEMs) for JOSE and COSE",
88-
"href": "https://www.ietf.org/archive/id/draft-ietf-jose-pqc-kem-05.html",
89-
"publisher": "IETF",
90-
"date": "December 2025"
91-
},
9291
"CSOR": {
9392
"title": "Computer Security Objects Register",
9493
"href": "https://csrc.nist.gov/projects/computer-security-objects-register/algorithm-registration",
@@ -104,6 +103,11 @@
104103
"href": "https://datatracker.ietf.org/doc/draft-ietf-hpke-hpke/",
105104
"publisher": "IETF"
106105
},
106+
"draft-ietf-jose-hpke-pq-pqt": {
107+
"title": "JOSE HPKE PQ & PQ/T Algorithm Registrations",
108+
"href": "https://datatracker.ietf.org/doc/draft-ietf-jose-hpke-pq-pqt/",
109+
"publisher": "IETF"
110+
},
107111
"draft-irtf-cfrg-hybrid-kems-12": {
108112
"title": "Hybrid PQ/T Key Encapsulation Mechanisms",
109113
"href": "https://www.ietf.org/archive/id/draft-irtf-cfrg-hybrid-kems-12.html",
@@ -1373,6 +1377,16 @@ <h4>Registration</h4>
13731377
</tbody>
13741378
</table>
13751379
</section>
1380+
<section id="ml-kem-jwk">
1381+
<h4>JSON Web Key Representation</h4>
1382+
<p>
1383+
ML-KEM keys use the "AKP" (Algorithm Key Pair) key type defined in [[RFC9964]]
1384+
for JWK representation. The "alg" (algorithm) parameter identifies the specific ML-KEM parameter set.
1385+
The public key is carried in the "pub" parameter. If a private key is included, it is represented
1386+
using the "priv" parameter. When expressed in JWK, all key parameters are base64url encoded.
1387+
</p>
1388+
</section>
1389+
13761390
<section id="ml-kem-operations">
13771391
<h4>Operations</h4>
13781392
<section id="ml-kem-operations-encapsulate">
@@ -2010,9 +2024,6 @@ <h5>Import Key</h5>
20102024
</dd>
20112025
<dt>If |format| is {{KeyFormat/"jwk"}}:</dt>
20122026
<dd>
2013-
<p class="issue">
2014-
The JWK format for ML-KEM is not standardized yet and thus subject to change.
2015-
</p>
20162027
<ol>
20172028
<li>
20182029
<dl class="switch">
@@ -2050,16 +2061,25 @@ <h5>Import Key</h5>
20502061
</li>
20512062
<li>
20522063
<p>
2053-
If the {{JsonWebKey/alg}} field of |jwk| is not
2054-
one of the `alg` values corresponding to the
2055-
{{Algorithm/name}} member of |normalizedAlgorithm|
2056-
indicated in Section 8 of [[draft-ietf-jose-pqc-kem-05]]
2057-
(Figure 1 or 2), then [= exception/throw =] a
2064+
If the {{JsonWebKey/alg}} field of |jwk| is not present,
2065+
or its value does not identify the
2066+
ML-KEM parameter set indicated by the {{Algorithm/name}} member
2067+
of |normalizedAlgorithm|,
2068+
then [= exception/throw =] a
20582069
{{DataError}}.
20592070
</p>
2060-
<p class="example">
2061-
For example, `ML-KEM-512` and `ML-KEM-512+A128KW`
2062-
are valid "alg" values for ML-KEM-512.
2071+
<p class="note">
2072+
The "alg" values registered in the
2073+
[[[IANA-JOSE-Algorithms]]] registry
2074+
for the ML-KEM parameter sets defined by this specification
2075+
are `ML-KEM-512`, `ML-KEM-768`, and `ML-KEM-1024`.
2076+
Implementations should also accept other values from this
2077+
registry that identify a JWE algorithm using the same
2078+
ML-KEM parameter set, provided that the JWE algorithm's
2079+
JWK representation is compatible with the representation
2080+
defined here apart from the "alg" value.
2081+
Examples include the values proposed in
2082+
[[draft-ietf-jose-hpke-pq-pqt]], once registered.
20632083
</p>
20642084
</li>
20652085
<li>
@@ -2449,9 +2469,6 @@ <h5>Export Key</h5>
24492469
</dd>
24502470
<dt>If |format| is {{KeyFormat/"jwk"}}:</dt>
24512471
<dd>
2452-
<p class="issue">
2453-
The JWK format for ML-KEM is not standardized yet and thus subject to change.
2454-
</p>
24552472
<ol>
24562473
<li>
24572474
<p>
@@ -2473,14 +2490,7 @@ <h5>Export Key</h5>
24732490
<li>
24742491
<p>
24752492
Set the `alg` attribute of |jwk| to
2476-
the `alg` value corresponding to the
2477-
{{Algorithm/name}} member of |keyAlgorithm|
2478-
indicated in Section 8 of [[draft-ietf-jose-pqc-kem-05]]
2479-
(Figure 1).
2480-
</p>
2481-
<p class="example">
2482-
For example, `ML-KEM-512` is the "alg" value
2483-
used for ML-KEM-512.
2493+
the {{Algorithm/name}} member of |keyAlgorithm|.
24842494
</p>
24852495
</li>
24862496
<li>
@@ -3022,12 +3032,16 @@ <h5>Import Key</h5>
30223032
</p>
30233033
<p class="note">
30243034
The "alg" values registered in the
3025-
IANA JSON Web Signature and Encryption Algorithms registry
3035+
[[[IANA-JOSE-Algorithms]]] registry
30263036
for the hybrid KEM instances defined by this specification
30273037
are `MLKEM768-P256`, `MLKEM768-X25519`, and
30283038
`MLKEM1024-P384`. Implementations should also accept other
3029-
values from this registry that identify an algorithm
3030-
utilizing the same hybrid KEM instance.
3039+
values from this registry that identify a JWE algorithm
3040+
using the same hybrid KEM instance, provided that the JWE
3041+
algorithm's JWK representation is compatible with the
3042+
representation defined here apart from the "alg" value.
3043+
Examples include the values proposed in
3044+
[[draft-ietf-jose-hpke-pq-pqt]], once registered.
30313045
</p>
30323046
</li>
30333047
<li>
@@ -8274,8 +8288,18 @@ <h2>IANA Considerations</h2>
82748288
<section id="iana-section-jws-jwa">
82758289
<h3>JSON Web Signature and Encryption Algorithms Registration</h3>
82768290
<p>
8277-
This section registers the following algorithm identifiers in the IANA JSON Web
8278-
Signature and Encryption Algorithms Registry for use with JSON Web Key.
8291+
This section registers the following algorithm identifiers in the
8292+
[[[IANA-JOSE-Algorithms]]]
8293+
Registry for use with JSON Web Key.
8294+
</p>
8295+
<p>
8296+
These registrations use "JWK" as the only Algorithm Usage Location.
8297+
They provide stable `alg` values for the JSON Web Key representations
8298+
defined by this specification, so that Web Cryptography API
8299+
implementations can serialize and parse these keys using
8300+
{{SubtleCrypto/exportKey()}} and {{SubtleCrypto/importKey()}} with
8301+
{{KeyFormat/"jwk"}}. This specification does not define use of these
8302+
identifiers as JSON Web Signature or JSON Web Encryption algorithms.
82798303
</p>
82808304
<ul>
82818305
<li>Algorithm Name: "A128OCB"</li>
@@ -8325,6 +8349,30 @@ <h3>JSON Web Signature and Encryption Algorithms Registration</h3>
83258349
<li>Change Controller: W3C Web Application Security Working Group</li>
83268350
<li>Specification Document(s): [[ This Document ]]</li>
83278351
</ul>
8352+
<ul>
8353+
<li>Algorithm Name: "ML-KEM-512"</li>
8354+
<li>Algorithm Description: ML-KEM using the ML-KEM-512 parameter set</li>
8355+
<li>Algorithm Usage Location(s): "JWK"</li>
8356+
<li>JOSE Implementation Requirements: Optional</li>
8357+
<li>Change Controller: W3C Web Application Security Working Group</li>
8358+
<li>Specification Document(s): [[ This Document ]]</li>
8359+
</ul>
8360+
<ul>
8361+
<li>Algorithm Name: "ML-KEM-768"</li>
8362+
<li>Algorithm Description: ML-KEM using the ML-KEM-768 parameter set</li>
8363+
<li>Algorithm Usage Location(s): "JWK"</li>
8364+
<li>JOSE Implementation Requirements: Optional</li>
8365+
<li>Change Controller: W3C Web Application Security Working Group</li>
8366+
<li>Specification Document(s): [[ This Document ]]</li>
8367+
</ul>
8368+
<ul>
8369+
<li>Algorithm Name: "ML-KEM-1024"</li>
8370+
<li>Algorithm Description: ML-KEM using the ML-KEM-1024 parameter set</li>
8371+
<li>Algorithm Usage Location(s): "JWK"</li>
8372+
<li>JOSE Implementation Requirements: Optional</li>
8373+
<li>Change Controller: W3C Web Application Security Working Group</li>
8374+
<li>Specification Document(s): [[ This Document ]]</li>
8375+
</ul>
83288376
<!-- This will be registered by draft-ietf-cose-sphincs-plus
83298377
<ul>
83308378
<li>Algorithm Name: "SLH-DSA-SHA2-128s"</li>

0 commit comments

Comments
 (0)