In this document, the OpenSSL Management Committee outlines the basic principles of the OpenSSL strategic architecture. Starting from 3.0.0, several versions are required to move from the current architecture (version 1.1.1) to the future one.

Numerous changes are expected in the architecture. We offer a possible migration path. The release of OpenSSL 3.0.0 will minimally affect the vast majority of existing applications, almost all competent applications just need to be recompiled.

The current functionality provided by the engine interface will eventually replace the program interface. OpenSSL 3.0.0 will retain engine support. Future architecture can be fully implemented no earlier than OpenSSL 4.0.0.

Current architecture

Currently, OpenSSL consists of four main components:
')

1. libcrypto. The main library for providing implementations of numerous cryptographic primitives. In addition, it provides a set of supporting services for libssl and libcrypto, as well as the implementation of protocols such as CMS and OCSP.
   
2. Engine The functionality of libcrypto can be extended through the API of the engine.
   
   Typically, engines are dynamically loaded modules that are registered in libcrypto and use available hooks to implement cryptographic algorithms, most often alternative implementations of algorithms already provided by libcrypto (for example, with hardware acceleration), but they can also include algorithms that are not implemented in OpenSSL by default (for example, the GOST mechanism implements a family of algorithms of the Russian GOST). Some engines come with the OpenSSL distribution, and others - by third parties (again, GOST).
   
3. libssl. A library that depends on libcrypto and implements the TLS and DTLS protocols.
   
4. Applications. A set of command line tools that use the basic libssl and libcrypto components to provide a set of cryptographic and other functions, such as:
   
   
   • Generation and verification of keys and parameters
     
   • Certificate Generation and Verification
     
   • SSL / TLS Testing Tools
     
   • ASN.1 check
     
   • and etc.
   
   Currently, OpenSSL has the following characteristics:
   
   
   1. EVP. The EVP (envelope) API provides a high-level abstract interface for cryptographic functionality, without being tied to a specific implementation. Direct use of specific implementations of cryptographic algorithms bypassing EVP interfaces is not recommended. Composite operations such as signing and verification are also provided. Some composite operations are also provided as an EVP level operation (for example, HMAC-SHA256). EVP also allows the use of cryptographic algorithms in an algorithmic-agnostic manner (for example, EVP_DigestSign works for both RSA and ECDSA algorithms).
      
   2. FIPS140 is not supported, it is only available in OpenSSL-1.0.2, which precedes the current architecture and is incompatible with the API or ABI.
   
   

   Component conceptual diagram

   
   The existing architecture is a simple four-level structure with a crypto layer below. The TLS layer depends on the cryptographic layer, and applications depend on both the TLS layer and the cryptographic layer.
   
   Note: the presence of a component in the diagram does not mean that the component is a public API or is intended for direct access / use by the end user.
   
   
   
   

   Package Scheme

   
   The components described above are packaged in libraries (libcrypto and libssl) and the corresponding kernel interfaces, as well as the command line executable (openssl) for running various applications. This is shown in the diagram below.
   
   
   
   

   Future architecture

   
   Features of the future architecture:
   
   
   • Kernel services form the building blocks used by applications and vendors (for example, BIO, X509, SECMEM, ASN1, etc.).
     
   • Suppliers use cryptographic algorithms and ancillary services. The provider implements one or more of the following functions:
     
     
     • Cryptographic primitives for the algorithm: encryption, decryption, signature, hashing, etc.
       
     • Serialization for an algorithm, such as the function of converting a private key to a PEM file. Serialization can be carried out in formats or from formats that are not currently supported.
       
     • Backend loader storage (store loader). Currently OpenSSL comes with a bootloader for reading keys, parameters, and other elements from files. Vendors can implement loaders to read data from other places (for example, from an LDAP directory).
     
     A provider can be completely autonomous or use services provided by different providers or kernel services. For example, an application might use cryptographic primitives for an algorithm implemented by a device vendor for hardware acceleration, but use another provider’s serialization services to export keys to the PKCS # 12 format.
     
     The default vendor (which contains the core of the current implementations of the OpenSSL cryptographic algorithm) will be “embedded”, but other vendors will be able to dynamically load at run time.
     
     The module (s) of obsolete suppliers will provide cryptographic implementations for older algorithms (for example, DES, MDC2, MD2, Blowfish, CAST). We will publish the rules as and when the algorithms go from the default provider to the outdated provider.
     
     A FIPS provider that implements the OpenSSL FIPS cryptographic module can dynamically load at run time.
     
   • The kernel provides access to services offered by application providers (and others). Providers give the kernel access to methods. The kernel is the mechanism by which specific implementations of such things as algorithms are detected.
     
     The kernel implements a search function based on properties for finding algorithms. For example, this will allow you to find an algorithm where "fips = true" or "keysize = 128, constant_time = true". Details will be published in subsequent project documents.
     
   • Implementing protocols such as TLS, DTLS.
   
   The future architecture has the following characteristics:
   
   
   • The EVP layer becomes a thin wrapper for services implemented through providers. Most calls go through with minimal or no post-processing or no processing at all.
     
   • New EVP APIs will appear to search the core implementation of the algorithm that will be used for any EVP call.
     
   • Information will be transferred between the main library and suppliers in the same way, regardless of their implementation.
     
   • Legacy APIs (for example, low-level cryptographic APIs that do not pass through the EVP level) will be excluded. Please note that there are obsolete APIs for algorithms that are not obsolete (for example, AES is not an obsolete algorithm, but AES_encrypt is an obsolete API).
     
   • The OpenSSL FIPS cryptographic module will be implemented as a dynamically loadable provider. It will be autonomous (that is, it can depend only on runtime system libraries and services provided by the kernel).
     
   • Other interfaces, too, over time can be translated to use the kernel (for example, OSSL_STORE).
     
   • Using the engine goes to the suppliers. “Bye-bye, engineers, hello suppliers . ”
   
   

   Component conceptual diagram

   
   The diagram below provides an overview of the components of the future OpenSSL architecture.
   
   Note: the presence of a component in the diagram does not mean that the component is a public API or is intended for direct access / use by the end user.
   
   
   
   The following components are shown here:
   
   
   • Applications: command line utilities: ca, ciphers, cms, dgst, etc.
     
   • Protocols: the component provides the ability to communicate between endpoints using standard protocols:
     
     • TLS Protocols: Implement all supported TLS / DTLS protocols and serving infrastructure:
       
       • SSL BIO: BIO for TLS communication
         
       • Statem: TLS state machine
         
       • Record: TLS Record Layer
     • Other protocols
       
       • CMS: implementation of the standard Cryptographic Message Syntax
         
       • OCSP: Online Certificate Status Protocol Implementation
         
       • TS: Timestamp Protocol implementation
     • Ancillary services: components specifically designed to support the implementation of the protocol code
       
       • Packet: internal component for reading protocol messages
         
       • Wpacket: internal component for recording protocol messages
   • Kernel: This is the fundamental component that connects requests for a service (for example, encryption) with a service provider for that service. It enables suppliers to register their services along with their properties. The kernel also provides the ability to find a service with a given set of properties that the service must perform. For example, encryption service properties can include "aead", "aes-gcm", "fips", "security-bits = 128", etc.
     
   • Default Provider: implements a set of default services registered in the kernel.
     
     • Auxiliary services
       
       • Low-level implementations: this is a set of components that actually implement cryptographic primitives.
   • FIPS provider: implements a set of services verified and available to the FIPS core. Includes the following support services:
     
     • POST: Power On Self Test
       
     • KAT: Known Answer Tests
       
     • Integrity check
       
     • Low-level implementations: this is a collection of components that actually implement cryptographic primitives (to meet the stand-alone FIPS requirement).
   • Legacy Algorithm Provider: provides implementations of legacy algorithms that will be provided through the EVP API.
     
   • Third Party Provider: Not part of the OpenSSL distribution. Third parties can sell their own suppliers.
     
   • Common Services: form the building blocks used by applications and suppliers (for example, BIO, X509, SECMEM, ASN1, etc.).
     
   • Outdated API. "Low-level" API: here the word "obsolete" refers specifically to the API, and not to the algorithm itself. For example, AES is not an obsolete algorithm, but there are obsolete APIs for it (for example, AES_encrypt).
   
   

   Package Scheme

   
   The various components described above in the conceptual diagram of the components are physically packaged in:
   
   
   • Executable applications for users
     
   • Library (libraries) for applications
     
   • Dynamically loadable module (s) for the kernel.
   
   
   
   
   The following actual packages are shown here:
   
   
   • OpenSSL executable file. Command line application
     
   • Libssl. Contains everything directly related to TLS and DTLS. Its contents are much the same as in the current libssl. Note that some helper services will be moved to libcrypto.
     
   • Libcrypto. This library contains the following components:
     
     • Implementing core services: X509, ASN1, EVP, OSSL_STORE, etc.
       
     • Core
       
     • Protocols not related to TLS or DTLS
       
     • Protocol support services (for example, Packet and Wpacket)
       
     • Default provider containing implementations of all default algorithms
   • Libcrypto-legacy. Provides outdated low-level APIs. The implementation of the algorithms for these APIs can come from any supplier.
     
   • FIPS module. Contains a FIPS provider that implements a set of services verified by FIPS and registered in the kernel.
     
   • Legacy module. Contains an outdated provider.