Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
Standard preamble:
========================================================================
..
.... \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
. ds C` "" . ds C' "" 'br\} . 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 ========================================================================
Title "OSSL-GUIDE-LIBCRYPTO-INTRODUCTION 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.
Algorithms are implemented in providers. See \fBossl-guide-libraries-introduction\|(7) for information about providers.
Two types of fetching are supported by OpenSSL - "Explicit fetching" and "Implicit fetching".
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 EVP_MD 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 (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 \fBEVP_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.
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.
The following functions can be used for explicit fetching:
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.
Fetch any available implementation of SHA2-256 in the default context. Note that some algorithms have aliases. So "SHA256" and "SHA2-256" are synonymous:
.Vb 3 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", NULL); ... EVP_MD_free(md); .Ve
Fetch any available implementation of AES-128-CBC 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 SHA2-256 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 SHA2-256 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 SHA2-256 that is preferably from the FIPS provider in the default context:
.Vb 3 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider=?fips"); ... EVP_MD_free(md); .Ve
Fetch an implementation of SHA2-256 from the default provider in the specified library context:
.Vb 3 EVP_MD *md = EVP_MD_fetch(libctx, "SHA2-256", "provider=default"); ... EVP_MD_free(md); .Ve
Load the legacy provider into the default context and then fetch an implementation of WHIRLPOOL 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 "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:
.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
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 freed.
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 ossl-guide-libraries-introduction\|(7)).
.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
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).
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.
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>.