manpagez: man pages & more
man crypto(7)
Home | html | info | man
OSSL-GUIDE-LIBCRYPTO-INTRODUCTION(7ossl)                               OpenSSL


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


       The OpenSSL cryptography library ("libcrypto") enables access to a wide
       range of cryptographic algorithms used in various Internet standards.
       The services provided by this library are used by the OpenSSL
       implementations of TLS and CMS, and they have also been used to
       implement many other third party products and protocols.

       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.

       Cryptographic primitives such as the SHA256 digest, or AES encryption
       are referred to in OpenSSL as "algorithms". 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 is also
       possible that a third party could add additional implementations such
       as in a hardware security module (HSM).

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

       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.


       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.

       Two types of fetching are supported by OpenSSL - "Explicit fetching"
       and "Implicit fetching".

   Explicit fetching
       Explicit fetching involves directly calling 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.

       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

       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),
           ALGORITHMS" in OSSL_PROVIDER-base(7).

       A property query string
           The property query string used to guide selection of the algorithm
           implementation. See "PROPERTY QUERY STRINGS" in

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

   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.

       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.

       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

       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

       The following functions can be used for explicit fetching:

           Fetch a message digest/hashing algorithm implementation.

           Fetch a symmetric cipher algorithm implementation.

           Fetch a Key Derivation Function (KDF) algorithm implementation.

           Fetch a Message Authentication Code (MAC) algorithm implementation.

           Fetch a Key Encapsulation Mechanism (KEM) algorithm implementation

           Fetch an encoder algorithm implementation (e.g. to encode keys to a
           specified format).

           Fetch a decoder algorithm implementation (e.g. to decode keys from
           a specified format).

           Fetch a Pseudo Random Number Generator (PRNG) algorithm

       in OSSL_PROVIDER-base(7) for a list of algorithm names that can be


       The following section provides a series of examples of fetching
       algorithm implementations.

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

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

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

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

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

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

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

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

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

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


       Cryptographic algorithms are made available to applications through use
       of the "EVP" APIs. Each of the various operations such as encryption,
       digesting, message authentication codes, etc., have a set of EVP
       function calls that can be invoked to use them. See the evp(7) page for
       further details.

       Most of these follow a common pattern. A "context" object is first
       created. For example for a digest operation you would use an
       EVP_MD_CTX, and for an encryption/decryption operation you would use an
       EVP_CIPHER_CTX. The operation is then initialised ready for use via an
       "init" function - optionally passing in a set of parameters (using the
       OSSL_PARAM(3) type) to configure how the operation should behave. Next
       data is fed into the operation in a series of "update" calls. The
       operation is finalised using a "final" call which will typically
       provide some kind of output. Finally the context is cleaned up and

       The following shows a complete example for doing this process for
       digesting data using SHA256. The process is similar for other
       operations such as encryption/decryption, signatures, message
       authentication codes, etc. Additional examples can be found in the
       OpenSSL demos (see "DEMO APPLICATIONS" in

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

            /* Clean up all the resources we allocated */
            if (ret != 0)
            return ret;


       Many algorithms require the use of a key. Keys can be generated
       dynamically using the EVP APIs (for example see EVP_PKEY_Q_keygen(3)).
       However it is often necessary to save or load keys (or their associated
       parameters) to or from some external format such as PEM or DER (see
       openssl-glossary(7)). OpenSSL uses encoders and decoders to perform
       this task.

       Encoders and decoders are just algorithm implementations in the same
       way as any other algorithm implementation in OpenSSL. They are
       implemented by providers. The OpenSSL encoders and decoders are
       available in the default provider. They are also duplicated in the base

       For information about encoders see OSSL_ENCODER_CTX_new_for_pkey(3).
       For information about decoders see OSSL_DECODER_CTX_new_for_pkey(3).

       As well as using encoders/decoders directly there are also some helper
       functions that can be used for certain well known and commonly used
       formats. For example see PEM_read_PrivateKey(3) and
       PEM_write_PrivateKey(3) for information about reading and writing key
       data from PEM encoded files.


       See ossl-guide-libssl-introduction(7) for an introduction to using


       openssl(1), ssl(7), evp(7), OSSL_LIB_CTX(3), openssl-threads(7),
       property(7), OSSL_PROVIDER-default(7), OSSL_PROVIDER-base(7),
       openssl-glossary(7), provider(7)


       Copyright 2000-2023 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

3.2.0                             2023-11-23

openssl 3.2.0 - Generated Sat Dec 2 07:49:53 CST 2023
© 2000-2024
Individual documents may contain additional copyright information.