OSSL-GUIDE-L...-INTRODUCTION(7ossl)

📦

version 3.5.9 · 8 versions

3.5.9 · alpine 3.23, alpine 3.24 (latest)
3.5.9 · centos-stream 9
3.5.9 · centos-stream 10
3.5.9 · alpine 3.22
3.5.8 · fedora 43
3.5.1 · fedora 43
3.5.9 · fedora 43, fedora 44
3.5.5 · fedora 44

okay bestie, welcome to OSSL-GUIDE-L...-INTRODUCTION(7ossl) — the manual page for ossl-guide-libcrypto-introduction, crypto. It’s the OpenSSL Guide’s intro to libcrypto, and we’re gonna get you comfy with it. 💖

💖 NAME 💖

ossl-guide-libcrypto-introduction, crypto — OpenSSL Guide: An introduction to libcrypto.

🌸 INTRODUCTION 🌸

The OpenSSL cryptography library, aka “libcrypto”, gives you access to a whole range of cryptographic algorithms used in various Internet standards. The services this library provides are used by the OpenSSL implementations of TLS and CMS, and bestie, they’ve also been used to implement many other third party products and protocols. slay ✨

The functionality includes symmetric encryption, public key cryptography, key agreement, certificate handling, cryptographic hash functions, cryptographic pseudo-random number generators, message authentication codes (MACs), key derivation functions (KDFs), and various utilities.

🧮 Algorithms 🧮

Cryptographic primitives like the SHA256 digest, or AES encryption, are called “algorithms” in OpenSSL. Each algorithm may have multiple implementations available for use. For example, the RSA algorithm is available as a “default” implementation suitable for general use, and a “fips” implementation which has been validated to FIPS 140 standards for situations where that is important. It’s also possible that a third party could add additional implementations, like in a hardware security module (HSM). 💅

Algorithms are implemented in providers. See ossl-guide-libraries-introduction(7) for information about providers. 🦋

⚙️ Operations ⚙️

Different algorithms can be grouped together by their purpose. For example, there are algorithms for encryption, and different algorithms for digesting data. These different groups are known as “operations” in OpenSSL. Each operation has a different set of functions associated with it. For example, to perform an encryption operation using AES (or any other encryption algorithm) you would use the encryption functions detailed on the EVP_EncryptInit(3) page. Or to perform a digest operation using SHA256, then you would use the digesting functions on the EVP_DigestInit(3) page. 🎀

✨ ALGORITHM FETCHING ✨

In order to use an algorithm, an implementation for it must first be “fetched”. Fetching is the process of looking through the available implementations, applying selection criteria (via a property query string), and finally choosing the implementation that will be used. It’s giving algorithm audition energy. 👑

Two types of fetching are supported by OpenSSL — “Explicit fetching” and “Implicit fetching”.

🎯 Explicit fetching 🎯

Explicit fetching is when you directly call a specific API to fetch an algorithm implementation from a provider. This fetched object can then be passed to other APIs. These explicit fetching functions usually have the name APINAME_fetch, where APINAME is the name of the operation. For example, EVP_MD_fetch(3) can be used to explicitly fetch a digest algorithm implementation. The user is responsible for freeing the object returned from the APINAME_fetch function using APINAME_free when it is no longer needed. don’t forget the cleanup bestie 🧹

These fetching functions follow a fairly common pattern, where three arguments are passed:

The library context — See OSSL_LIB_CTX(3) for a more detailed description. This may be NULL to signify the default (global) library context, or a context created by the user. Only providers loaded in this library context (see OSSL_PROVIDER_load(3)) will be considered by the fetching function. In case no provider has been loaded in this library context then the default provider will be loaded as a fallback (see OSSL_PROVIDER-default(7)).
An identifier — For all currently implemented fetching functions this is the algorithm name. Each provider supports a list of algorithm implementations. See the provider specific documentation for information on the algorithm implementations available in each provider: "OPERATIONS AND ALGORITHMS" in OSSL_PROVIDER-default(7), "OPERATIONS AND ALGORITHMS" in OSSL_PROVIDER-FIPS(7), "OPERATIONS AND ALGORITHMS" in OSSL_PROVIDER-legacy(7) and "OPERATIONS AND ALGORITHMS" in OSSL_PROVIDER-base(7). Note, while providers may register algorithms against a list of names using a string with a colon separated list of names, fetching algorithms using that format is currently unsupported.
A property query string — The property query string used to guide selection of the algorithm implementation. See "PROPERTY QUERY STRINGS" in ossl-guide-libraries-introduction(7).

The algorithm implementation that is fetched can then be used with other diverse functions that use them. For example, the EVP_DigestInit_ex(3) function takes as a parameter an EVP_MD object which may have been returned from an earlier call to EVP_MD_fetch(3). reuse the fetched object, it’s iconic ✨

🫶 Implicit fetching 🫶

OpenSSL has a number of functions that return an algorithm object with no associated implementation, such as EVP_sha256(3), EVP_aes_128_cbc(3), EVP_get_cipherbyname(3) or EVP_get_digestbyname(3). These are present for compatibility with OpenSSL before version 3.0 where explicit fetching was not available. vintage compatibility moment 🫶

When they are used with functions like EVP_DigestInit_ex(3) or EVP_CipherInit_ex(3), the actual implementation to be used is fetched implicitly using default search criteria (which uses NULL for the library context and property query string).

In some cases implicit fetching can also occur when a NULL algorithm parameter is supplied. In this case an algorithm implementation is implicitly fetched using default search criteria and an algorithm name that is consistent with the context in which it is being used. 🌀

Functions that use an EVP_PKEY_CTX or an EVP_PKEY(3), such as EVP_DigestSignInit(3), all fetch the implementations implicitly. Usually the algorithm to fetch is determined based on the type of key that is being used and the function that has been called. 🔑

⚡ Performance ⚡

If you perform the same operation many times with the same algorithm, then it is recommended to use a single explicit fetch of the algorithm and then reuse the explicitly fetched algorithm each subsequent time. This will typically be faster than implicitly fetching the algorithm every time you use it. See an example of Explicit fetching in "USING ALGORITHMS IN APPLICATIONS". speed queen behavior ⚡

Prior to OpenSSL 3.0, functions such as EVP_sha256() which return a const object were used directly to indicate the algorithm to use in various function calls. If you pass the return value of one of these convenience functions to an operation then you are using implicit fetching. If you are converting an application that worked with an OpenSSL version prior to OpenSSL 3.0 then consider changing instances of implicit fetching to explicit fetching instead. 🚀

If an explicitly fetched object is not passed to an operation, then any implicit fetch will use an internally cached prefetched object, but it will still be slower than passing the explicitly fetched object directly. ngl, pass the fetched object directly when you can 💅

The following functions can be used for explicit fetching:

EVP_MD_fetch(3) — Fetch a message digest/hashing algorithm implementation.
EVP_CIPHER_fetch(3) — Fetch a symmetric cipher algorithm implementation.
EVP_KDF_fetch(3) — Fetch a Key Derivation Function (KDF) algorithm implementation.
EVP_MAC_fetch(3) — Fetch a Message Authentication Code (MAC) algorithm implementation.
EVP_KEM_fetch(3) — Fetch a Key Encapsulation Mechanism (KEM) algorithm implementation
OSSL_ENCODER_fetch(3) — Fetch an encoder algorithm implementation (e.g. to encode keys to a specified format).
OSSL_DECODER_fetch(3) — Fetch a decoder algorithm implementation (e.g. to decode keys from a specified format).
EVP_RAND_fetch(3) — Fetch a Pseudo Random Number Generator (PRNG) algorithm implementation.

See "OPERATIONS AND ALGORITHMS" in OSSL_PROVIDER-default(7), "OPERATIONS AND ALGORITHMS" in OSSL_PROVIDER-FIPS(7), "OPERATIONS AND ALGORITHMS" in OSSL_PROVIDER-legacy(7) and "OPERATIONS AND ALGORITHMS" in OSSL_PROVIDER-base(7) for a list of algorithm names that can be fetched. 🦋

🔥 FETCHING EXAMPLES 🔥

The following section provides a series of examples of fetching algorithm implementations. little code snack break, bestie 🍓

Fetch any available implementation of SHA2-256 in the default context. Note that some algorithms have aliases. So "SHA256" and "SHA2-256" are synonymous:

EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", NULL);
...
EVP_MD_free(md);

Fetch any available implementation of AES-128-CBC in the default context:

EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL);
...
EVP_CIPHER_free(cipher);

Fetch an implementation of SHA2-256 from the default provider in the default context:

EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");
...
EVP_MD_free(md);

Fetch an implementation of SHA2-256 that is not from the default provider in the default context:

EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider!=default");
...
EVP_MD_free(md);

Fetch an implementation of SHA2-256 that is preferably from the FIPS provider in the default context:

EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider=?fips");
...
EVP_MD_free(md);

Fetch an implementation of SHA2-256 from the default provider in the specified library context:

EVP_MD *md = EVP_MD_fetch(libctx, "SHA2-256", "provider=default");
...
EVP_MD_free(md);

Load the legacy provider into the default context and then fetch an implementation of WHIRLPOOL from it:

/* This only needs to be done once - usually at application start up */
OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");

EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy");
...
EVP_MD_free(md);

Note that in the above example the property string "provider=legacy" is optional since, assuming no other providers have been loaded, the only implementation of the "whirlpool" algorithm is in the "legacy" provider. Also note that the default provider should be explicitly loaded if it is required in addition to other providers:

/* This only needs to be done once - usually at application start up */
OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");

EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
...
EVP_MD_free(md_whirlpool);
EVP_MD_free(md_sha256);

🧚 USING ALGORITHMS IN APPLICATIONS

Okay bestie, so here's the tea: crypto algorithms get handed to your app through the "EVP" APIs. Every single operation — encryption, digesting, message authentication codes, all of it — has its own little fam of EVP function calls you can invoke to actually use them. Head over to evp(7) for the full lore. 💅

Most of them follow the same iconic pattern, no cap:

A "context" object gets created first. Digesting? That's an EVP_MD_CTX. Encrypting/decrypting? That's an EVP_CIPHER_CTX.
Then the operation gets initialised and made ready to go via an "init" function — optionally passing in a set of parameters (type OSSL_PARAM(3)) to configure how it should behave.
Next, data gets fed in through a series of "update" calls.
The operation gets finalised with a "final" call, which will typically give you some kind of output.
Finally the context gets cleaned up and freed. (Yes, we free. Always free. 🫶)

The following is a whole complete example of that process for digesting data with SHA256. The vibe is basically identical for other operations like encryption/decryption, signatures, message authentication codes, etc. More examples live in the OpenSSL demos — see "DEMO APPLICATIONS" in ossl-guide-libraries-introduction(7). ✨

#include <stdio.h>
#include <openssl/evp.h>
#include <openssl/bio.h>
#include <openssl/err.h>

int main(void)
{
    EVP_MD_CTX *ctx = NULL;
    EVP_MD *sha256 = NULL;
    const unsigned char msg[] = {
        0x00, 0x01, 0x02, 0x03
    };
    unsigned int len = 0;
    unsigned char *outdigest = NULL;
    int ret = 1;

    /* Create a context for the digest operation */
    ctx = EVP_MD_CTX_new();
    if (ctx == NULL)
        goto err;

    /*
     * Fetch the SHA256 algorithm implementation for doing the digest. We're
     * using the "default" library context here (first NULL parameter), and
     * we're not supplying any particular search criteria for our SHA256
     * implementation (second NULL parameter). Any SHA256 implementation will
     * do.
     * In a larger application this fetch would just be done once, and could
     * be used for multiple calls to other operations such as EVP_DigestInit_ex().
     */
    sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
    if (sha256 == NULL)
        goto err;

   /* Initialise the digest operation */
   if (!EVP_DigestInit_ex(ctx, sha256, NULL))
       goto err;

    /*
     * Pass the message to be digested. This can be passed in over multiple
     * EVP_DigestUpdate calls if necessary
     */
    if (!EVP_DigestUpdate(ctx, msg, sizeof(msg)))
        goto err;

    /* Allocate the output buffer */
    outdigest = OPENSSL_malloc(EVP_MD_get_size(sha256));
    if (outdigest == NULL)
        goto err;

    /* Now calculate the digest itself */
    if (!EVP_DigestFinal_ex(ctx, outdigest, &len))
        goto err;

    /* Print out the digest result */
    BIO_dump_fp(stdout, outdigest, len);

    ret = 0;

 err:
    /* Clean up all the resources we allocated */
    OPENSSL_free(outdigest);
    EVP_MD_free(sha256);
    EVP_MD_CTX_free(ctx);
    if (ret != 0)
       ERR_print_errors_fp(stderr);
    return ret;
}

🔑 ENCODING AND DECODING KEYS

So many algorithms need a key, right? And you can generate keys dynamically using the EVP APIs — peep EVP_PKEY_Q_keygen(3) for that one. 🌸

But lowkey, a lot of the time you gotta save keys (or their associated parameters) to some external format, or load them back out of one — think PEM or DER (see openssl-glossary(7) if those words are giving mystery). That's the whole job of OpenSSL's encoders and decoders. 🎀

And here's the thing: encoders and decoders are just algorithm implementations, exactly like any other algorithm implementation in OpenSSL. They're implemented by providers. The OpenSSL encoders and decoders live in the default provider — and they're also duplicated in the base provider. (Double the slay, iykyk.)

Wanna know about encoders? That's OSSL_ENCODER_CTX_new_for_pkey(3).
Wanna know about decoders? That's OSSL_DECODER_CTX_new_for_pkey(3).

And besides using encoders/decoders directly, there are also some helper functions for certain well known and commonly used formats. For example, PEM_read_PrivateKey(3) and PEM_write_PrivateKey(3) will tell you all about reading and writing key data from PEM encoded files. 🦋

📚 FURTHER READING

If you wanna get into "libssl", go read ossl-guide-libssl-introduction(7) — it's the intro, and it ate. 💖

©️ COPYRIGHT

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>.

Okay that's the whole page bestie, you made it to the end, I'm so proud of you 😭🫶 This one's from 3.5.9, dated 2026-09-2 — go forth and digest things responsibly 💅✨

📦 where this page comes from

alpine 3.23: openssl-doc 3.5.9-r0 · Apache-2.0
alpine 3.24: openssl-doc 3.5.9-r0 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms