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

📦

version 4.0.3 · 13 versions

💖 OSSL-GUIDE-LIBCRYPTO-INTRODUCTION — aka `ossl-guide-libcrypto-introduction`, `crypto` 💖

okay bestie, welcome to the OpenSSL Guide: An introduction to libcrypto 🎀 this is the 7SSL one, and it's the moment you finally meet the library that's been running the whole internet's group chat behind the scenes. grab a snack, we're going in 🦋

✨ INTRODUCTION ✨

so the OpenSSL cryptography library — everybody calls it "libcrypto" — is basically your all-access pass to a huge range of cryptographic algorithms that get used all over Internet standards 🌈. The services it hands out? The OpenSSL implementations of TLS and CMS use them, and a whole bunch of other third-party products and protocols have used them too. iconic behaviour, honestly 👑

what's actually in the menu:

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 — get called "algorithms" in OpenSSL-speak. and lowkey the interesting bit: each algorithm can have multiple implementations available to you. for example, the RSA algorithm shows up as a "default" implementation that's good for general use, AND a "fips" implementation that's been validated to FIPS 140 standards for when that actually matters. also?? a third party could absolutely add more implementations, like in a hardware security module (HSM) 🧚

algorithms live inside providers. go read ossl-guide-libraries-introduction(7) for the whole provider tea ☕

⚙️ Operations

different algorithms can be grouped together by purpose. like, there are algorithms for encryption, and totally different algorithms for digesting data. these groups are called "operations" in OpenSSL 🫶, and each operation has its own little set of functions attached to it.

for example:

wanna do an encryption operation with AES (or literally any other encryption algorithm)? you use the encryption functions on the EVP_EncryptInit(3) page.
wanna do a digest operation with SHA256? you use the digesting functions on the EVP_DigestInit(3) page.

see how it's organised? obsessed 😌

🔍 ALGORITHM FETCHING 🔍

okay so to actually use an algorithm, an implementation for it has to be "fetched" first. fetching = 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 ✨

OpenSSL supports two flavours of fetching — "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. the 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. and bestie, you are responsible for freeing the object returned from the APINAME_fetch function — use APINAME_free when you don't need it anymore. don't forget, that's a leak 🫠

these fetching functions follow a pretty common pattern where three arguments get passed:

The library context — see OSSL_LIB_CTX(3) for the full 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. and 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 info on what's available in each one: "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).

⚠️ heads up bestie: 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. so don't try it 💀

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

so the algorithm implementation that gets 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). cute, right? 💅

🌙 Implicit fetching

OpenSSL has a bunch of functions that return an algorithm object with no associated implementation, like EVP_sha256(3), EVP_aes_128_cbc(3), EVP_get_cipherbyname(3) or EVP_get_digestbyname(3). these stick around for compatibility with OpenSSL before version 3.0, back when explicit fetching wasn't a thing yet. nostalgia core 😭

when you use them with functions like EVP_DigestInit_ex(3) or EVP_CipherInit_ex(3), the actual implementation to be used gets fetched implicitly using default search criteria (which uses NULL for the library context and property query string).

and in some cases, implicit fetching can also occur when a NULL algorithm parameter is supplied. in that 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's being used and the function that's 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 that explicitly fetched algorithm each subsequent time 🔥. this will typically be faster than implicitly fetching the algorithm every single time you use it. there's an example of Explicit fetching down in "USING ALGORITHMS IN APPLICATIONS" 👀

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. and if you're 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. glow up ✨

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. no cap 🫡

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.

and go check "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 the full list of algorithm names that can be fetched 🧾

🍓 FETCHING EXAMPLES 🍓

this whole section is a series of examples of fetching algorithm implementations. show don't tell, main character energy 👑

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);

and that's where part 1 wraps, bestie — more coming 🌸

💖 USING ALGORITHMS IN APPLICATIONS 💖

so bestie, the ✨tea✨ is that all the crypto algorithms show up in your app through the "EVP" APIs. every single operation — encryption, digesting, message authentication codes, etc. — has its own lil set of EVP function calls you can summon to do the thing. if you want the deep dive, go read evp(7), that's the lore page 🌸

most of them follow the same lil pattern, and honestly once you clock it you've clocked all of them:

first you make a "context" object. digesting? that's an EVP_MD_CTX. encrypting/decrypting? that's an EVP_CIPHER_CTX 💅
then you initialise it for use with an "init" function — and you can optionally pass in a set of parameters (that's the OSSL_PARAM(3) type, iykyk) to configure how the operation behaves ✨
then you feed data in with a bunch of "update" calls 🍓
then you finalise with a "final" call, which usually hands you some output 🎀
and finally you clean up and free the context, like the responsible main character you are 👑

and here's a whole complete example of that process for digesting data with SHA256. the process is basically the same for other operations like encryption/decryption, signatures, message authentication codes, etc. there's even more examples chilling in the OpenSSL demos (peep "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 🔑

okay so a ton of algorithms need a key to even function. you can generate keys dynamically with the EVP APIs (for example, look at EVP_PKEY_Q_keygen(3)), but like… realistically you're gonna need to save or load keys (or their associated parameters) to/from some external format like PEM or DER (see openssl-glossary(7) for the format tea ☕). and that's literally what OpenSSL's encoders and decoders are for 💅

here's the cute part: encoders and decoders are just algorithm implementations, same as literally every other algorithm implementation in OpenSSL. providers implement them. the OpenSSL encoders and decoders live in the default provider, and they're also duplicated in the base provider 🌈

wanna know about encoders? → OSSL_ENCODER_CTX_new_for_pkey(3) ✨
wanna know about decoders? → OSSL_DECODER_CTX_new_for_pkey(3) ✨

and also, besides using encoders/decoders directly, there are some helper functions for certain well known and commonly used formats. for example peep PEM_read_PrivateKey(3) and PEM_write_PrivateKey(3) for reading and writing key data from PEM encoded files 🎀

📚 FURTHER READING 📚

want an intro to using "libssl"? go read ossl-guide-libssl-introduction(7) bestie, it's right there 💜

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

and that's a wrap, bestie 🫶 this was version 4.0.3, dated 2026-09-29, and it ate, no crumbs left 💅✨ go forth and digest, or encode, or whatever your heart desires 👑🌸

📦 where this page comes from

ubuntu stonking: openssl 4.0.3-1ubuntu1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

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

💖 OSSL-GUIDE-LIBCRYPTO-INTRODUCTION — aka `ossl-guide-libcrypto-introduction`, `crypto` 💖

✨ INTRODUCTION ✨

🧮 Algorithms

⚙️ Operations

🔍 ALGORITHM FETCHING 🔍

🎯 Explicit fetching

🌙 Implicit fetching

🏎️ Performance

🍓 FETCHING EXAMPLES 🍓

💖 USING ALGORITHMS IN APPLICATIONS 💖

🔑 ENCODING AND DECODING KEYS 🔑

📚 FURTHER READING 📚

👀 SEE ALSO 👀

©️ COPYRIGHT ©️

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

💖 OSSL-GUIDE-LIBCRYPTO-INTRODUCTION — aka ossl-guide-libcrypto-introduction, crypto 💖

✨ INTRODUCTION ✨

🧮 Algorithms

⚙️ Operations

🔍 ALGORITHM FETCHING 🔍

🎯 Explicit fetching

🌙 Implicit fetching

🏎️ Performance

🍓 FETCHING EXAMPLES 🍓

💖 USING ALGORITHMS IN APPLICATIONS 💖

🔑 ENCODING AND DECODING KEYS 🔑

📚 FURTHER READING 📚

👀 SEE ALSO 👀

©️ COPYRIGHT ©️

💖 OSSL-GUIDE-LIBCRYPTO-INTRODUCTION — aka `ossl-guide-libcrypto-introduction`, `crypto` 💖