PROVIDER(7ossl)

📦 version 3.5.0, in opensuse-leap 16.0

🌸 PROVIDER(7ossl) 🌸 — the OpenSSL manual page, but make it make sense

okay so bestie, this is PROVIDER(7ossl), the OpenSSL manual page all about providers — and before you ask, no, it's not about your fave music provider or your streaming subscriptions, it's about OpenSSL's operation implementation providers. Trust me, it's more interesting than it sounds 💅✨

This page is literally for provider authors, so if you're writing one of these bad boys, this is your moment. Slay.

🎀 SYNOPSIS 🎀

#include <openssl/provider.h>

short and sweet, literally iconic, no notes 🫶

💖 DESCRIPTION 💖

💫 General 💫

Bestie, first things first: this page contains information useful to provider authors. That's the whole target audience. If that's you, welcome, you're the main character now.

A provider, in OpenSSL terms, is a unit of code that provides one or more implementations for various operations for diverse algorithms that one might want to perform. It's giving "I contain multitudes" energy.

An operation is something one wants to do — like encryption and decryption, key derivation, MAC calculation, signing and verification, etc. Basically the verbs of cryptographic life.

An algorithm is a named method to perform an operation. Very often, the algorithms revolve around cryptographic operations, but they may also revolve around other types of operation, such as managing certain types of objects. Not everything is crypto, iykyk.

See crypto(7) for further details. go read it, it's the lore 💜

🦋 Provider 🦋

A provider offers an initialization function, as a set of base functions in the form of an OSSL_DISPATCH(3) array, and by extension, a set of OSSL_ALGORITHM(3)s (see openssl-core.h(7)). It may be a dynamically loadable module, or may be built-in, in OpenSSL libraries or in the application. So it can either slide in at runtime or be born into the library. Both valid.

Here's the catch: if it's a dynamically loadable module, the initialization function must be named OSSL_provider_init and must be exported. No exceptions, periodt. If it's built-in, the initialization function may have any name. lucky them.

The initialization function must have the following signature:

        int NAME(const OSSL_CORE_HANDLE *handle,
                 const OSSL_DISPATCH *in, const OSSL_DISPATCH **out,
                 void **provctx);

Let's break down these parameters like a group chat screenshot:

  • handle — the OpenSSL library object for the provider, and it works as a handle for everything the OpenSSL libraries need to know about the provider. For the provider itself, it is passed to some of the functions given in the dispatch array in. It's like the provider's official ID card 🪪
  • in — a dispatch array of base functions offered by the OpenSSL libraries, and the available functions are further described in provider-base(7). This is the library saying "here's what I can do for you."
  • *out — must be assigned a dispatch array of base functions that the provider offers to the OpenSSL libraries. The functions that may be offered are further described in provider-base(7), and they are the central means of communication between the OpenSSL libraries and the provider. This is the provider's "here's what I can do for you" moment. iconic.
  • *provctx — should be assigned a provider specific context to allow the provider multiple simultaneous uses. This pointer will be passed to various operation functions offered by the provider. It's the provider's personal little state corner 🧚
⚠️ important vibe check: note that the provider will not be made available for applications to use until the initialization function has completed and returned successfully. No half-baked entrances. Finish the init, then you can party.

One of the functions the provider offers to the OpenSSL libraries is the central mechanism for the OpenSSL libraries to get access to operation implementations for diverse algorithms. It's referred to with the number OSSL_FUNC_PROVIDER_QUERY_OPERATION and has the following signature:

        const OSSL_ALGORITHM *provider_query_operation(void *provctx,
                                                       int operation_id,
                                                       const int *no_store);
  • provctx — the provider specific context that was passed back by the initialization function. same context, different function, consistency queen 💅
  • operation_id — an operation identity (see "Operations" below). You'll see the list, don't worry.
  • no_store — a flag back to the OpenSSL libraries which, when nonzero, signifies that the OpenSSL libraries will not store a reference to the returned data in their internal store of implementations. So no_store nonzero = no keepie, no storing, we're just browsing 😌

The returned OSSL_ALGORITHM(3) is the foundation of any OpenSSL library API that uses providers for their implementation, most commonly in the fetching type of functions (see "ALGORITHM FETCHING" in crypto(7)). This is the whole reason providers exist, bestie. The foundation. The blueprint. The moment.

🔥 Operations 🔥

Operations are referred to with numbers, via macros with names starting with "OSSL_OP_". cute little numeric IDs, very demure.

With each operation comes a set of defined function types that a provider may or may not offer, depending on its needs. You don't have to offer everything — you're not obligated to be an overachiever.

Currently available operations are:

  • Digests — In the OpenSSL libraries, the corresponding method object is EVP_MD. The number for this operation is OSSL_OP_DIGEST. The functions the provider can offer are described in provider-digest(7). 🍓
  • Symmetric ciphers — In the OpenSSL libraries, the corresponding method object is EVP_CIPHER. The number for this operation is OSSL_OP_CIPHER. The functions the provider can offer are described in provider-cipher(7). 🔐
  • Message Authentication Code (MAC) — In the OpenSSL libraries, the corresponding method object is EVP_MAC. The number for this operation is OSSL_OP_MAC. The functions the provider can offer are described in provider-mac(7). 📬
  • Key Derivation Function (KDF) — In the OpenSSL libraries, the corresponding method object is EVP_KDF. The number for this operation is OSSL_OP_KDF. The functions the provider can offer are described in provider-kdf(7). 🌱
  • Key Exchange — In the OpenSSL libraries, the corresponding method object is EVP_KEYEXCH. The number for this operation is OSSL_OP_KEYEXCH. The functions the provider can offer are described in provider-keyexch(7). 🤝
  • Asymmetric Ciphers — In the OpenSSL libraries, the corresponding method object is EVP_ASYM_CIPHER. The number for this operation is OSSL_OP_ASYM_CIPHER. The functions the provider can offer are described in provider-asym_cipher(7). 🗝️
  • Asymmetric Key Encapsulation — In the OpenSSL libraries, the corresponding method object is EVP_KEM. The number for this operation is OSSL_OP_KEM. The functions the provider can offer are described in provider-kem(7). 📦
  • Encoding — In the OpenSSL libraries, the corresponding method object is OSSL_ENCODER. The number for this operation is OSSL_OP_ENCODER. The functions the provider can offer are described in provider-encoder(7). 🧬
  • Decoding — In the OpenSSL libraries, the corresponding method object is OSSL_DECODER. The number for this operation is OSSL_OP_DECODER. The functions the provider can offer are described in provider-decoder(7). 🧪
  • Random Number Generation — The number for this operation is OSSL_OP_RAND. The functions the provider can offer for random number generation are described in provider-rand(7). 🎲 (no method object listed here, and we're not making one up — accuracy queen)
  • Key Management — The number for this operation is OSSL_OP_KEYMGMT. The functions the provider can offer for key management are described in provider-keymgmt(7). 🔑
  • Signing and Signature Verification — The number for this operation is OSSL_OP_SIGNATURE. The functions the provider can offer for digital signatures are described in provider-signature(7). ✍️
  • Store Management — The number for this operation is OSSL_OP_STORE. The functions the provider can offer for store management are described in provider-storemgmt(7). 🗄️

🌈 Algorithm naming 🌈

Algorithm names are case insensitive. Any particular algorithm can have multiple aliases associated with it. The canonical OpenSSL naming scheme follows this format:

ALGNAME[VERSION?][-SUBNAME[VERSION?]?][-SIZE?][-MODE?]

Let's decode this bracket situation:

  • VERSION — is only present if there are multiple versions of an algorithm (e.g. MD2, MD4, MD5). It may be omitted if there is only one version. If there's only one, why label it, right? exactly.
  • SUBNAME — may be present where multiple algorithms are combined together, e.g. MD5-SHA1. collaboration era 🤝
  • SIZE — is only present if multiple versions of an algorithm exist with different sizes (e.g. AES-128-CBC, AES-256-CBC). size matters, apparently 💀
  • MODE — is only present where applicable. no mode, no label. simple as that.

Other aliases may exist for example where standards bodies or common practice use alternative names or names that OpenSSL has used historically. so if you see a name that looks different, it might just be the historical alias. don't @ me.

🧚 Provider dependencies 🧚

Providers may depend for their proper operation on the availability of (functionality implemented in) other providers. As there is no mechanism to express such dependencies towards the OpenSSL core, provider authors must take care that such dependencies are either completely avoided or made visible to users, e.g., by documentation and/or defensive programming, e.g., outputting error messages if required external dependencies are not available, e.g., when no provider implementing the required functionality has been activated. In particular, provider initialization should not depend on other providers already having been initialized.

Read that again, bestie. No indirect codependency allowed. The core does not know about your provider's situationship with other providers 🚩 communicate it yourself or avoid it entirely.

💀 Note on naming clashes 💀

It is possible to register the same algorithm name from within different providers. Users should note that if no property query is specified, or more than one implementation matches the property query then it is unspecified which implementation of a particular algorithm will be returned. unspecified! which means we literally cannot tell you which one you'll get. dramatic, but that's the truth.

Such naming clashes may also occur if algorithms only differ in capitalization as "Algorithm naming" is case insensitive. so AES and aes are the same name for clash purposes. case insensitive means case insensitive, no cap.

👑 OPENSSL PROVIDERS 👑

OpenSSL provides a number of its own providers. These are the default, base, fips, legacy and null providers. Five icons, five vibes. See crypto(7) for an overview of these providers. the lore continues there.

🫶 SEE ALSO 🫶

EVP_DigestInit_ex(3), EVP_EncryptInit_ex(3), OSSL_LIB_CTX(3), EVP_set_default_properties(3), EVP_MD_fetch(3), EVP_CIPHER_fetch(3), EVP_KEYMGMT_fetch(3), openssl-core.h(7), provider-base(7), provider-digest(7), provider-cipher(7), provider-keyexch(7)

all the friends of this page, go say hi 💖

⭐ HISTORY ⭐

The concept of providers and everything surrounding them was introduced in OpenSSL 3.0. so if you're on 1.1.1, this whole page is not your era yet, sorry bestie.

Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

like and subscribe, but legally binding 📜✨

okay that's the whole page, you're officially a provider understander now 💅

Version 3.5.0 — dated 2026-09-25 — page PROVIDER(7ossl)

mwah, go write a provider, bestie 🌸🦋

📦 where this page comes from