WKL.System.Security.Cryptography overview

Preview: This library is published as a preview. Types, methods, and data formats can change before the first supported release.

graph TD
    APP["Your app: existing code that uses RSA, ECDSA, X509Certificate2, SignedCms, SignedXml"]
    EXT["WKL extensions: same method, extra CryptoMode argument"]
    FW[".NET: classical part, RSA, ECDSA, certificates, CMS, XML"]
    OSSL["OpenSSL 3.5 or later: post-quantum part, ML-DSA, ML-KEM"]
    APP -- "call without CryptoMode" --> FW
    APP -- "call with CryptoMode" --> EXT
    EXT -- "classical part" --> FW
    EXT -- "post-quantum part" --> OSSL

Figure: A call without CryptoMode still goes straight to .NET. Only the extra argument routes the call through the library, which leaves the classical part to .NET and has OpenSSL compute the post-quantum part.

WKL.System.Security.Cryptography adds post-quantum (PQ) algorithms to .NET cryptography: the ML-DSA signature (FIPS 204) and the ML-KEM key encapsulation mechanism (FIPS 203). It's built for teams that maintain apps on .NET Framework 4.6.2 or later, or on .NET 8, and need to protect certificates, signatures, and encrypted messages against future quantum computers without rewriting those apps. You add PQ protection where you need it: at a single call site, with one argument.

• Defaults that follow BSI TR-02102-1: Unless you opt in to more, the library only creates data with the PQ algorithms and parameter sets that the German Federal Office for Information Security (BSI) recommends in Technical Guideline TR-02102-1 (2026-01). Your app allows anything beyond that explicitly and is notified of every use through an event.
• Hybrid and pure PQ certificates: Certificates, certificate revocation lists (CRLs), and certificate requests carry an additional ML-DSA signature next to RSA or ECDSA (hybrid), or ML-DSA alone (as defined in RFC 9881).
• Chain validation that includes the PQ part: On request, X509Chain.Build verifies every ML-DSA signature in the chain after the classical validation.
• Signatures: Raw signatures as composite ML-DSA (RSA or ECDSA combined with ML-DSA) or as pure ML-DSA, and PQ signatures in CMS messages (SignedCms) and XML documents (SignedXml).
• Encryption: CMS messages for recipients with an ML-KEM or composite ML-KEM key (KemEnvelopedCms), and hybrid key agreement from ECDH and ML-KEM, combined with KeyCombine as defined in NIST SP 800-227.
• Key transport and storage: PFX files carry the PQ key in a standard PKCS#12 key bag, encrypted with AES-256, so other programs can still read the file. Next to the certificate store, the operating system's key store protects the PQ keys.
• One feature set for every target: The same features run on .NET Framework 4.6.2 through 4.8, .NET Core 3.1, and .NET 8. Where .NET Framework 4.6.2 doesn't have a type yet, such as CertificateRequest, the library provides its own building blocks. For the differences between targets, see Target frameworks.
• Blazor: Blazor Server uses the library like any other .NET app. In Blazor WebAssembly, ML-DSA and ML-KEM are available through a separate asynchronous API that runs OpenSSL as WebAssembly in the browser.

Extend, don't replace. The library doesn't change any .NET method. It provides extension methods with the same name and parameters as the original and appends one optional argument, CryptoMode? mode. The C# compiler always binds a call without that argument to the .NET method, so existing code behaves exactly as before, bit for bit. For details, see Crypto modes and call binding.

Recommendations as defaults. Without an opt-in, everything the library creates follows BSI TR-02102-1: ML-DSA-65 and ML-DSA-87, ML-KEM-768 and ML-KEM-1024, each combined with a classical algorithm. Existing data that uses other algorithms stays verifiable and readable. For details, see Post-quantum algorithm policy.

Same behavior as the original. With CryptoMode, an extension keeps the return type, exceptions, and error message of the .NET method; only the content is classical, hybrid, or pure PQ. If the requested PQ part fails, the call fails the way the original would. The library never silently falls back to a classical-only result.

Division of labor. .NET still computes the classical part (RSA, ECDSA, AES, certificate validation). Only OpenSSL 3.5 or later computes the PQ part. The library combines both into data formats that classical verifiers can still read. For the formats, see Formats of the post-quantum parts.

• OpenSSL is part of your operations. The library doesn't ship OpenSSL. You need an installation of version 3.5 or later whose libraries match the process architecture and provide ML-DSA and ML-KEM, and you apply its security updates yourself.
• Only through the .NET abstractions. Code that hard-codes key sizes, bypasses RSA and ECDsa, or builds algorithm names from strings doesn't gain PQ protection from an extra argument.
• No TLS. The library covers algorithms, keys, certificates, and message formats, but not the TLS handshake. Post-quantum HTTPS is the job of a separate transport layer.
• Provisional identifiers. The CMS attributes for PQ signatures and the XML signature methods for ML-DSA use provisional identifiers, because no standard assigns identifiers for them yet. Only peers that use this library verify these parts; classical verifiers still read the messages.
• Key storage on Windows and Linux. The library stores PQ keys next to the certificate store only where an operating system key store protects them: on Windows, and on Linux with Secret Service. On other systems, keep the keys in a PFX file; see Keys and key storage.
• No certification. The defaults follow the recommendations of BSI TR-02102-1. They aren't an approval or a certification under any evaluation scheme.

• Get started
• Concepts
• How-to guides
• Reference
• Troubleshooting