About RTI’s OpenSSL CNG Engine¶
OpenSSL is a widely used open source crypto suite that supports multiple operating systems. It includes crypto, a library that implements a wide range of cryptographic algorithms used in various Internet standards. Several of these built-in implementations can be replaced by plugging in a different so-called engine.
This OpenSSL CNG Engine project implements an engine for transparently leveraging Windows’ Cryptography API: Next Generation (CNG) with OpenSSL. It supports CNG’s Cryptographic Primitives as well as some of its Key Storage and Retrieval mechanisms and legacy CryptoAPI (CAPI) functionality for certificates.
You may want to use this engine if you prefer to use the OpenSSL API over the Windows CNG API directly. The only OpenSSL branch supported is 1.1.1 and only the latest version, currently 1.1.1i, is CI-tested.
Functionality provided¶
This engine actually consists of two different components, indicated for short here as EVP and STORE.
EVP (envelope)¶
The first component is a “traditional” engine that redirects the EVP high-level cryptographic functions to their equivalent algorithms implemented by CNG Cryptographic Primitive Functions. These functions are exposed via the bcrypt.h header file in the Windows SDK, and provided by the Bcrypt.dll library. Therefore, the associated naming convention for the CNG Engine is to use bcrypt in project names, like engine-bcrypt or lib-evp-bcrypt.
Algorithm |
Remarks |
|---|---|
AES-GCM with 128, 192 or 256 bits key |
|
512 bits ≤ key size ≤ 4096 bits |
|
Not yet implemented |
|
ECDH and ECDSA with P-256, P-384 and P-521 |
|
SHA-1, SHA-256, SHA-384 and SHA-512 |
|
HMAC with SHA |
|
Default CNG random number provider |
|
512 bits ≤ key size ≤ 16384 bits |
For a more comprehensive overview, see section BCrypt EVP algorithms.
Note that cryptographic key material in the EVP engine is ephemeral, generated at runtime with the help of the random number generator.
STORE (ossl_store)¶
The second component is a CNG-based implementation of an OpenSSL STORE. The store component currently supports enumerating over, addressing and using public key certificates and (private) keys. For that, the loader leverages, among others, CNG Key Storage Functsion. These functions are exposed via the ncrypt.h header file in the Windows SDK, and provided by the Ncrypt.dll library. Therefore, the associated naming convention for the CNG Engine is to use ncrypt in project names, like engine-ncrypt or lib-store-ncrypt. Additionally, it leverages functions to interact with the Certificate Store.
The URI addressing schema format aligns with the PowerShell’s Certificate Provider. For a detailed overview of the supported store mechanisms, see section NCrypt STORE operations.
Note that the cryptographic material used by the STORE engine typically includes long-term keypairs as stored in the key storage.
Windows and toolchains versions¶
Not all possible combinations of Windows OS, SDK and Visual Studio version combinations are tested. Windows 10 is currently assumed, although other versions may work as well. Due to the usage of C++17 features in the test applications, Visual Studio versions older than 2017 will not be able to build those.
Visual Studio |
SDK |
Remarks |
|---|---|---|
VS2019 (v142) |
10.0.19041.0 (2004) |
CI-tested |
10.0.18362.0 (1903) |
||
10.0.17763.0 (1809) |
||
VS2017 (v141) |
10.0.19041.0 (2004) |
|
10.0.18362.0 (1903) |
CI-tested |
|
10.0.17763.0 (1809) |
For more detailed information on the toolchain, including build-time and runtime dependencies on 3rd party components, see section Building the solution. For some known limitations of certain Windows versions, see section Known limitations.