522 lines
21 KiB
Plaintext
522 lines
21 KiB
Plaintext
|
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
|
||
|
|
.\"
|
||
|
|
.\" 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 turned on, 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 "OSSL-GUIDE-LIBCRYPTO-INTRODUCTION 7ossl"
|
||
|
|
.TH OSSL-GUIDE-LIBCRYPTO-INTRODUCTION 7ossl "2024-01-30" "3.2.1" "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"
|
||
|
|
ossl\-guide\-libcrypto\-introduction, crypto
|
||
|
|
\&\- OpenSSL Guide: An introduction to libcrypto
|
||
|
|
.SH "INTRODUCTION"
|
||
|
|
.IX Header "INTRODUCTION"
|
||
|
|
The OpenSSL cryptography library (\f(CW\*(C`libcrypto\*(C'\fR) 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 \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 140\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).
|
||
|
|
.PP
|
||
|
|
Algorithms are implemented in providers. See
|
||
|
|
\&\fIossl\-guide\-libraries\-introduction\fR\|(7) for information about providers.
|
||
|
|
.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 \fIEVP_EncryptInit\fR\|(3) page. Or to
|
||
|
|
perform a digest operation using \s-1SHA256\s0 then you would use the digesting
|
||
|
|
functions on the \fIEVP_DigestInit\fR\|(3) page.
|
||
|
|
.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 \- \*(L"Explicit fetching\*(R" and
|
||
|
|
\&\*(L"Implicit fetching\*(R".
|
||
|
|
.SS "Explicit fetching"
|
||
|
|
.IX Subsection "Explicit fetching"
|
||
|
|
Explicit fetching involves directly calling a specific \s-1API\s0 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 \f(CW\*(C`APINAME_fetch\*(C'\fR,
|
||
|
|
where \f(CW\*(C`APINAME\*(C'\fR is the name of the operation. For example \fIEVP_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\fIOSSL_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
|
||
|
|
\&\fIOSSL_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 \fIOSSL_PROVIDER\-default\fR\|(7)).
|
||
|
|
.IP "An identifier" 4
|
||
|
|
.IX Item "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:
|
||
|
|
\&\*(L"\s-1OPERATIONS AND ALGORITHMS\*(R"\s0 in \fIOSSL_PROVIDER\-default\fR\|(7),
|
||
|
|
\&\*(L"\s-1OPERATIONS AND ALGORITHMS\*(R"\s0 in \s-1\fIOSSL_PROVIDER\-FIPS\s0\fR\|(7),
|
||
|
|
\&\*(L"\s-1OPERATIONS AND ALGORITHMS\*(R"\s0 in \fIOSSL_PROVIDER\-legacy\fR\|(7) and
|
||
|
|
\&\*(L"\s-1OPERATIONS AND ALGORITHMS\*(R"\s0 in \fIOSSL_PROVIDER\-base\fR\|(7).
|
||
|
|
.Sp
|
||
|
|
Note, 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.
|
||
|
|
.IP "A property query string" 4
|
||
|
|
.IX Item "A property query string"
|
||
|
|
The property query string used to guide selection of the algorithm
|
||
|
|
implementation. See
|
||
|
|
\&\*(L"\s-1PROPERTY QUERY STRINGS\*(R"\s0 in \fIossl\-guide\-libraries\-introduction\fR\|(7).
|
||
|
|
.PP
|
||
|
|
The algorithm implementation that is fetched can then be used with other diverse
|
||
|
|
functions that use them. For example the \fIEVP_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 \fIEVP_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 \fIEVP_sha256\fR\|(3), \fIEVP_aes_128_cbc\fR\|(3),
|
||
|
|
\&\fIEVP_get_cipherbyname\fR\|(3) or \fIEVP_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 \fIEVP_DigestInit_ex\fR\|(3) or
|
||
|
|
\&\fIEVP_CipherInit_ex\fR\|(3), the actual implementation to be used is
|
||
|
|
fetched implicitly using default search criteria (which uses \s-1NULL\s0 for the
|
||
|
|
library context and property query string).
|
||
|
|
.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 use an \fB\s-1EVP_PKEY_CTX\s0\fR or an \s-1\fIEVP_PKEY\s0\fR\|(3), such as
|
||
|
|
\&\fIEVP_DigestSignInit\fR\|(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.
|
||
|
|
.SS "Performance"
|
||
|
|
.IX Subsection "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 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 \*(L"\s-1USING ALGORITHMS IN APPLICATIONS\*(R"\s0.
|
||
|
|
.PP
|
||
|
|
Prior to OpenSSL 3.0, functions such as \fIEVP_sha256()\fR which return a \*(L"const\*(R"
|
||
|
|
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.
|
||
|
|
.PP
|
||
|
|
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.
|
||
|
|
.PP
|
||
|
|
The following functions can be used for explicit fetching:
|
||
|
|
.IP "\fIEVP_MD_fetch\fR\|(3)" 4
|
||
|
|
.IX Item "EVP_MD_fetch"
|
||
|
|
Fetch a message digest/hashing algorithm implementation.
|
||
|
|
.IP "\fIEVP_CIPHER_fetch\fR\|(3)" 4
|
||
|
|
.IX Item "EVP_CIPHER_fetch"
|
||
|
|
Fetch a symmetric cipher algorithm implementation.
|
||
|
|
.IP "\fIEVP_KDF_fetch\fR\|(3)" 4
|
||
|
|
.IX Item "EVP_KDF_fetch"
|
||
|
|
Fetch a Key Derivation Function (\s-1KDF\s0) algorithm implementation.
|
||
|
|
.IP "\fIEVP_MAC_fetch\fR\|(3)" 4
|
||
|
|
.IX Item "EVP_MAC_fetch"
|
||
|
|
Fetch a Message Authentication Code (\s-1MAC\s0) algorithm implementation.
|
||
|
|
.IP "\fIEVP_KEM_fetch\fR\|(3)" 4
|
||
|
|
.IX Item "EVP_KEM_fetch"
|
||
|
|
Fetch a Key Encapsulation Mechanism (\s-1KEM\s0) algorithm implementation
|
||
|
|
.IP "\fIOSSL_ENCODER_fetch\fR\|(3)" 4
|
||
|
|
.IX Item "OSSL_ENCODER_fetch"
|
||
|
|
Fetch an encoder algorithm implementation (e.g. to encode keys to a specified
|
||
|
|
format).
|
||
|
|
.IP "\fIOSSL_DECODER_fetch\fR\|(3)" 4
|
||
|
|
.IX Item "OSSL_DECODER_fetch"
|
||
|
|
Fetch a decoder algorithm implementation (e.g. to decode keys from a specified
|
||
|
|
format).
|
||
|
|
.IP "\fIEVP_RAND_fetch\fR\|(3)" 4
|
||
|
|
.IX Item "EVP_RAND_fetch"
|
||
|
|
Fetch a Pseudo Random Number Generator (\s-1PRNG\s0) algorithm implementation.
|
||
|
|
.PP
|
||
|
|
See \*(L"\s-1OPERATIONS AND ALGORITHMS\*(R"\s0 in \fIOSSL_PROVIDER\-default\fR\|(7),
|
||
|
|
\&\*(L"\s-1OPERATIONS AND ALGORITHMS\*(R"\s0 in \s-1\fIOSSL_PROVIDER\-FIPS\s0\fR\|(7),
|
||
|
|
\&\*(L"\s-1OPERATIONS AND ALGORITHMS\*(R"\s0 in \fIOSSL_PROVIDER\-legacy\fR\|(7) and
|
||
|
|
\&\*(L"\s-1OPERATIONS AND ALGORITHMS\*(R"\s0 in \fIOSSL_PROVIDER\-base\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 that is preferably from the \s-1FIPS\s0 provider in
|
||
|
|
the default context:
|
||
|
|
.PP
|
||
|
|
.Vb 3
|
||
|
|
\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider=?fips");
|
||
|
|
\& ...
|
||
|
|
\& EVP_MD_free(md);
|
||
|
|
.Ve
|
||
|
|
.PP
|
||
|
|
Fetch an implementation of \s-1SHA2\-256\s0 from the default provider in the specified
|
||
|
|
library context:
|
||
|
|
.PP
|
||
|
|
.Vb 3
|
||
|
|
\& EVP_MD *md = EVP_MD_fetch(libctx, "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 "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 \fIevp\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\fIOSSL_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. Additional
|
||
|
|
examples can be found in the OpenSSL demos (see
|
||
|
|
\&\*(L"\s-1DEMO APPLICATIONS\*(R"\s0 in \fIossl\-guide\-libraries\-introduction\fR\|(7)).
|
||
|
|
.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 "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 \fIEVP_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 \fIopenssl\-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 \fIOSSL_ENCODER_CTX_new_for_pkey\fR\|(3). For
|
||
|
|
information about decoders see \fIOSSL_DECODER_CTX_new_for_pkey\fR\|(3).
|
||
|
|
.PP
|
||
|
|
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 \fIPEM_read_PrivateKey\fR\|(3) and \fIPEM_write_PrivateKey\fR\|(3) for information
|
||
|
|
about reading and writing key data from \s-1PEM\s0 encoded files.
|
||
|
|
.SH "FURTHER READING"
|
||
|
|
.IX Header "FURTHER READING"
|
||
|
|
See \fIossl\-guide\-libssl\-introduction\fR\|(7) for an introduction to using \f(CW\*(C`libssl\*(C'\fR.
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
.IX Header "SEE ALSO"
|
||
|
|
\&\fIopenssl\fR\|(1), \fIssl\fR\|(7), \fIevp\fR\|(7), \s-1\fIOSSL_LIB_CTX\s0\fR\|(3), \fIopenssl\-threads\fR\|(7),
|
||
|
|
\&\fIproperty\fR\|(7), \fIOSSL_PROVIDER\-default\fR\|(7), \fIOSSL_PROVIDER\-base\fR\|(7),
|
||
|
|
\&\s-1\fIOSSL_PROVIDER\-FIPS\s0\fR\|(7), \fIOSSL_PROVIDER\-legacy\fR\|(7), \fIOSSL_PROVIDER\-null\fR\|(7),
|
||
|
|
\&\fIopenssl\-glossary\fR\|(7), \fIprovider\fR\|(7)
|
||
|
|
.SH "COPYRIGHT"
|
||
|
|
.IX Header "COPYRIGHT"
|
||
|
|
Copyright 2000\-2024 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>.
|