OpenSSL Strategic Architecture

Original author: OpenSSL Management Committee
  • Transfer
In this document, the OpenSSL Management Committee outlines the basic principles of the OpenSSL strategic architecture. Starting with 3.0.0, several versions will be required to move from the current architecture (version 1.1.1) to the future.

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

The current functionality provided by the engine interface will be replaced by the software interface over time. OpenSSL 3.0.0 will retain engine support. Future architecture can be fully implemented no earlier than OpenSSL 4.0.0.

Current architecture


OpenSSL currently has 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 protocol implementations such as CMS and OCSP.
  2. The engine. The functionality of libcrypto can be extended through the engine API.

    Typically, engines are dynamically loaded modules registered in libcrypto and using available hooks to implement cryptographic algorithms, most often alternative implementations of algorithms already provided by libcrypto (for example, with hardware acceleration support), but they may also include algorithms that are not implemented in OpenSSL by by default (for example, the GOST mechanism implements the Russian GOST family of algorithms). Some engines come with the OpenSSL distribution, while others come with 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 components of libssl and libcrypto 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 Verification
    • and etc.

    OpenSSL currently has the following features:

    1. EVP The EVP layer (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. It also provides compound operations such as signing and verification. Some compound 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 available only in OpenSSL-1.0.2, which is prior to the current architecture and is not compatible with API or ABI.

    Component Concept


    The existing architecture is a simple four-level structure with a crypto layer at the bottom. 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 Diagram


    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 launching various applications. This is shown in the diagram below.



    Future architecture


    Features of future architecture:

    • Kernel services form the building blocks used by applications and providers (for example, BIO, X509, SECMEM, ASN1, etc.).
    • Suppliers use cryptographic algorithms and support services. A provider implements one or more of the following functions:

      • Cryptographic primitives for the algorithm: encryption, decryption, signature, hashing, etc.
      • Serialization for the algorithm, for example, the function of converting the private key to a PEM file. Serialization can be in formats or from formats that are not currently supported.
      • Store loader backend. OpenSSL currently ships with a bootloader for reading keys, parameters, and other elements from files. Vendors can implement downloaders to read data from other places (for example, from an LDAP directory).

      The provider can be fully autonomous or use services provided by different providers or kernel services. For example, an application may use cryptographic primitives for an algorithm implemented by a hardware accelerator vendor, but use another vendor's serialization services to export keys to PKCS # 12 format.

      The default provider (which contains the core of current implementations of the OpenSSL cryptographic algorithm) will be “built-in,” but other providers will be able to dynamically load at run time.

      The module (s) of the legacy providers will provide cryptographic implementations for older algorithms (e.g. DES, MDC2, MD2, Blowfish, CAST). We will post rules on how and when algorithms go from a default provider to an outdated provider.

      The 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). Vendors give the kernel access to methods. A kernel is a mechanism by which specific implementations of things like algorithms are discovered.

      The kernel implements a property-based search function to find algorithms. For example, this will find an algorithm where "fips = true" or "keysize = 128, constant_time = true". Details will be published in subsequent project documents.
    • Protocol implementations such as TLS, DTLS.

    Future architecture has the following characteristics:

    • The EVP layer becomes a thin wrapper for services implemented through suppliers. Most calls go through with minimal pre-processing, post-processing, or no processing at all.
    • New EVP APIs will appear to search the kernel for the 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.
    • Deprecated APIs (such as low-level cryptographic APIs that do not pass through the EVP layer) will be excluded. Note that there are outdated APIs for algorithms that are not outdated (for example, AES is not an outdated algorithm, but AES_encrypt is an outdated API).
    • The OpenSSL FIPS cryptographic module will be implemented as a dynamically loaded provider. It will be autonomous (i.e., it may depend only on the system runtime libraries and services provided by the kernel).
    • Other interfaces can also be converted to using the kernel over time (for example, OSSL_STORE).
    • Using the engine goes to the suppliers. "Bye-bye, engineers, hello, suppliers . "

    Component Concept


    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: implementation of 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: Implementing the Cryptographic Message Syntax Standard
        • OCSP: Implementation of Online Certificate Status Protocol
        • TS: Timestamp Protocol Implementation
      • Support Services: Components specifically designed to support protocol code implementation
        • Packet: internal component for reading protocol messages
        • Wpacket: an internal component for recording protocol messages
    • Kernel: This is the fundamental component that connects service requests (e.g., encryption) to the service provider. 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 should execute. For example, encryption service properties may include "aead", "aes-gcm", "fips", "security-bits = 128", and so on.
    • Default Provider: Implements a set of default services registered in the kernel.
      • Support Services
        • Low-level implementations: this is a set of components that actually implement cryptographic primitives.
    • FIPS provider: implements a set of services that are 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 set of components that actually implement cryptographic primitives (to satisfy 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 may sell their own suppliers.
    • General services: form the building blocks used by applications and suppliers (for example, BIO, X509, SECMEM, ASN1, etc.).
    • Deprecated APIs. "Low-level" API: here the word "obsolete" refers specifically to the API, and not to the algorithm itself. For example, AES is not an outdated algorithm, but there are outdated APIs for it (for example, AES_encrypt).

    Package Diagram


    The various components described above in the conceptual diagram of the components are physically packaged in:

    • Executable applications for users
    • Library (s) for applications
    • Dynamically loadable module (s) for the kernel.




    The following actual packages are shown here:

    • The executable file is OpenSSL. Command line application.
    • Libssl. Contains everything that is directly related to TLS and DTLS. Its contents are much the same as in the current libssl. Note that some support services will be moved to libcrypto.
    • Libcrypto This library contains the following components:
      • Implementations of the main services: X509, ASN1, EVP, OSSL_STORE, etc.
      • Core
      • Non-TLS or DTLS Protocols
      • Protocol Support Services (e.g. Packet and Wpacket)
      • Default provider containing implementations of all default algorithms
    • Libcrypto-legacy. Provides legacy low-level APIs. The implementation of the algorithms for these APIs may come from any provider.
    • 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.

Also popular now: