Standard preamble:
========================================================================
..
.... Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.
If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.
Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================
Title "CRYPTO 7ossl"
way too many mistakes in technical documents.
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.
If an application does not explicitly create a library context then the \*(L"default\*(R" library context will be used.
Library contexts are represented by the \s-1OSSL_LIB_CTX\s0 type. Many OpenSSL \s-1API\s0 functions take a library context as a parameter. Applications can always pass \fB\s-1NULL\s0 for this parameter to just use the default library context.
The default library context is automatically created the first time it is needed. This will automatically load any available configuration file and will initialise OpenSSL for use. Unlike in earlier versions of OpenSSL (prior to 1.1.0) no explicit initialisation steps need to be taken.
Similarly when the application exits the default library context is automatically destroyed. No explicit de-initialisation steps need to be taken.
See \s-1OSSL_LIB_CTX\s0\|(3) for more information about library contexts. See also \*(L"\s-1ALGORITHM FETCHING\*(R"\s0.
There are exceptions to these rules. A small number of functions are not thread safe at all. Where this is the case this restriction should be noted in the documentation for the function. Similarly some data structures may be partially or fully thread safe. For example it is safe to use an \s-1OSSL_LIB_CTX\s0 in multiple threads.
See openssl-threads\|(7) for a more detailed discussion on OpenSSL threading support.
Two types of fetching are supported by OpenSSL - explicit fetching and implicit fetching.
Property query strings can be specified explicitly as an argument to a function. It is also possible to specify a default property query string for the whole library context using the EVP_set_default_properties\|(3) or \fBEVP_default_properties_enable_fips\|(3) functions. Where both default properties and function specific properties are specified then they are combined. Function specific properties will override default properties where there is a conflict.
See property\|(7) for more information about properties.
These fetching functions follow a fairly common pattern, where three arguments are passed:
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 \s-1EVP_MD\s0 object which may have been returned from an earlier call to EVP_MD_fetch\|(3).
When they are used with functions like EVP_DigestInit_ex\|(3) or \fBEVP_CipherInit_ex\|(3), the actual implementation to be used is fetched implicitly using default search criteria.
In some cases implicit fetching can also occur when a \s-1NULL\s0 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 revolve around \s-1EVP_PKEY_CTX\s0 and \s-1EVP_PKEY\s0\|(3), such as \fBEVP_DigestSignInit\|(3) and friends, all fetch the implementations implicitly. Because these functions involve both an operation type (such as \s-1EVP_SIGNATURE\s0\|(3)) and an \s-1EVP_KEYMGMT\s0\|(3) for the \s-1EVP_PKEY\s0\|(3), they try the following:
Prior to OpenSSL 3.0, constant method tables (such as EVP_sha256()) were used directly to access methods. If you pass one of these convenience functions to an operation the fixed methods are ignored, and only the name is used to internally fetch methods from a provider.
If the prefetched object is not passed to operations, then any implicit fetch will use the internally cached prefetched object, but it will still be slower than passing the prefetched object directly.
Fetching via a provider offers more flexibility, but it is slower than the old method, since it must search for the algorithm in all loaded providers, and then populate the method table using provider supplied methods. Internally OpenSSL caches similar algorithms on the first fetch (so loading a digest caches all digests).
The following methods can be used for prefetching:
0
The following methods are used internally when performing operations:
0
See OSSL_PROVIDER-default\|(7), <OSSL_PROVIDER-fips\|(7)> and <OSSL_PROVIDER-legacy\|(7)>for a list of algorithm names that can be fetched.
Fetch any available implementation of \s-1SHA2-256\s0 in the default context. Note that some algorithms have aliases. So \*(L"\s-1SHA256\*(R"\s0 and \*(L"\s-1SHA2-256\*(R"\s0 are synonymous:
.Vb 3 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", NULL); ... EVP_MD_free(md); .Ve
Fetch any available implementation of \s-1AES-128-CBC\s0 in the default context:
.Vb 3 EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL); ... EVP_CIPHER_free(cipher); .Ve
Fetch an implementation of \s-1SHA2-256\s0 from the default provider in the default context:
.Vb 3 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider=default"); ... EVP_MD_free(md); .Ve
Fetch an implementation of \s-1SHA2-256\s0 that is not from the default provider in the default context:
.Vb 3 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider!=default"); ... EVP_MD_free(md); .Ve
Fetch an implementation of \s-1SHA2-256\s0 from the default provider in the specified context:
.Vb 3 EVP_MD *md = EVP_MD_fetch(ctx, "SHA2-256", "provider=default"); ... EVP_MD_free(md); .Ve
Load the legacy provider into the default context and then fetch an implementation of \s-1WHIRLPOOL\s0 from it:
.Vb 2 /* 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); .Ve
Note that in the above example the property string \*(L"provider=legacy\*(R" is optional since, assuming no other providers have been loaded, the only implementation of the \*(L"whirlpool\*(R" algorithm is in the \*(L"legacy\*(R" provider. Also note that the default provider should be explicitly loaded if it is required in addition to other providers:
.Vb 3 /* 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); .Ve
The algorithms available in each of these providers may vary due to build time configuration options. The openssl-list\|(1) command can be used to list the currently available algorithms.
The names of the algorithms shown from openssl-list\|(1) can be used as an algorithm identifier to the appropriate fetching function. Also see the provider specific manual pages linked below for further details about using the algorithms available in each of the providers.
As well as the OpenSSL providers third parties can also implement providers. For information on writing a provider see provider\|(7).
If you don't load any providers at all then the \*(L"default\*(R" provider will be automatically loaded. If you explicitly load any provider then the \*(L"default\*(R" provider would also need to be explicitly loaded if it is required.
See OSSL_PROVIDER-default\|(7).
See OSSL_PROVIDER-base\|(7).
See \s-1OSSL_PROVIDER-FIPS\s0\|(7) and fips_module\|(7).
See OSSL_PROVIDER-legacy\|(7).
See OSSL_PROVIDER-null\|(7).
Most of these follow a common pattern. A \*(L"context\*(R" object is first created. For example for a digest operation you would use an \s-1EVP_MD_CTX\s0, and for an encryption/decryption operation you would use an \s-1EVP_CIPHER_CTX\s0. The operation is then initialised ready for use via an \*(L"init\*(R" function - optionally passing in a set of parameters (using the \s-1OSSL_PARAM\s0\|(3) type) to configure how the operation should behave. Next data is fed into the operation in a series of \*(L"update\*(R" calls. The operation is finalised using a \*(L"final\*(R" call which will typically provide some kind of output. Finally the context is cleaned up and freed.
The following shows a complete example for doing this process for digesting data using \s-1SHA256.\s0 The process is similar for other operations such as encryption/decryption, signatures, message authentication codes, etc.
.Vb 4 #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\*(Aqre * using the "default" library context here (first NULL parameter), and * we\*(Aqre 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; } .Ve
The configuration file can be used to automatically load providers and set up default property query strings.
For information on the OpenSSL configuration file format see config\|(5).
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 provider.
For information about encoders see OSSL_ENCODER_CTX_new_for_pkey\|(3). For information about decoders see OSSL_DECODER_CTX_new_for_pkey\|(3).
For example the functions:
.Vb 2 int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev); int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj); .Ve
In the 0 version the ownership of the object is passed to (for an add or set) or retained by (for a get) the parent object. For example after calling the \fBX509_CRL_add0_revoked() function above, ownership of the rev object is passed to the crl object. Therefore, after calling this function rev should not be freed directly. It will be freed implicitly when crl is freed.
In the 1 version the ownership of the object is not passed to or retained by the parent object. Instead a copy or \*(L"up ref\*(R" of the object is performed. So after calling the X509_add1_trust_object() function above the application will still be responsible for freeing the obj value where appropriate.
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>.