Configure OpenSSL

You want your app to load a specific OpenSSL installation at startup and turn on post-quantum mode, or to stop with a clear message if that doesn't work.

Run this code once when your app starts, before the first cryptographic operation:

using System.Security.Cryptography;
using System.Security.Cryptography.X509Certificates;
using WKL.System.Security.Cryptography;
using WKL.System.Security.Cryptography.X509Certificates;
 
PostQuantumConfig.OpenSslPath = @"C:\OpenSSL\bin";
try
{
    PostQuantumConfig.EnablePostQuantum(CryptoMode.Hybrid);
}
catch (CryptographicException ex)
{
    Console.Error.WriteLine($"Post-quantum mode isn't available: {ex.Message}");
    throw;
}

The library picks the file based on the operating system and the process architecture:

Without OpenSslPath, the operating system's library search applies. That's enough if the first file the search finds belongs to OpenSSL 3.5 or later. On Windows, always set OpenSslPath.

• Provider. The library registers the provider that computes the PQ algorithms through OpenSSL on first use, as long as the WKL.System.Security.Cryptography.Extensions assembly is part of your app. You only need CryptoProviderFactory.RegisterProvider for a different provider, such as the WebAssembly provider in Blazor WebAssembly.
• Linux: the OpenSSL that .NET loads. OpenSslPath only applies to this library's calls. On Linux, X509Chain and the .NET PFX import load the system's libcrypto themselves. If that version lacks ML-DSA, as OpenSSL 3.0 on Ubuntu 24.04 does, building a chain with a pure ML-DSA issuer fails. In that case, have .NET load your OpenSSL 3.5 or later installation as well, by setting LD_LIBRARY_PATH to its library folder before the process starts. Hybrid certificates with an RSA or ECDSA key aren't affected.
• Multiple OpenSSL copies on Windows. Git, VPN clients, and other programs ship their own, often older, OpenSSL files. The Windows search takes the first one it finds. OpenSslPath pins the installation.
• Once per process. The library loads OpenSSL on first use and keeps that choice until the process ends. If you set OpenSslPath to a different value afterward, the next operation throws a CryptographicException instead of silently ignoring the new value.
• Error messages name the path and the version. If the folder or the file is missing, EnablePostQuantum throws a CryptographicException that names the path. If the loaded installation doesn't provide ML-DSA-65 or ML-KEM-768, the message names the algorithm, the version, and the path. In both cases, DefaultMode stays unchanged. To fix these errors, see OpenSSL doesn't load and OpenSSL doesn't provide ML-DSA or ML-KEM.
• Path from configuration. In apps with a configuration file, read the path from configuration, so that each environment can specify its own installation without a rebuild.

• Prerequisites
• Crypto modes and call binding
• No crypto provider is registered
• OpenSSL doesn't load