.\"	$NetBSD: crypto.7,v 1.5 2023/05/31 19:42:44 christos Exp $
.\"
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" 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 C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    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\}
.el\{\
.    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.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" 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'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    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
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    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
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CRYPTO 7"
.TH CRYPTO 7 "2023-05-31" "3.0.9" "OpenSSL"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
crypto \- OpenSSL cryptographic library
.SH "LIBRARY"
libcrypto, -lcrypto
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
See the individual manual pages for details.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The OpenSSL crypto library (\f(CW\*(C`libcrypto\*(C'\fR) implements a wide range of
cryptographic algorithms used in various Internet standards. The services
provided by this library are used by the OpenSSL implementations of \s-1TLS\s0 and
\&\s-1CMS,\s0 and they have also been used to implement many other third party products
and protocols.
.PP
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.
.SS "Algorithms"
.IX Subsection "Algorithms"
Cryptographic primitives such as the \s-1SHA256\s0 digest, or \s-1AES\s0 encryption are
referred to in OpenSSL as \*(L"algorithms\*(R". Each algorithm may have multiple
implementations available for use. For example the \s-1RSA\s0 algorithm is available as
a \*(L"default\*(R" implementation suitable for general use, and a \*(L"fips\*(R" implementation
which has been validated to \s-1FIPS\s0 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 (\s-1HSM\s0).
.SS "Operations"
.IX Subsection "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 \*(L"operations\*(R" in OpenSSL. Each operation
has a different set of functions associated with it. For example to perform an
encryption operation using \s-1AES\s0 (or any other encryption algorithm) you would use
the encryption functions detailed on the \fBEVP_EncryptInit\fR\|(3) page. Or to
perform a digest operation using \s-1SHA256\s0 then you would use the digesting
functions on the \fBEVP_DigestInit\fR\|(3) page.
.SS "Providers"
.IX Subsection "Providers"
A provider in OpenSSL is a component that collects together algorithm
implementations. In order to use an algorithm you must have at least one
provider loaded that contains an implementation of it. OpenSSL comes with a
number of providers and they may also be obtained from third parties. If you
don't load a provider explicitly (either in program code or via config) then the
OpenSSL built-in \*(L"default\*(R" provider will be automatically loaded.
.SS "Library contexts"
.IX Subsection "Library contexts"
A library context can be thought of as a \*(L"scope\*(R" within which configuration
options take effect. When a provider is loaded, it is only loaded within the
scope of a given library context. In this way it is possible for different
components of a complex application to each use a different library context and
have different providers loaded with different configuration settings.
.PP
If an application does not explicitly create a library context then the
\&\*(L"default\*(R" library context will be used.
.PP
Library contexts are represented by the \fB\s-1OSSL_LIB_CTX\s0\fR type. Many OpenSSL \s-1API\s0
functions take a library context as a parameter. Applications can always pass
\&\fB\s-1NULL\s0\fR for this parameter to just use the default library context.
.PP
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.
.PP
Similarly when the application exits the default library context is
automatically destroyed. No explicit de-initialisation steps need to be taken.
.PP
See \s-1\fBOSSL_LIB_CTX\s0\fR\|(3) for more information about library contexts.
See also \*(L"\s-1ALGORITHM FETCHING\*(R"\s0.
.SS "Multi-threaded applications"
.IX Subsection "Multi-threaded applications"
As long as OpenSSL has been built with support for threads (the default case
on most platforms) then most OpenSSL \fIfunctions\fR are thread-safe in the sense
that it is safe to call the same function from multiple threads at the same
time. However most OpenSSL \fIdata structures\fR are not thread-safe. For example
the \fBBIO_write\fR\|(3) and \fBBIO_read\fR\|(3) functions are thread safe. However it
would not be thread safe to call \fBBIO_write()\fR from one thread while calling
\&\fBBIO_read()\fR in another where both functions are passed the same \fB\s-1BIO\s0\fR object
since both of them may attempt to make changes to the same \fB\s-1BIO\s0\fR object.
.PP
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 \fB\s-1OSSL_LIB_CTX\s0\fR in
multiple threads.
.PP
See \fBopenssl\-threads\fR\|(7) for a more detailed discussion on OpenSSL threading
support.
.SH "ALGORITHM FETCHING"
.IX Header "ALGORITHM FETCHING"
In order to use an algorithm an implementation for it must first be \*(L"fetched\*(R".
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.
.PP
Two types of fetching are supported by OpenSSL \- explicit fetching and implicit
fetching.
.SS "Property query strings"
.IX Subsection "Property query strings"
When fetching an algorithm it is possible to specify a property query string to
guide the selection process. For example a property query string of
\&\*(L"provider=default\*(R" could be used to force the selection to only consider
algorithm implementations in the default provider.
.PP
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 \fBEVP_set_default_properties\fR\|(3) or
\&\fBEVP_default_properties_enable_fips\fR\|(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.
.PP
See \fBproperty\fR\|(7) for more information about properties.
.SS "Explicit fetching"
.IX Subsection "Explicit fetching"
Users of the OpenSSL libraries never query a provider directly for an algorithm
implementation. Instead, the diverse OpenSSL APIs often have explicit fetching
functions that do the work, and they return an appropriate algorithm object back
to the user. These functions usually have the name \f(CW\*(C`APINAME_fetch\*(C'\fR, where
\&\f(CW\*(C`APINAME\*(C'\fR is the name of the operation. For example \fBEVP_MD_fetch\fR\|(3) can
be used to explicitly fetch a digest algorithm implementation. The user is
responsible for freeing the object returned from the \f(CW\*(C`APINAME_fetch\*(C'\fR function
using \f(CW\*(C`APINAME_free\*(C'\fR when it is no longer needed.
.PP
These fetching functions follow a fairly common pattern, where three
arguments are passed:
.IP "The library context" 4
.IX Item "The library context"
See \s-1\fBOSSL_LIB_CTX\s0\fR\|(3) for a more detailed description.
This may be \s-1NULL\s0 to signify the default (global) library context, or a
context created by the user. Only providers loaded in this library context (see
\&\fBOSSL_PROVIDER_load\fR\|(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 \fBOSSL_PROVIDER\-default\fR\|(7)).
.IP "An identifier" 4
.IX Item "An identifier"
For all currently implemented fetching functions this is the algorithm name.
.IP "A property query string" 4
.IX Item "A property query string"
The property query string used to guide selection of the algorithm
implementation.
.PP
The algorithm implementation that is fetched can then be used with other diverse
functions that use them. For example the \fBEVP_DigestInit_ex\fR\|(3) function takes
as a parameter an \fB\s-1EVP_MD\s0\fR object which may have been returned from an earlier
call to \fBEVP_MD_fetch\fR\|(3).
.SS "Implicit fetching"
.IX Subsection "Implicit fetching"
OpenSSL has a number of functions that return an algorithm object with no
associated implementation, such as \fBEVP_sha256\fR\|(3), \fBEVP_aes_128_cbc\fR\|(3),
\&\fBEVP_get_cipherbyname\fR\|(3) or \fBEVP_get_digestbyname\fR\|(3). These are present for
compatibility with OpenSSL before version 3.0 where explicit fetching was not
available.
.PP
When they are used with functions like \fBEVP_DigestInit_ex\fR\|(3) or
\&\fBEVP_CipherInit_ex\fR\|(3), the actual implementation to be used is
fetched implicitly using default search criteria.
.PP
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.
.PP
Functions that revolve around \fB\s-1EVP_PKEY_CTX\s0\fR and \s-1\fBEVP_PKEY\s0\fR\|(3), such as
\&\fBEVP_DigestSignInit\fR\|(3) and friends, all fetch the implementations
implicitly.  Because these functions involve both an operation type (such as
\&\s-1\fBEVP_SIGNATURE\s0\fR\|(3)) and an \s-1\fBEVP_KEYMGMT\s0\fR\|(3) for the \s-1\fBEVP_PKEY\s0\fR\|(3), they try
the following:
.IP "1." 4
Fetch the operation type implementation from any provider given a library
context and property string stored in the \fB\s-1EVP_PKEY_CTX\s0\fR.
.Sp
If the provider of the operation type implementation is different from the
provider of the \s-1\fBEVP_PKEY\s0\fR\|(3)'s \s-1\fBEVP_KEYMGMT\s0\fR\|(3) implementation, try to
fetch a \s-1\fBEVP_KEYMGMT\s0\fR\|(3) implementation in the same provider as the operation
type implementation and export the \s-1\fBEVP_PKEY\s0\fR\|(3) to it (effectively making a
temporary copy of the original key).
.Sp
If anything in this step fails, the next step is used as a fallback.
.IP "2." 4
As a fallback, try to fetch the operation type implementation from the same
provider as the original \s-1\fBEVP_PKEY\s0\fR\|(3)'s \s-1\fBEVP_KEYMGMT\s0\fR\|(3), still using the
propery string from the \fB\s-1EVP_PKEY_CTX\s0\fR.
.SS "Performance"
.IX Subsection "Performance"
If you perform the same operation many times then it is recommended to use
\&\*(L"Explicit fetching\*(R" to prefetch an algorithm once initially,
and then pass this created object to any operations that are currently
using \*(L"Implicit fetching\*(R".
See an example of Explicit fetching in \*(L"\s-1USING ALGORITHMS IN APPLICATIONS\*(R"\s0.
.PP
Prior to OpenSSL 3.0, constant method tables (such as \fBEVP_sha256()\fR) 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.
.PP
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.
.PP
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).
.PP
The following methods can be used for prefetching:
.IP "\fBEVP_MD_fetch\fR\|(3)" 4
.IX Item "EVP_MD_fetch"
.PD 0
.IP "\fBEVP_CIPHER_fetch\fR\|(3)" 4
.IX Item "EVP_CIPHER_fetch"
.IP "\fBEVP_KDF_fetch\fR\|(3)" 4
.IX Item "EVP_KDF_fetch"
.IP "\fBEVP_MAC_fetch\fR\|(3)" 4
.IX Item "EVP_MAC_fetch"
.IP "\fBEVP_KEM_fetch\fR\|(3)" 4
.IX Item "EVP_KEM_fetch"
.IP "\fBOSSL_ENCODER_fetch\fR\|(3)" 4
.IX Item "OSSL_ENCODER_fetch"
.IP "\fBOSSL_DECODER_fetch\fR\|(3)" 4
.IX Item "OSSL_DECODER_fetch"
.IP "\fBEVP_RAND_fetch\fR\|(3)" 4
.IX Item "EVP_RAND_fetch"
.PD
.PP
The following methods are used internally when performing operations:
.IP "\fBEVP_KEYMGMT_fetch\fR\|(3)" 4
.IX Item "EVP_KEYMGMT_fetch"
.PD 0
.IP "\fBEVP_KEYEXCH_fetch\fR\|(3)" 4
.IX Item "EVP_KEYEXCH_fetch"
.IP "\fBEVP_SIGNATURE_fetch\fR\|(3)" 4
.IX Item "EVP_SIGNATURE_fetch"
.IP "\fBOSSL_STORE_LOADER_fetch\fR\|(3)" 4
.IX Item "OSSL_STORE_LOADER_fetch"
.PD
.PP
See \fBOSSL_PROVIDER\-default\fR\|(7), <\fBOSSL_PROVIDER\-fips\fR\|(7)> and
<\fBOSSL_PROVIDER\-legacy\fR\|(7)>for a list of algorithm names that
can be fetched.
.SH "FETCHING EXAMPLES"
.IX Header "FETCHING EXAMPLES"
The following section provides a series of examples of fetching algorithm
implementations.
.PP
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:
.PP
.Vb 3
\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", NULL);
\& ...
\& EVP_MD_free(md);
.Ve
.PP
Fetch any available implementation of \s-1AES\-128\-CBC\s0 in the default context:
.PP
.Vb 3
\& EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES\-128\-CBC", NULL);
\& ...
\& EVP_CIPHER_free(cipher);
.Ve
.PP
Fetch an implementation of \s-1SHA2\-256\s0 from the default provider in the default
context:
.PP
.Vb 3
\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider=default");
\& ...
\& EVP_MD_free(md);
.Ve
.PP
Fetch an implementation of \s-1SHA2\-256\s0 that is not from the default provider in the
default context:
.PP
.Vb 3
\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider!=default");
\& ...
\& EVP_MD_free(md);
.Ve
.PP
Fetch an implementation of \s-1SHA2\-256\s0 from the default provider in the specified
context:
.PP
.Vb 3
\& EVP_MD *md = EVP_MD_fetch(ctx, "SHA2\-256", "provider=default");
\& ...
\& EVP_MD_free(md);
.Ve
.PP
Load the legacy provider into the default context and then fetch an
implementation of \s-1WHIRLPOOL\s0 from it:
.PP
.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
.PP
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:
.PP
.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
.SH "OPENSSL PROVIDERS"
.IX Header "OPENSSL PROVIDERS"
OpenSSL comes with a set of providers.
.PP
The algorithms available in each of these providers may vary due to build time
configuration options. The \fBopenssl\-list\fR\|(1) command can be used to list the
currently available algorithms.
.PP
The names of the algorithms shown from \fBopenssl\-list\fR\|(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.
.PP
As well as the OpenSSL providers third parties can also implement providers.
For information on writing a provider see \fBprovider\fR\|(7).
.SS "Default provider"
.IX Subsection "Default provider"
The default provider is built in as part of the \fIlibcrypto\fR library and
contains all of the most commonly used algorithm implementations. Should it be
needed (if other providers are loaded and offer implementations of the same
algorithms), the property query string \*(L"provider=default\*(R" can be used as a
search criterion for these implementations.  The default provider includes all
of the functionality in the base provider below.
.PP
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.
.PP
See \fBOSSL_PROVIDER\-default\fR\|(7).
.SS "Base provider"
.IX Subsection "Base provider"
The base provider is built in as part of the \fIlibcrypto\fR library and contains
algorithm implementations for encoding and decoding for OpenSSL keys.
Should it be needed (if other providers are loaded and offer
implementations of the same algorithms), the property query string
\&\*(L"provider=base\*(R" can be used as a search criterion for these implementations.
Some encoding and decoding algorithm implementations are not \s-1FIPS\s0 algorithm
implementations in themselves but support algorithms from the \s-1FIPS\s0 provider and
are allowed for use in \*(L"\s-1FIPS\s0 mode\*(R". The property query string \*(L"fips=yes\*(R" can be
used to select such algorithms.
.PP
See \fBOSSL_PROVIDER\-base\fR\|(7).
.SS "\s-1FIPS\s0 provider"
.IX Subsection "FIPS provider"
The \s-1FIPS\s0 provider is a dynamically loadable module, and must therefore
be loaded explicitly, either in code or through OpenSSL configuration
(see \fBconfig\fR\|(5)). It contains algorithm implementations that have been
validated according to the \s-1FIPS 140\-2\s0 standard. Should it be needed (if other
providers are loaded and offer implementations of the same algorithms), the
property query string \*(L"provider=fips\*(R" can be used as a search criterion for
these implementations. All approved algorithm implementations in the \s-1FIPS\s0
provider can also be selected with the property \*(L"fips=yes\*(R". The \s-1FIPS\s0 provider
may also contain non-approved algorithm implementations and these can be
selected with the property \*(L"fips=no\*(R".
.PP
See \s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7) and \fBfips_module\fR\|(7).
.SS "Legacy provider"
.IX Subsection "Legacy provider"
The legacy provider is a dynamically loadable module, and must therefore
be loaded explicitly, either in code or through OpenSSL configuration
(see \fBconfig\fR\|(5)). It contains algorithm implementations that are considered
insecure, or are no longer in common use such as \s-1MD2\s0 or \s-1RC4.\s0 Should it be needed
(if other providers are loaded and offer implementations of the same algorithms),
the property \*(L"provider=legacy\*(R" can be used as a search criterion for these
implementations.
.PP
See \fBOSSL_PROVIDER\-legacy\fR\|(7).
.SS "Null provider"
.IX Subsection "Null provider"
The null provider is built in as part of the \fIlibcrypto\fR library. It contains
no algorithms in it at all. When fetching algorithms the default provider will
be automatically loaded if no other provider has been explicitly loaded. To
prevent that from happening you can explicitly load the null provider.
.PP
See \fBOSSL_PROVIDER\-null\fR\|(7).
.SH "USING ALGORITHMS IN APPLICATIONS"
.IX Header "USING ALGORITHMS IN APPLICATIONS"
Cryptographic algorithms are made available to applications through use of the
\&\*(L"\s-1EVP\*(R"\s0 APIs. Each of the various operations such as encryption, digesting,
message authentication codes, etc., have a set of \s-1EVP\s0 function calls that can
be invoked to use them. See the \fBevp\fR\|(7) page for further details.
.PP
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 \fB\s-1EVP_MD_CTX\s0\fR, and for an
encryption/decryption operation you would use an \fB\s-1EVP_CIPHER_CTX\s0\fR. The
operation is then initialised ready for use via an \*(L"init\*(R" function \- optionally
passing in a set of parameters (using the \s-1\fBOSSL_PARAM\s0\fR\|(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.
.PP
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.
.PP
.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
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
By default OpenSSL will load a configuration file when it is first used. This
will set up various configuration settings within the default library context.
Applications that create their own library contexts may optionally configure
them with a config file using the \fBOSSL_LIB_CTX_load_config\fR\|(3) function.
.PP
The configuration file can be used to automatically load providers and set up
default property query strings.
.PP
For information on the OpenSSL configuration file format see \fBconfig\fR\|(5).
.SH "ENCODING AND DECODING KEYS"
.IX Header "ENCODING AND DECODING KEYS"
Many algorithms require the use of a key. Keys can be generated dynamically
using the \s-1EVP\s0 APIs (for example see \fBEVP_PKEY_Q_keygen\fR\|(3)). However it is often
necessary to save or load keys (or their associated parameters) to or from some
external format such as \s-1PEM\s0 or \s-1DER\s0 (see \fBopenssl\-glossary\fR\|(7)). OpenSSL uses
encoders and decoders to perform this task.
.PP
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.
.PP
For information about encoders see \fBOSSL_ENCODER_CTX_new_for_pkey\fR\|(3). For
information about decoders see \fBOSSL_DECODER_CTX_new_for_pkey\fR\|(3).
.SH "LIBRARY CONVENTIONS"
.IX Header "LIBRARY CONVENTIONS"
Many OpenSSL functions that \*(L"get\*(R" or \*(L"set\*(R" a value follow a naming convention
using the numbers \fB0\fR and \fB1\fR, i.e. \*(L"get0\*(R", \*(L"get1\*(R", \*(L"set0\*(R" and \*(L"set1\*(R". This
can also apply to some functions that \*(L"add\*(R" a value to an existing set, i.e.
\&\*(L"add0\*(R" and \*(L"add1\*(R".
.PP
For example the functions:
.PP
.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
.PP
In the \fB0\fR 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()\fR function above, ownership of the \fIrev\fR object is passed
to the \fIcrl\fR object. Therefore, after calling this function \fIrev\fR should not
be freed directly. It will be freed implicitly when \fIcrl\fR is freed.
.PP
In the \fB1\fR 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 \fBX509_add1_trust_object()\fR function above the application will
still be responsible for freeing the \fIobj\fR value where appropriate.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBopenssl\fR\|(1), \fBssl\fR\|(7), \fBevp\fR\|(7), \s-1\fBOSSL_LIB_CTX\s0\fR\|(3), \fBopenssl\-threads\fR\|(7),
\&\fBproperty\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7), \fBOSSL_PROVIDER\-base\fR\|(7),
\&\s-1\fBOSSL_PROVIDER\-FIPS\s0\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7), \fBOSSL_PROVIDER\-null\fR\|(7),
\&\fBopenssl\-glossary\fR\|(7), \fBprovider\fR\|(7)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
.PP
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>.