Proposed addition/modification to CMS artifacts section in README.md

codespree commented 3 weeks ago

Perhaps the following can weigh in here: [✅] @carl-wallace [❓] @dghgit [❓] @ounsworth

CMS -- artifacts_cms_v2.zip

This is version 2 of the CMS artifacts format. It may change, if it needs to change.

Within providers/<provider_name>/[implementation_name/]

artifacts_cms_v2.zip
- artifacts_cms_v2/ subfolder which will contain the artifacts
- artifacts_cms_v2/expected_plaintext.txt # The message which was encrypted and can be compared against the decrypted artifacts.
- artifacts_cms_v2/ukm.txt # The User Keying Material (UKM) included in some of the enveloped messages.
- artifacts_cms_v2/<ta oid>_<ta friendly name>_ta.der # ML-DSA trust anchor used to sign the KEM end-entity certificates:
  - For MlKem512 use MlDsa44
  - For MlKem768 and MlKem768 based composites, use MlDsa65
  - For MlKem1024 and MlKem1024 based composites use MlDsa87
- artifacts_cms_v2/<oid>_<friendly>_ee.der # The KEM certificate that the message is enveloped to.
- artifacts_cms_v2/<oid>_<friendly>_priv.der # The private key to decrypt the enveloped messages.
- artifacts_cms_v2/<oid>_<friendly>_kemri_ukm_<kdf>.der # An Enveloped artifact using KEMRI’s UKM field and one of the Mandatory to Implement (MTI) KDFs for the KEM algorithm.
- artifacts_cms_v2/<oid>_<friendly>_kemri_auth_<kdf>.der # An AuthEnveloped artifact using KEMRI without UKM and one of the MTI KDFs for the KEM algorithm.
- artifacts_cms_v2/<oid>_<friendly>_kemri_<kdf>.der # Enveloped artifacts using KEMRI without UKM and the specified KDF.

Friendly

Per https://github.com/IETF-Hackathon/pqc-certificates/issues/96 we would like a text description of the algorithm in the artifact names to make artifacts directory listings easier to read. Stick something same in there, for example the appropriate name from oid_mapping.md.

Trust Anchor

A trust anchor isn't necessary to verify the KEMRecipientInfo artifacts, but if you provide it, we can test that the EE certificate is signed by the TA. If it is not provided, this test will be skipped.

DER vs PEM

We picked DER encoding so there's not an extra layer to mess up. You probably have a DER<->PEM re-encoding tool.

Encryption Algorithms

Use id-aes<size>wrap for KEK algorithm where <size> is appropriate for your <oid>. Each I-D/RFC should specify this.

Use aes-<size>-gcm for the CEK algorithm in the <oid>_kemri_auth_<kdf>.der artifact. Use aes-<size>-cbc for all others.

MTI KDFs

Each RFC will specify MTI KDFs, and allow for others as well.

You MUST have a <oid>_<friendly>_kemri_<kdf>, <oid>_<friendly>_kemri_ukm_<kdf>.der, and <oid>_<friendly>_kemri_auth_<kdf>.der artifacts for all MTI KDFs.

You MAY provider artifacts for other KDFs with the following caveats:- Pure ML-KEM (draft-ietf-lamps-cms-kyber-05 Section 2.2.2):

      ML-KEM-512 SHOULD be used with a KDF capable of outputting a key
      with at least 128 bits of preimage strength and with a key
      wrapping algorithm with a key length of at least 128 bits.

      ML-KEM-768 SHOULD be used with a KDF capable of outputting a key
      with at least 192 bits of preimage strength and with a key
      wrapping algorithm with a key length of at least 192 bits.

      ML-KEM-1024 SHOULD be used with a KDF capable of outputting a key
      with at least 256 bits of preimage strength and with a key
      wrapping algorithm with a key length of at least 256 bits.

Composite ML-KEM (draft-ietf-lamps-pq-composite-kem-05 Section 8.1):

     SHOULD use algorithms of equivalent strength or greater to the MTI KDFs in the table listed below:

The following are the MTI KDFs for ML-KEM based pure and composites:	I-D/RFC	Algorithm	Wrap	MTI KDF
draft-ietf-lamps-cms-kyber-05	ML-KEM-512	id-aes128-wrap	HKDF with SHA-256*	id-alg-hkdf-with-sha256*
draft-ietf-lamps-cms-kyber-05	ML-KEM-768	id-aes256-wrap	HKDF with SHA-256*	id-alg-hkdf-with-sha256*
draft-ietf-lamps-cms-kyber-05	ML-KEM-1024	id-aes256-wrap	HKDF with SHA-256*	id-alg-hkdf-with-sha256*
draft-ietf-lamps-pq-composite-kem-05	MLKEM768-RSA2048	id-aes128-wrap	HKDF with SHA-256**	id-alg-hkdf-with-sha256**
draft-ietf-lamps-pq-composite-kem-05	MLKEM768-RSA3072	id-aes128-wrap	HKDF with SHA-256**	id-alg-hkdf-with-sha256**
draft-ietf-lamps-pq-composite-kem-05	MLKEM768-RSA4096	id-aes128-wrap	HKDF with SHA-256\	id-alg-hkdf-with-sha256\
draft-ietf-lamps-pq-composite-kem-05	MLKEM768-X25519	id-aes128-wrap	KMAC256-KDF\	id-kmac256\
draft-ietf-lamps-pq-composite-kem-05	MLKEM768-ECDH-P384	id-aes256-wrap	HKDF with SHA-256\	id-alg-hkdf-with-sha256\
draft-ietf-lamps-pq-composite-kem-05	MLKEM768-ECDH-brainpoolP256r1	id-aes256-wrap	HKDF with SHA-256\	id-alg-hkdf-with-sha256\
draft-ietf-lamps-pq-composite-kem-05	MLKEM1024-ECDH-P384	id-aes256-wrap	KMAC256-KDF\	id-kmac256\
draft-ietf-lamps-pq-composite-kem-05	MLKEM1024-ECDH-brainpoolP384r1	id-aes256-wrap	KMAC256-KDF\	id-kmac256\
draft-ietf-lamps-pq-composite-kem-05	MLKEM1024-X448	id-aes256-wrap	KMAC256-KDF\	id-kmac256\

The following is the MTI KDF for RSA-KEM:	I-D/RFC	Algorithm	Wrap	MTI KDF	`<kdf> string`
draft-ietf-lamps-rfc5990bis-10	RSA-KEM	id-aes128-wrap	KDF3 w/ SHA-256 ***	id-kdf-kdf3 ***

* Based on draft-ietf-lamps-cms-kyber-05 ** Based on draft-ietf-lamps-pq-composite-kem-05 *** Based on draft draft-ietf-lamps-rfc5990bis-10

The markdown for the above is:

## CMS -- artifacts_cms_v2.zip

This is version 2 of the CMS artifacts format.  It may change if needs change.

Within `providers/<provider_name>/[implementation_name/]`
- artifacts_cms_v2.zip
  - `artifacts_cms_v2/` subfolder which will contain the artifacts
  - `artifacts_cms_v2/expected_plaintext.txt` # The message which was encrypted and can be compared against the decrypted artifacts.
  - `artifacts_cms_v2/ukm.txt` # The User Keying Material (UKM) included in some of the enveloped messages.
  - `artifacts_cms_v2/<ta oid>_<ta friendly name>_ta.der` # ML-DSA trust anchor used to sign the KEM end-entity certificates:
          - For MlKem512 use MlDsa44
          - For MlKem768 and MlKem768 based composites, use MlDsa65
          - For MlKem1024 and MlKem1024 based composites use MlDsa87
  - `artifacts_cms_v2/<oid>_<friendly>_ee.der` # The KEM certificate that the message is enveloped to.
  - `artifacts_cms_v2/<oid>_<friendly>_priv.der` # The private key to decrypt the enveloped messages.
  - `artifacts_cms_v2/<oid>_<friendly>_kemri_ukm_<kdf>.der` # An Enveloped artifact using KEMRI’s UKM field and one of the Mandatory to Implement (MTI) KDFs for the KEM algorithm.
  - `artifacts_cms_v2/<oid>_<friendly>_kemri_auth_<kdf>.der` # An AuthEnveloped artifact using KEMRI without UKM and one of the MTI KDFs for the KEM algorithm.
  - `artifacts_cms_v2/<oid>_<friendly>_kemri_<kdf>.der` # Enveloped artifacts using KEMRI without UKM and the specified KDF. 

#### Friendly

Per https://github.com/IETF-Hackathon/pqc-certificates/issues/96 we would like a text description of the algorithm in the artifact names to make artifacts directory listings easier to read. Stick something same in there, for example the appropriate name from [oid_mapping.md](docs/oid_mapping.md).

#### Trust Anchor

A trust anchor isn't necessary to verify the KEMRecipientInfo artifacts, but if you provide it, we can test that the EE certificate is signed by the TA. If it is not provided, this test will be skipped.

#### DER vs PEM

We picked DER encoding so there's not an extra layer to mess up. You probably have a DER<->PEM re-encoding tool.

#### Encryption Algorithms

Use `id-aes<size>wrap` for KEK algorithm where `<size>` is appropriate for your `<oid>`.  Each I-D/RFC should specify this.

Use `aes-<size>-gcm` for the CEK algorithm in the `<oid>_kemri_auth_<kdf>.der` artifact.  Use `aes-<size>-cbc` for all others.

#### MTI KDFs

Each RFC will specify MTI KDFs, and allow for others as well. 

You *MUST* have a `<oid>_<friendly>_kemri_<kdf>`, `<oid>_<friendly>_kemri_ukm_<kdf>.der`, and  `<oid>_<friendly>_kemri_auth_<kdf>.der`  artifacts for all MTI KDFs. 

You *MAY* provider artifacts for other KDFs with the following caveats:-
Pure ML-KEM (`draft-ietf-lamps-cms-kyber-05` Section  2.2.2):
\```
      ML-KEM-512 SHOULD be used with a KDF capable of outputting a key
      with at least 128 bits of preimage strength and with a key
      wrapping algorithm with a key length of at least 128 bits.

      ML-KEM-768 SHOULD be used with a KDF capable of outputting a key
      with at least 192 bits of preimage strength and with a key
      wrapping algorithm with a key length of at least 192 bits.

      ML-KEM-1024 SHOULD be used with a KDF capable of outputting a key
      with at least 256 bits of preimage strength and with a key
      wrapping algorithm with a key length of at least 256 bits.
\```

Composite ML-KEM (`draft-ietf-lamps-pq-composite-kem-05` Section 8.1):
\```
     SHOULD use algorithms of equivalent strength or greater to the MTI KDFs in the table listed below:
\```

The following are the MTI KDFs for ML-KEM based pure and composites:
| I-D/RFC | Algorithm | Wrap | MTI KDF | `<kdf> string` |
| - | - | - | - | - |
| draft-ietf-lamps-cms-kyber-05 | ML-KEM-512 | id-aes128-wrap | HKDF with SHA-256\* | id-alg-hkdf-with-sha256\* |
| draft-ietf-lamps-cms-kyber-05 | ML-KEM-768 | id-aes256-wrap | HKDF with SHA-256\* | id-alg-hkdf-with-sha256\* |
| draft-ietf-lamps-cms-kyber-05 | ML-KEM-1024 | id-aes256-wrap | HKDF with SHA-256\* | id-alg-hkdf-with-sha256\* |
| draft-ietf-lamps-pq-composite-kem-05 | MLKEM768-RSA2048 | id-aes128-wrap | HKDF with SHA-256\*\* | id-alg-hkdf-with-sha256\*\* |
| draft-ietf-lamps-pq-composite-kem-05 | MLKEM768-RSA3072 | id-aes128-wrap | HKDF with SHA-256\*\* | id-alg-hkdf-with-sha256\*\* |
| draft-ietf-lamps-pq-composite-kem-05 | MLKEM768-RSA4096 | id-aes128-wrap | HKDF with SHA-256*\* | id-alg-hkdf-with-sha256*\* |
| draft-ietf-lamps-pq-composite-kem-05 | MLKEM768-X25519 | id-aes128-wrap | KMAC256-KDF*\* | id-kmac256*\* |
| draft-ietf-lamps-pq-composite-kem-05 | MLKEM768-ECDH-P384 | id-aes256-wrap | HKDF with SHA-256*\* | id-alg-hkdf-with-sha256*\* |
| draft-ietf-lamps-pq-composite-kem-05 | MLKEM768-ECDH-brainpoolP256r1 | id-aes256-wrap | HKDF with SHA-256*\* | id-alg-hkdf-with-sha256*\* |
| draft-ietf-lamps-pq-composite-kem-05 | MLKEM1024-ECDH-P384 | id-aes256-wrap | KMAC256-KDF*\* | id-kmac256*\*  |
| draft-ietf-lamps-pq-composite-kem-05 | MLKEM1024-ECDH-brainpoolP384r1 | id-aes256-wrap | KMAC256-KDF*\* | id-kmac256*\*  |
| draft-ietf-lamps-pq-composite-kem-05 | MLKEM1024-X448 | id-aes256-wrap | KMAC256-KDF*\* | id-kmac256*\*  |

The following is the MTI KDF for RSA-KEM:
| I-D/RFC | Algorithm | Wrap | MTI KDF | `<kdf> string` |
| - | - | - | - | - |
| draft-ietf-lamps-rfc5990bis-10 | RSA-KEM | id-aes128-wrap |  KDF3 w/ SHA-256 \*\*\* | id-kdf-kdf3 \*\*\* |

\* Based on draft-ietf-lamps-cms-kyber-05
\*\* Based on draft-ietf-lamps-pq-composite-kem-05
\*\*\* Based on draft draft-ietf-lamps-rfc5990bis-10

codespree commented 3 weeks ago

For simplicity, and to avoid combinatorial explosion, should we just stick to the MUSTs for CMS artifacts?

carl-wallace commented 3 weeks ago

Not sure. Having test artifacts beyond the MTIs isn't necessarily a bad thing.

codespree commented 3 weeks ago

@carl-wallace sure. But I think the above description is clearer right?

The file names etc. and the MTI artifacts which MUST be present.

We can also verify anything else submitted as well, no harm.

But the test should fail if an MTI is not present.

carl-wallace commented 3 weeks ago

I don't think anything MUST be present for any provider in this repo. To my eye, the utility of this endeavor is in teasing out spec bugs, making sure there is interoperability where there are common algorithms between implementations, etc.

The above description seems useful to me, but is brainpool actually an MTI for composite KEM?

codespree commented 3 weeks ago

@carl-wallace the musts are from the drafts. For example,

   A compliant implementation MUST support the following algorithm
   combinations for the KEMRecipientInfo kdf and wrap fields when the
   corresponding Composite ML-KEM algorithm is listed in the
   KEMRecipientInfo kem field.  The KDFs listed below align with the KDF
   used internally within the KEM combiner.  An implementation MAY also
   support other key-derivation functions and other key-encryption
   algorithms within CMS KEMRecipientInfo and SHOULD use algorithms of
   equivalent strength or greater.

https://datatracker.ietf.org/doc/draft-ietf-lamps-pq-composite-kem/

Section 8.1

carl-wallace commented 3 weeks ago

Thanks for the reference (the current data tracker outage impeded my loading the draft). Be that as it may, I don't see "failing a test" because one only submitted a subset of artifacts. But that's just, like, my opinion:-) But, it's also only a draft at present. I wonder if these MTIs will all stick.

codespree commented 3 weeks ago

@carl-wallace

@jethrolow created an automation: https://jethrolow.github.io/pqc-certificates/pqc_hackathon_results_certs_r4_automated_tests.html

I was thinking we could do something similar for CMS artifacts.

So, from that point of view, what would be the rows? Just MTI artifacts?

If not just MTI artifacts, it would be difficult to list all possible combinations as rows right?

codespree commented 2 weeks ago

This is not a comment about the draft. Nor does it express an opinion on what MTI artifacts should be. This is a comment about the language in the README.md file and about its clarity to, at least, developers like me.

And, how we can create an automation to test CMS artifacts.

Perhaps we can test the MTI artifacts as rows in an automation page.

And have one extra row as Others which tests the rest and shows pass/fail in that row.

IETF-Hackathon / pqc-certificates