Merge pull request #98 from IETF-Hackathon/dvg/initial_cms

Initial CMS interop
IETF-Hackathon · Feb 15, 2024 · 302b679 · 302b679
2 parents 80f7267 + ba436ce
commit 302b679
Show file tree

Hide file tree

Showing 10 changed files with 302 additions and 14 deletions.
diff --git a/docs/pqc_hackathon_results_certs_r3.html b/docs/pqc_hackathon_results_certs_r3.html
@@ -1,4 +1,4 @@
-<h1 id="ietf-pqc-hackathon-interoperability-results">IETF PQC Hackathon Interoperability Results</h1>
+<h1 id="ietf-pqc-hackathon-certificate-interoperability-results">IETF PQC Hackathon Certificate Interoperability Results</h1>
 <h1 id="algorithms">Algorithms</h1>
 <ul>
 <li><a href="#algorithms-tested">Algorithms Tested</a></li>

diff --git a/docs/pqc_hackathon_results_certs_r3.md b/docs/pqc_hackathon_results_certs_r3.md
@@ -1,6 +1,6 @@
 
-IETF PQC Hackathon Interoperability Results
-===========================================
+IETF PQC Hackathon Certificate Interoperability Results
+=======================================================
 
 Algorithms
 ==========

diff --git a/docs/pqc_hackathon_results_cms_v1.html b/docs/pqc_hackathon_results_cms_v1.html
@@ -0,0 +1,139 @@
+<h1 id="ietf-pqc-hackathon-cms-interoperability-results">IETF PQC Hackathon CMS Interoperability Results</h1>
+<h1 id="algorithms">Algorithms</h1>
+<ul>
+<li><a href="#algorithms-tested">Algorithms Tested</a></li>
+<li><a href="#ml-kem-512-ipd-13614122554561">ML-KEM-512-ipd (1.3.6.1.4.1.22554.5.6.1)</a></li>
+<li><a href="#ml-kem-768-ipd-13614122554562">ML-KEM-768-ipd (1.3.6.1.4.1.22554.5.6.2)</a></li>
+<li><a href="#ml-kem-1024-ipd-13614122554563">ML-KEM-1024-ipd (1.3.6.1.4.1.22554.5.6.3)</a></li>
+<li><a href="#kyber512_shake-13614122554567"><del>kyber512_shake</del> (1.3.6.1.4.1.22554.5.6.7)</a></li>
+<li><a href="#kyber768_shake-13614122554568"><del>kyber768_shake</del> (1.3.6.1.4.1.22554.5.6.8)</a></li>
+<li><a href="#kyber1024_shake-13614122554569"><del>kyber1024_shake</del> (1.3.6.1.4.1.22554.5.6.9)</a></li>
+</ul>
+<style> table { border-collapse: collapse; } th, td { border: solid black 1px; padding: 0 1ex; } </style>
+<p>In the individual algorithm tables below, Rows are producers. Columns are parsers.</p>
+<h1 id="algorithms-tested">Algorithms Tested</h1>
+<p>To be in this table, an algorithm must have a test result in one of the tables below (pass or fail). Algorithms for which we have artifacts but no test results are not shown.</p>
+<table>
+<thead>
+<tr class="header">
+<th style="text-align: left;">-</th>
+<th style="text-align: left;">cryptonext-cnsprovider</th>
+</tr>
+</thead>
+<tbody>
+<tr class="odd">
+<td style="text-align: left;">ML-KEM-512-ipd</td>
+<td style="text-align: left;">✅</td>
+</tr>
+<tr class="even">
+<td style="text-align: left;">ML-KEM-768-ipd</td>
+<td style="text-align: left;">✅</td>
+</tr>
+<tr class="odd">
+<td style="text-align: left;">ML-KEM-1024-ipd</td>
+<td style="text-align: left;">✅</td>
+</tr>
+<tr class="even">
+<td style="text-align: left;"><del>kyber512_shake</del></td>
+<td style="text-align: left;">✅</td>
+</tr>
+<tr class="odd">
+<td style="text-align: left;"><del>kyber768_shake</del></td>
+<td style="text-align: left;">✅</td>
+</tr>
+<tr class="even">
+<td style="text-align: left;"><del>kyber1024_shake</del></td>
+<td style="text-align: left;">✅</td>
+</tr>
+</tbody>
+</table>
+<h1 id="ml-kem-512-ipd-1.3.6.1.4.1.22554.5.6.1">ML-KEM-512-ipd (1.3.6.1.4.1.22554.5.6.1)</h1>
+<table>
+<thead>
+<tr class="header">
+<th style="text-align: left;">-</th>
+<th style="text-align: left;">cryptonext-cnsprovider</th>
+</tr>
+</thead>
+<tbody>
+<tr class="odd">
+<td style="text-align: left;">cryptonext-cnsprovider</td>
+<td style="text-align: left;">✅</td>
+</tr>
+</tbody>
+</table>
+<h1 id="ml-kem-768-ipd-1.3.6.1.4.1.22554.5.6.2">ML-KEM-768-ipd (1.3.6.1.4.1.22554.5.6.2)</h1>
+<table>
+<thead>
+<tr class="header">
+<th style="text-align: left;">-</th>
+<th style="text-align: left;">cryptonext-cnsprovider</th>
+</tr>
+</thead>
+<tbody>
+<tr class="odd">
+<td style="text-align: left;">cryptonext-cnsprovider</td>
+<td style="text-align: left;">✅</td>
+</tr>
+</tbody>
+</table>
+<h1 id="ml-kem-1024-ipd-1.3.6.1.4.1.22554.5.6.3">ML-KEM-1024-ipd (1.3.6.1.4.1.22554.5.6.3)</h1>
+<table>
+<thead>
+<tr class="header">
+<th style="text-align: left;">-</th>
+<th style="text-align: left;">cryptonext-cnsprovider</th>
+</tr>
+</thead>
+<tbody>
+<tr class="odd">
+<td style="text-align: left;">cryptonext-cnsprovider</td>
+<td style="text-align: left;">✅</td>
+</tr>
+</tbody>
+</table>
+<h1 id="kyber512_shake-1.3.6.1.4.1.22554.5.6.7"><del>kyber512_shake</del> (1.3.6.1.4.1.22554.5.6.7)</h1>
+<table>
+<thead>
+<tr class="header">
+<th style="text-align: left;">-</th>
+<th style="text-align: left;">cryptonext-cnsprovider</th>
+</tr>
+</thead>
+<tbody>
+<tr class="odd">
+<td style="text-align: left;">cryptonext-cnsprovider</td>
+<td style="text-align: left;">✅</td>
+</tr>
+</tbody>
+</table>
+<h1 id="kyber768_shake-1.3.6.1.4.1.22554.5.6.8"><del>kyber768_shake</del> (1.3.6.1.4.1.22554.5.6.8)</h1>
+<table>
+<thead>
+<tr class="header">
+<th style="text-align: left;">-</th>
+<th style="text-align: left;">cryptonext-cnsprovider</th>
+</tr>
+</thead>
+<tbody>
+<tr class="odd">
+<td style="text-align: left;">cryptonext-cnsprovider</td>
+<td style="text-align: left;">✅</td>
+</tr>
+</tbody>
+</table>
+<h1 id="kyber1024_shake-1.3.6.1.4.1.22554.5.6.9"><del>kyber1024_shake</del> (1.3.6.1.4.1.22554.5.6.9)</h1>
+<table>
+<thead>
+<tr class="header">
+<th style="text-align: left;">-</th>
+<th style="text-align: left;">cryptonext-cnsprovider</th>
+</tr>
+</thead>
+<tbody>
+<tr class="odd">
+<td style="text-align: left;">cryptonext-cnsprovider</td>
+<td style="text-align: left;">✅</td>
+</tr>
+</tbody>
+</table>
diff --git a/docs/pqc_hackathon_results_cms_v1.md b/docs/pqc_hackathon_results_cms_v1.md
@@ -0,0 +1,69 @@
+
+IETF PQC Hackathon CMS Interoperability Results
+===============================================
+
+Algorithms
+==========
+
+* [Algorithms Tested](#algorithms-tested)
+* [ML-KEM-512-ipd (1.3.6.1.4.1.22554.5.6.1)](#ml-kem-512-ipd-13614122554561)
+* [ML-KEM-768-ipd (1.3.6.1.4.1.22554.5.6.2)](#ml-kem-768-ipd-13614122554562)
+* [ML-KEM-1024-ipd (1.3.6.1.4.1.22554.5.6.3)](#ml-kem-1024-ipd-13614122554563)
+* [~~kyber512_shake~~ (1.3.6.1.4.1.22554.5.6.7)](#kyber512_shake-13614122554567)
+* [~~kyber768_shake~~ (1.3.6.1.4.1.22554.5.6.8)](#kyber768_shake-13614122554568)
+* [~~kyber1024_shake~~ (1.3.6.1.4.1.22554.5.6.9)](#kyber1024_shake-13614122554569)
+
+
+<style> table { border-collapse: collapse; } th, td { border: solid black 1px; padding: 0 1ex; } </style>
+
+In the individual algorithm tables below, Rows are producers. Columns are parsers.
+
+# Algorithms Tested
+
+
+To be in this table, an algorithm must have a test result in one of the tables below (pass or fail). Algorithms for which we have artifacts but no test results are not shown.
+
+|-|cryptonext-cnsprovider|
+| :--- | :--- |
+|ML-KEM-512-ipd|✅|
+|ML-KEM-768-ipd|✅|
+|ML-KEM-1024-ipd|✅|
+|~~kyber512_shake~~|✅|
+|~~kyber768_shake~~|✅|
+|~~kyber1024_shake~~|✅|
+
+# ML-KEM-512-ipd (1.3.6.1.4.1.22554.5.6.1)
+
+|-|cryptonext-cnsprovider|
+| :--- | :--- |
+|cryptonext-cnsprovider|✅|
+
+# ML-KEM-768-ipd (1.3.6.1.4.1.22554.5.6.2)
+
+|-|cryptonext-cnsprovider|
+| :--- | :--- |
+|cryptonext-cnsprovider|✅|
+
+# ML-KEM-1024-ipd (1.3.6.1.4.1.22554.5.6.3)
+
+|-|cryptonext-cnsprovider|
+| :--- | :--- |
+|cryptonext-cnsprovider|✅|
+
+# ~~kyber512_shake~~ (1.3.6.1.4.1.22554.5.6.7)
+
+|-|cryptonext-cnsprovider|
+| :--- | :--- |
+|cryptonext-cnsprovider|✅|
+
+# ~~kyber768_shake~~ (1.3.6.1.4.1.22554.5.6.8)
+
+|-|cryptonext-cnsprovider|
+| :--- | :--- |
+|cryptonext-cnsprovider|✅|
+
+# ~~kyber1024_shake~~ (1.3.6.1.4.1.22554.5.6.9)
+
+|-|cryptonext-cnsprovider|
+| :--- | :--- |
+|cryptonext-cnsprovider|✅|
diff --git a/providers/cryptonext/cnsprovider/artifacts_cms_v1.zip b/providers/cryptonext/cnsprovider/artifacts_cms_v1.zip
diff --git a/...ptonext/compatMatrices/artifacts_cms_v1/cryptonext-cnsprovider_cryptonext-cnsprovider.csv b/...ptonext/compatMatrices/artifacts_cms_v1/cryptonext-cnsprovider_cryptonext-cnsprovider.csv
@@ -0,0 +1,7 @@
+key_algorithm_oid,test_result
+1.3.6.1.4.1.22554.5.6.7,Y
+1.3.6.1.4.1.22554.5.6.8,Y
+1.3.6.1.4.1.22554.5.6.9,Y
+1.3.6.1.4.1.22554.5.6.1,Y
+1.3.6.1.4.1.22554.5.6.2,Y
+1.3.6.1.4.1.22554.5.6.3,Y
diff --git a/readme.md b/readme.md
@@ -1,3 +1,4 @@
+<style> table { border-collapse: collapse; } th, td { border: solid black 1px; padding: 0 1ex; } </style>
 # IETF Hackathon - PQC Certificates
 
 This project provides a set of data repositories for X.509 data
@@ -6,9 +7,13 @@ structures that make use of post-quantum and composite algorithms
 
 This repo represents work done between IETF 115 - 119.
 
-A summary table of the ongoing interoperability testing can be found here:
+A summary table of the ongoing certificate interoperability testing can be found here:
 https://ietf-hackathon.github.io/pqc-certificates/pqc_hackathon_results_certs_r3.html
 
+A summary table of the ongoing CMS interoperability testing can be found here:
+https://ietf-hackathon.github.io/pqc-certificates/pqc_hackathon_results_cms_v1.html
+
+
 An older version showing more (now obsolete) algorithms can be found here instead:
 https://ietf-hackathon.github.io/pqc-certificates/pqc_hackathon_results.html
 
@@ -30,15 +35,22 @@ The project's directory structure is as follows:
     - providers/
         - provider_name_1/
             - artifacts_certs_r3.zip
+            - artifacts_cms_v1.zip
             - implementation_name_1/
                 - artifacts_certs_r3.zip
+                - artifacts_cms_v1.zip
             - implementation_name_2/
                 - artifacts_certs_r3.zip
+                - artifacts_cms_v1.zip
             - compatMatrices
               - artifacts_certs_r3
                 - prov2_prov1.csv
                 - prov3_prov1.csv
                 - ...
+              - artifacts_cms_v1
+                - prov2_prov1.csv
+                - prov3_prov1.csv
+                - ...
             - gen.sh
             - check.sh
             - Makefile
@@ -47,7 +59,7 @@ The project's directory structure is as follows:
             - implementation_name_1
             - ...
 ~~~
-Note that your artifacts zip can be placed either at the top-level of your provider, or if you have multiple implementtations, then they can be places id implementation sub-folders.
+Note that your artifacts zip can be placed either at the top-level of your provider, or if you have multiple implementations, then they can be placed in implementation sub-folders.
 
 Where:
 
@@ -96,21 +108,66 @@ Starting with artifacts for the NIST Draft standards released 2023-08-24, we wil
 * For Kyber, use the the Dilithium TA of the equivalent security level to sign a <kyber_oid>_ee.pem
 * For hybrid certificate formats, name the file `<hybrid_format>_<oid1>_with_<oid2>_ta.pem`
 
-Within `providers/<provider_name>/`
+Within `providers/<provider_name>/[implementation_name/]`
 - artifacts_certs_r3.zip
   - `<oid>_ta.pem`  # self-signed cert for signature alg oids
   - `<oid>_ee.pem`  # ex.: Kyber512  - signed with Dilithium2
   - `<hybrid_format>_<oid1>_with_<oid2>_ta.pem`  # ex.: catalyst_1.2.840.10045.4.3.2_with_1.3.6.1.4.1.2.267.12.4.4_ta.pem
 
 The KEM end entity certificate can be used to validate encrypted artifacts in either the CMS or CMP artifacts zips.
 
-### CMS -- artifacts_cms.zip
+### CMS -- artifacts_cms_v1.zip
+
+This is version 1 of the CMS artifacts format.  It may change if needs change.
+
+Within `providers/<provider_name>/[implementation_name/]`
+- artifacts_cms_v1.zip
+  - `expected_plaintext.txt` # The message which was encrypted and can be compared against the decrypted artifacts.
+  - `ukm.txt` # The User Keying Material (UKM) included in some of the enveloped messages.
+  - `<ta>.der` # dilithium2 trust anchor used to sign the KEM end-entity certificates.
+  - `<oid>_<friendly>_ee.der` # The KEM certificate that the message is enveloped to.
+  - `<oid>_<friendly>_priv.der` # The private key to decrypt the enveloped messages.
+  - `<oid>_<friendly>_kemri_ukm.der` # An Enveloped artifact using KEMRI’s UKM field and one of the MTI KDFs for the KEM algorithm.
+  - `<oid>_<friendly>_kemri_auth.der` # An AuthEnveloped artifact using KEMRI without UKM and one of the MTI KDFs for the KEM algorithm.
+  - `<oid>_<friendly>_kemri_<kdf>.der` # Enveloped artifacts using KEMRI without UKM and the specified KDF. Implementations must provide artifacts for each of the MTI KDFs for the OID, and may provider artifacts for others.
+
+#### 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 some implementations may find it useful. We're using dilithium2 at the moment since some might not have implemented ML-DSA.ipd.
+
+#### 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.der` artifact.  Use `aes-<size>-cbc` for all others.
+
+#### MTI KDFs
+
+Each RFC will specify mandatory KDFs, and probably allow for others as well. You should have a `<oid>_kemri_<kdf>.der` artifact for all MTI KDFs for each KEM OID that you support.
+
+| I-D/RFC | Algorithm | MTI KDF | `<kdf> string` |
+| - | - | - | - |
+| rfc5990bis | RSA-KEM | KDF3 w/ SHA-256 | id-kdf-kdf3 |
+| cms-kyber | ML-KEM-512 | HKDF w/ SHA-256\* | id-alg-hkdf-with-sha256\* |
+| cms-kyber | ML-KEM-768 | HKDF w/ SHA-384\* | id-alg-hkdf-with-sha384\* |
+| cms-kyber | ML-KEM-1024 | HKDF w/ SHA-512\* | id-alg-hkdf-with-sha512\* |
+| - | kyber512 | HKDF w/ SHA-256\* | id-alg-hkdf-with-sha256\* |
+| - | kyber768 | HKDF w/ SHA-384\* | id-alg-hkdf-with-sha384\* |
+| - | kyber1024 | HKDF w/ SHA-512\* | id-alg-hkdf-with-sha512\* |
 
-CMS artficats should be placed into a `artifacts_cms.zip` within `providers/<provider_name>/`. We will specify the exact file format when we start to see more robust artifacts submitted.
+\* The MTI artifacts for draft-ietf-lamps-cms-kyber are still TBD. Ideally we're just waiting on OIDs for kmac-based KDFs. Otherwise we'll argue about using KDF3 vs HKDF-with-SHA3 (OIDs are not defined yet). For the moment we're using HKDF-with-SHA2 because a) we have OIDs; b) we have implementations.
 
 ### CMP -- artifacts_cmp.zip
 
-CMP artficats should be placed into a `artifacts_cmp.zip` within `providers/<provider_name>/`. We will specify the exact file format when we start to see more robust artifacts submitted.
+CMP artifacts should be placed into a `artifacts_cmp.zip` within `providers/<provider_name>/[implementation_name/]`. We will specify the exact file format when we start to see more robust artifacts submitted.
 
 ## Old Zip Format (R2)
 

diff --git a/src/pqc_report_writer_certs_r3.py → src/pqc_report_writer_common.py b/src/pqc_report_writer_certs_r3.py → src/pqc_report_writer_common.py
@@ -6,8 +6,6 @@
 from typing import NamedTuple, Optional, Sequence, Mapping
 from mdutils.mdutils import MdUtils
 
-OUTPUT_FILE = 'pqc_hackathon_results_certs_r3.md'
-
 _FILENAME_REGEX = re.compile(r'^(?P<generator>[^_]+)_(?P<verifier>[^.]+)\.(?P<extension>(csv|json))$', re.IGNORECASE)
 _OID_MAPPING_LINE_REGEX = re.compile(r'^\|\s*(?P<name>[^|]+)\s*\|\s*(~~)?(?P<oid>\d+(\.\d+)+)\*?(~~)?\s*\|.*$')
 _HYBRID_FORMAT_NAME_REGEX = re.compile(r'(?P<hybrid_format>[^_]+)_(?P<oid1>[^_]+)_with_(?P<oid2>[^_]+)', re.IGNORECASE)
@@ -122,6 +120,8 @@ def _get_alg_name_by_oid_str(oid_to_name_mappings, oid_str):
 def main():
     parser = argparse.ArgumentParser()
     parser.add_argument('oid_mapping_file', type=argparse.FileType('r'))
+    parser.add_argument('outfile')
+    parser.add_argument('interop_type')
     parser.add_argument('files', nargs='+')
 
     args = parser.parse_args()
@@ -163,7 +163,7 @@ def main():
     for avr in avrs:
         avrs_by_alg[avr.key_algorithm_oid].append(avr)
 
-    md_file = MdUtils(file_name=OUTPUT_FILE, title='IETF PQC Hackathon Interoperability Results')
+    md_file = MdUtils(file_name=args.outfile, title=f'IETF PQC Hackathon {args.interop_type} Interoperability Results')
 
     md_file.new_paragraph(text="<style> table { border-collapse: collapse; } th, td { border: solid black 1px; padding: 0 1ex; } </style>")
 

diff --git a/src/rebuild_results_certs_r3.sh b/src/rebuild_results_certs_r3.sh
@@ -10,8 +10,7 @@ for dir in $dirs; do
 done
 
 # build the compat matrix
-# outputs to `pqc_hackathon_results.md`
-python3 pqc_report_writer_certs_r3.py ../docs/oid_mapping.md $files
+python3 pqc_report_writer_common.py ../docs/oid_mapping.md pqc_hackathon_results_certs_r3.md Certificate $files
 
 # convert to html
 pandoc -f markdown pqc_hackathon_results_certs_r3.md > pqc_hackathon_results_certs_r3.html