search

IETF-Hackathon / pqc-certificates

Post-quantum cryptography certificates
Other
35 stars 21 forks source link

readme

IETF Hackathon - PQC Certificates

This project provides a set of data repositories for X.509 data structures that make use of post-quantum and composite algorithms (classic with PQC).

This repo represents work done between IETF 115 - 120.

The various output compatibility tables produced by this project can be viewed here:

https://ietf-hackathon.github.io/pqc-certificates/

Goals

Contributing and testing your artifacts

Simply upload your artifacts zip files into your own directory under providers/, and uploads test results CSV files into the compatMatrices/ directory of your provider, and the github automation will:

NOTE: expired certificates within the artifacts zips will show as failed against the OQS automated testing because there is no flag to openssl verify to ignore expiry. We recommend uploading certs with very long expiry times -- like 10 years or more -- so that they do not start failing one year from now.

Also note that for legibility, the main table is filtered to only show the "modern" set of algorithm OIDs as represented it [docs/oids.json]. Providers which do not provide any of these OIDs will not be shown.

Folder structure of this repo

The project's directory structure is as follows:

    - main_project_dir
    - Makefile
    - docs/
    - providers/
        - provider_name_1/
            - 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
                - unzip, generate, verify, and cross_verify targets
        - provider_name_2
            - implementation_name_1
            - ...

Note that some vendors have multiple providers with artifacts. Due to automation for generating the results HTML page which takes the provider name from the directory name; please create a new top-level provider directory for each of your providers.

Where:

Zip Format (R3)

Certificates - artifacts_certs_r3.zip

Starting with artifacts for the NIST Draft standards released 2023-08-24, we will use a much simpler artifact format:

Within providers/<provider_name>/[implementation_name/]

The KEM end entity certificate can be used to validate encrypted artifacts in either the CMS or CMP artifacts zips.

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/]

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 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 KMAC128-KDF* id-kmac128*
cms-kyber ML-KEM-768 KMAC256-KDF* id-kmac256*
cms-kyber ML-KEM-1024 KMAC256-KDF* id-kmac256*
- kyber512 KMAC256-KDF* id-kmac128*
- kyber768 KMAC256-KDF* id-kmac256*
- kyber1024 KMAC256-KDF* id-kmac256*

* The MTI artifacts were updated to KMAC-based KDFs in draft-ietf-lamps-cms-kyber-03.

CMP -- artifacts_cmp.zip

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)

OLD -- IF YOU ARE SUBMITTING ARTIFACTS AGAINST THE NIST DRAFT SPECS AS OF 2023-08-24, THEN PLEASE USE THE R3 FORMAT ABOVE.

At the hackathon, we are all going to script our PKI toolkit to produce and read zip bundles of certs in the following format. Scripts should place data into files with the following names so that parsing scripts

(parentheses denotes optional files)

NOTE: The OCSP filename has changed from R1 (ocsp.der) to R2 (ocsp_ca.der) amd ocsp_cert.der for the OCSP responses for the Intermediate CA and the EE certificate.

OIDs

The OID mappings to be used for this hackathon are documented in oid_mapping.md.

Unzipping Artifacts

The repository comes with a Makefile that is meant to ease and automate the operations for unzipping, generating, and validating the artifacts provided.

To accommodate for different options from different providers, there are three primary targets for the Makefile:

Specifically, to unzip all the artifacts from all the providers, simply use the following:

$ make unzip

To run the verify for all the providers:

$ make verify

To run the verify from a single provider, simply change the directory to the specific provider and run the same command:

$ cd providers/<provider_name>
$ make verify

Interoperability Results

Instructions for documenting each provider's compatibility test results can be found in compat_matrix_intructions.md.