OpenSSL Engines

Before providers were introduced in OpenSSL 3.0, external cryptographic modules were integrated through the engine framework. Engines allow OpenSSL to delegate operations such as key storage, signing, or encryption to external libraries or hardware modules, including Hardware Security Modules (HSMs) and operating system cryptographic services. While engines remain supported for compatibility, they are gradually being replaced by the more flexible and extensible provider interface.

CNG Engine

The CNG engine is an OpenSSL 3.x engine designed to integrate the Windows Cryptography API: Next Generation (CNG) with OpenSSL-based applications. It serves as a drop-in replacement for the legacy OpenSSL Cryptography API (CAPI) engine.

Key Features

Compared to the CAPI engine, the CNG engine offers several enhancements:

• Support for negotiating recent versions of TLS, including TLS 1.3.
• Compatibility with OpenSSL 3.x's FIPS 140-2 mode of operation.
• Capability to retrieve X509 OpenSSL objects directly from the engine.

Compatibility with the OpenSSL CAPI Engine

New Engine Control Commands

• LOAD_CERT_CTRL: Retrieve an X509 certificate from the store (requires ENGINE_init()).
• VLOG_A: Set the logging callback.
• PIN: Set the PIN code or password for a protected key.

Supported CAPI Engine Control Commands

• debug_level: Set the debug level: 0=emerg, 1=alert, 2=crit, 3=err, 4=warning, 5=notice (default), 6=info, 7=debug.
• debug_file: Specify the debugging filename.
• store_name: Certificate store names (search all if not specified): MY, Root, Trust, CA, UserDS (CERT_SYSTEM_STORE_CURRENT_USER only).
• store_flags: Set certificate store flags: 0=CERT_SYSTEM_STORE_CURRENT_USER (default), 1=CERT_SYSTEM_STORE_LOCAL_MACHINE.
• list_options: Configure list options: 1=summary (default), 2=friendly name, 4=full printout, 8=PEM output, 16=XXX, 32=private key info.
• lookup_method: Select key lookup method: 1=substring (default), 2=friendlyname.
• list_csps: List available CNG Key Storage Providers (KSPs).
• csp_idx: Set CNG KSP by index.
• csp_name: Set CNG KSP by name (default used if not specified).
• list_certs: List all certificates in store (requires ENGINE_init()).
• lookup_cert: Lookup and output certificates (requires ENGINE_init()).

Unsupported CAPI Engine Control Commands

• csp_type: CSP type is zero if the key container is one of the CNG Key Storage Providers.
• list_containers: In CryptoAPI, the key container file is stored in a directory whose name is the textual equivalent of the user's SID. This behavior is not applicable in CNG, eliminating issues with domain migration and private key retention.
• key_type: Keys associated with a CNG Key Storage Provider (KSP) only support the CERT_NCRYPT_KEY_SPEC (0xFFFFFFFF) value. The AT_KEYEXCHANGE and AT_SIGNATURE values for legacy CAPI (non-CNG) certificates are unsupported.

Unsupported CAPI Engine Features

• DSA signatures and certificates