Skip to content

Commit

Permalink
Merge pull request #8 from cose-wg/thumbprints
Browse files Browse the repository at this point in the history 
Add Examples
  • Loading branch information
@OR13
OR13 authored Oct 20, 2024
2 parents a998f9b + b1c47be commit 10fb8a8
Show file tree
Hide file tree
Showing 21 changed files with 1,104 additions and 273 deletions.
3 changes: 3 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,6 @@ draft-ietf-cose-dilithium.xml
package-lock.json
report.xml
!requirements.txt


/examples/jose/js
153 changes: 62 additions & 91 deletions draft-ietf-cose-dilithium.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ informative:
NIST-PQC-2022:
title: "Selected Algorithms 2022"
target: https://csrc.nist.gov/Projects/post-quantum-cryptography/selected-algorithms-2022

---

--- abstract

Expand All @@ -87,12 +87,7 @@ To reduce implementation burden, the key type and thumbprint computations for ML

{::boilerplate bcp14-tagged}

# ML-DSA Private Key

Note that FIPS 204 defines 2 expressions for private keys, a seed, and a private key that is expanded from the seed.
For the algorithms defined in this document, the private key is always the seed, and never the expanded expression.

# The ML-DSA Algorithm Family
# ML-DSA Algorithms

The ML-DSA Signature Scheme is paramaterized to support different security levels.

Expand All @@ -114,7 +109,7 @@ This document requests the registration of the following algorithms in {{-IANA.c
| ML-DSA-87 | TBD (requested assignment -50) | CBOR Object Signing Algorithm for ML-DSA-87
{: #cose-algorithms align="left" title="COSE algorithms for ML-DSA"}

# The Algorithm Key Type
# Algorithm Key Pair Type

The Algorithm Key Pair (AKP) Type is used to express Public and Private Keys for use with Algorithms.
When this key type is used the "alg" JSON Web Key Parameter or COSE Key Common Parameter is REQUIRED.
Expand All @@ -126,14 +121,43 @@ This document requests the registration of the following key types in {{-IANA.jo
| Algorithm Key Pair | AKP | JSON Web Key Type for the Algorithm Key Pair.
{: #jose-key-type align="left" title="Algorithm Key Pair Type for JOSE"}

~~~
{
"kid": "T4xl70S7MT6Zeq6r9V9fPJGVn76wfnXJ21-gyo0Gu6o",
"kty": "AKP",
"alg": "ML-DSA-44",
"pub": "unH59k4Ru...DZgbTP07e7gEWzw4MFRrndjbDQ",
"priv": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
}
~~~
{: #json-web-key-example align="left" title="The all zeros ML-DSA-44 JSON Web Key"}


This document requests the registration of the following algorithms in {{-IANA.cose}}:

| Name | kty | Description
|---
| AKP | TBD (requested assignment 7) | COSE Key Type for the Algorithm Key Pair.
{: #cose-key-type align="left" title="Algorithm Key Pair Type for COSE"}

# The Algorithm Key Type Thumbprint
~~~
{
/ kid / 2: h'b8969ab4b37da9f068...6f0583bf5b8d3a8059a',
/ kty / 1: 7, / AKP /
/ alg / 3: -48, / ML-DSA-44 /
/ pub / -1: h'ba71f9f64e11baeb58...c3830546b9dd8db0d',
/ priv / -2: h'00000000000000...0000000000000000'
}
~~~
{: #cose-key-example align="left" title="The all zeros ML-DSA-44 COSE Key"}

# ML-DSA Private Keys

Note that FIPS 204 defines 2 expressions for private keys, a seed, and a private key that is expanded from the seed.
For the algorithms defined in this document, the private key is always the seed, and never the expanded expression.
The AKP Key Type MAY be used with algorithms not defined in this specification, and those algorithms MAY encode their private keys differently.

# AKP Thumbprints

When computing the COSE Key Thumbprint as described in {{-COSE-KID}}, the required parameters for algorithm key pairs are:

Expand All @@ -157,6 +181,8 @@ Their lexicographic order, per {{Section 3.3 of -JOSE-KID}}, is:

The JWK Key Thumbprint is produced according to the process described in {{Section 3 of -JOSE-KID}}.

See the `kid` values in the JSON Web Key and COSE Key examples in the appendix for examples of AKP thumbprints.

# Security Considerations

The security considerations of {{-JWS}}, {{-JWK}} and {{-COSE}} applies to this specification as well.
Expand Down Expand Up @@ -233,7 +259,7 @@ The following completed registration templates are provided as described in RFC9
* Name: private_key
* Label: -2
* CBOR Type: bstr
* Description: Private key.
* Description: Private key or seed used to derive a private key.
* Reference: RFC XXXX

### New JOSE Algorithms
Expand Down Expand Up @@ -295,7 +321,7 @@ The following completed registration templates are provided as described in RFC7
#### AKP Public Key

* Parameter Name: pub
* Parameter Description: Public or verification key
* Parameter Description: Public key
* Used with "kty" Value(s): AKP
* Parameter Information Class: Public
* Change Controller: IETF
Expand All @@ -304,7 +330,7 @@ The following completed registration templates are provided as described in RFC7
#### AKP Private Key

* Parameter Name: priv
* Parameter Description: Private or signing key
* Parameter Description: Private key or seed used to derive a private key.
* Used with "kty" Value(s): AKP
* Parameter Information Class: Private
* Change Controller: IETF
Expand All @@ -316,92 +342,37 @@ The following completed registration templates are provided as described in RFC7

## JOSE

### Key Pair
~~~~~~~~~~
{::include ./examples/jose/examples/ML_DSA_44.jose.json}
~~~~~~~~~~
{: #jose_example_ML_DSA_44 title="ML_DSA_44"}

~~~json
{
"kty": "AKP",
"alg": "ML-DSA-44",
"pub": "V53SIdVF...uvw2nuCQ",
"priv": "V53SIdVF...cDKLbsBY"
}
~~~
{: #ML-DSA-44-private-jwk title="Example ML-DSA-44 Private JSON Web Key"}

~~~json
{
"kty": "AKP",
"alg": "ML-DSA-44",
"pub": "V53SIdVF...uvw2nuCQ"
}
~~~
{: #ML-DSA-44-public-jwk title="Example ML-DSA-44 Public JSON Web Key"}

### Thumbprint URI

TODO

### JSON Web Signature

~~~json
{
"alg": "ML-DSA-44"
}
~~~
{: #ML-DSA-44-jose-protected-header title="Example ML-DSA-44 Decoded Protected Header"}
~~~~~~~~~~
{::include ./examples/jose/examples/ML_DSA_65.jose.json}
~~~~~~~~~~
{: #jose_example_ML_DSA_65 title="ML_DSA_65"}

~~~
eyJhbGciOiJ...LCJraWQiOiI0MiJ9\
.\
eyJpc3MiOiJ1cm46d...XVpZDo0NTYifQ\
.\
5MSEgQ0dZB4SeLC...AAAAAABIhMUE
~~~
{: #ML-DSA-44-jose-jws title="Example ML-DSA-44 Compact JSON Web Signature"}
~~~~~~~~~~
{::include ./examples/jose/examples/ML_DSA_87.jose.json}
~~~~~~~~~~
{: #jose_example_ML_DSA_87 title="ML_DSA_87"}

## COSE

### Key Pair

~~~~ cbor-diag
{ / COSE Key /
1: 7, / AKP Key Type /
3: -48, / ML-DSA-44 Algorithm /
-1: h'7803c0f9...3f6e2c70', / AKP Private Key /
-2: h'7803c0f9...3bba7abd', / AKP Public Key /
}
~~~~
{: #ML-DSA-44-private-cose-key title="Example ML-DSA-44 Private COSE Key"}

~~~~ cbor-diag
{ / COSE Key /
1: 7, / AKP Key Type /
3: -48, / ML-DSA-44 Algorithm /
-2: h'7803c0f9...3f6e2c70' / AKP Public Key /
}
~~~~
{: #ML-DSA-44-public-cose-key title="Example ML-DSA-44 Public COSE Key"}

### Thumbprint URI

TODO

### COSE Sign 1
~~~~~~~~~~
{::include ./examples/cose/examples/ML_DSA_44.cose.json}
~~~~~~~~~~
{: #cose_example_ML_DSA_44 title="ML_DSA_44"}

~~~~ cbor-diag
/ cose-sign1 / 18(
[
/ protected / <<{
/ algorithm / 1 : -49 / ML-DSA-65 /
}>>
/ unprotected / {},
/ payload / h'66616b65',
/ signature / h'53e855e8...0f263549'
]
)
~~~~
{: #ML-DSA-44-cose-sign-1-diagnostic title="Example ML-DSA-44 COSE Sign 1"}
~~~~~~~~~~
{::include ./examples/cose/examples/ML_DSA_65.cose.json}
~~~~~~~~~~
{: #cose_example_ML_DSA_65 title="ML_DSA_65"}

~~~~~~~~~~
{::include ./examples/cose/examples/ML_DSA_87.cose.json}
~~~~~~~~~~
{: #cose_example_ML_DSA_87 title="ML_DSA_87"}

# Acknowledgments
{:numbered="false"}
Expand Down
11 changes: 9 additions & 2 deletions examples/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,16 @@

🔥 The code in this repository has not been audited or reviewed.

This code is for generating example spec text, and is likely to be incorrect.

### Generate Examples

```
go run generate.go
cat ./examples.json | jq
cd cose
go test
cd jose
go test
```

### Credits
Expand Down
Loading

0 comments on commit 10fb8a8

Please sign in to comment.