Formats of the post-quantum parts

graph TD
    CERT["Hybrid certificate"]
    TBS["TBSCertificate with three noncritical extensions"]
    SPKI["subjectAltPublicKeyInfo: the subject's ML-DSA key"]
    ALG["altSignatureAlgorithm: ML-DSA parameter set"]
    VAL["altSignatureValue: the issuer's ML-DSA signature"]
    SIG["Classical signature: RSA or ECDSA over the entire TBSCertificate"]
    CERT --> TBS
    CERT --> SIG
    TBS --> SPKI
    TBS --> ALG
    TBS --> VAL

Figure: A hybrid certificate is an ordinary X.509 certificate. The post-quantum part sits in three noncritical extensions, which the classical signature also covers.

The library stores every post-quantum (PQ) part so that software without PQ support can still read and verify the data. Where a standard defines a format, the library follows it. Where no standard exists yet, the library uses provisional identifiers; this page lists those cases.

• Hybrid certificates and CRLs with alternative signatures as defined in ITU-T X.509 (10/2019).
• Pure ML-DSA certificates as defined in RFC 9881.
• Composite ML-DSA for raw signatures, following the IETF draft draft-ietf-lamps-pq-composite-sigs.
• CMS encryption for ML-KEM as defined in RFC 9629 (KEMRecipientInfo).
• PFX files as defined in RFC 7292, with the ML-DSA key in a key bag of its own.
• Provisional: PQ signatures in CMS and XML, and hybrid encryption with EncryptHybrid.

A hybrid certificate carries three noncritical extensions from ITU-T X.509 (10/2019):

The ML-DSA signature covers the TBSCertificate without the altSignatureValue extension. The classical signature covers the entire TBSCertificate, including all three extensions. A classical verifier skips unknown noncritical extensions and validates the certificate like any other. CRLs from X509CrlBuilder carry their additional signature the same way.

Certificates in PostQuantum mode carry the ML-DSA key as a standard SubjectPublicKeyInfo and are signed with ML-DSA, as RFC 9881 specifies. The library supports the parameter sets ML-DSA-44, ML-DSA-65, and ML-DSA-87. Which of them create data without an exemption is governed by the Post-quantum algorithm policy.

Raw signatures in Hybrid mode are composite ML-DSA signatures as defined in the IETF draft draft-ietf-lamps-pq-composite-sigs (revision 19): an ML-DSA signature followed by the RSA or ECDSA signature. The draft defines fixed pairs, and the library supports these. The Hash algorithm column lists the value that you pass to SignData and VerifyData:

The library rejects any other pair, such as ML-DSA-65 with RSA-2048, with a CryptographicException. The pairs with ML-DSA-44 sign only with the ReducedParameterSets exemption; you can verify them without it. Ed25519 and Ed448 aren't supported, because .NET 8 doesn't provide EdDSA.

KemEnvelopedCms writes CMS EnvelopedData (RFC 5652) with KEMRecipientInfo (RFC 9629). For ML-KEM, the format matches what OpenSSL 3.6 writes. For composite ML-KEM, it follows the IETF draft draft-ietf-lamps-cms-composite-kem. RSA recipients of the same message get a KeyTransRecipientInfo with RSAES-OAEP.

The .NET EnvelopedCms class can't decode a message that contains a KEMRecipientInfo, not even for an RSA recipient of the same message. Open mixed messages with KemEnvelopedCms instead.

ExportPfx writes a PKCS#12 file as defined in RFC 7292. The ML-DSA key sits in an additional encrypted key bag next to the classical key, and the same localKeyId links it to the certificate. ML-KEM and composite ML-KEM keys are stored in the file the same way. Other programs read the certificate and the classical key as usual and skip the additional bag. For how the file is encrypted, see Keys and key storage.

No standard assigns identifiers for the following cases yet, so the library uses provisional identifiers. Only peers that use this library verify the PQ part; classical verifiers still read the data.

The classical signature protects the announcement in CMS. If someone strips the PQ signature, a verifier that uses this library detects the downgrade and rejects the message.

• Provisional identifiers aren't registered. A future standard will assign different identifiers. Use PQ signatures in CMS and XML only between apps that use this library, and don't rely on these identifiers alone when you archive signed documents for the long term.
• Drafts aren't standards. Composite ML-DSA and composite ML-KEM follow specific revisions of IETF drafts. A peer that implements a different revision can reject such signatures and messages.
• Proprietary binary format only between your own apps. EncryptHybrid and PqCrypto aren't suitable for exchanging data with third-party software. For that, use KemEnvelopedCms.

• Crypto modes and call binding
• Keys and key storage
• Sign CMS messages
• Sign XML documents
• Encrypt CMS messages