Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Open
codespree opened this issue Nov 3, 2024 · 8 comments
Open

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

codespree opened this issue Nov 3, 2024 · 8 comments

Comments

@codespree
Copy link

codespree commented Nov 3, 2024 •
edited
Loading

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 #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 <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

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
Copy link
Author

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

@carl-wallace
Copy link
Collaborator

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

@codespree
Copy link
Author

@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
Copy link
Collaborator

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
Copy link
Author

@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
Copy link
Collaborator

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
Copy link
Author

@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
Copy link
Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@carl-wallace @codespree