1=pod
2
3=head1 NAME
4
5ossl-guide-libcrypto-introduction, crypto
6- OpenSSL Guide: An introduction to libcrypto
7
8
9=head1 INTRODUCTION
10
11The OpenSSL cryptography library (C<libcrypto>) enables access to a wide range
12of cryptographic algorithms used in various Internet standards. The services
13provided by this library are used by the OpenSSL implementations of TLS and
14CMS, and they have also been used to implement many other third party products
15and protocols.
16
17The functionality includes symmetric encryption, public key cryptography, key
18agreement, certificate handling, cryptographic hash functions, cryptographic
19pseudo-random number generators, message authentication codes (MACs), key
20derivation functions (KDFs), and various utilities.
21
22=head2 Algorithms
23
24Cryptographic primitives such as the SHA256 digest, or AES encryption are
25referred to in OpenSSL as "algorithms". Each algorithm may have multiple
26implementations available for use. For example the RSA algorithm is available as
27a "default" implementation suitable for general use, and a "fips" implementation
28which has been validated to FIPS 140 standards for situations where that is
29important. It is also possible that a third party could add additional
30implementations such as in a hardware security module (HSM).
31
32Algorithms are implemented in providers. See
33L<ossl-guide-libraries-introduction(7)> for information about providers.
34
35=head2 Operations
36
37Different algorithms can be grouped together by their purpose. For example there
38are algorithms for encryption, and different algorithms for digesting data.
39These different groups are known as "operations" in OpenSSL. Each operation
40has a different set of functions associated with it. For example to perform an
41encryption operation using AES (or any other encryption algorithm) you would use
42the encryption functions detailed on the L<EVP_EncryptInit(3)> page. Or to
43perform a digest operation using SHA256 then you would use the digesting
44functions on the L<EVP_DigestInit(3)> page.
45
46=head1 ALGORITHM FETCHING
47
48In order to use an algorithm an implementation for it must first be "fetched".
49Fetching is the process of looking through the available implementations,
50applying selection criteria (via a property query string), and finally choosing
51the implementation that will be used.
52
53Two types of fetching are supported by OpenSSL - L</Explicit fetching> and
54L</Implicit fetching>.
55
56=head2 Explicit fetching
57
58Explicit fetching involves directly calling a specific API to fetch an algorithm
59implementation from a provider. This fetched object can then be passed to other
60APIs. These explicit fetching functions usually have the name C<APINAME_fetch>,
61where C<APINAME> is the name of the operation. For example L<EVP_MD_fetch(3)>
62can be used to explicitly fetch a digest algorithm implementation. The user is
63responsible for freeing the object returned from the C<APINAME_fetch> function
64using C<APINAME_free> when it is no longer needed.
65
66These fetching functions follow a fairly common pattern, where three
67arguments are passed:
68
69=over 4
70
71=item The library context
72
73See L<OSSL_LIB_CTX(3)> for a more detailed description.
74This may be NULL to signify the default (global) library context, or a
75context created by the user. Only providers loaded in this library context (see
76L<OSSL_PROVIDER_load(3)>) will be considered by the fetching function. In case
77no provider has been loaded in this library context then the default provider
78will be loaded as a fallback (see L<OSSL_PROVIDER-default(7)>).
79
80=item An identifier
81
82For all currently implemented fetching functions this is the algorithm name.
83Each provider supports a list of algorithm implementations. See the provider
84specific documentation for information on the algorithm implementations
85available in each provider:
86L<OSSL_PROVIDER-default(7)/OPERATIONS AND ALGORITHMS>,
87L<OSSL_PROVIDER-FIPS(7)/OPERATIONS AND ALGORITHMS>,
88L<OSSL_PROVIDER-legacy(7)/OPERATIONS AND ALGORITHMS> and
89L<OSSL_PROVIDER-base(7)/OPERATIONS AND ALGORITHMS>.
90
91Note, while providers may register algorithms against a list of names using a
92string with a colon separated list of names, fetching algorithms using that
93format is currently unsupported.
94
95=item A property query string
96
97The property query string used to guide selection of the algorithm
98implementation. See
99L<ossl-guide-libraries-introduction(7)/PROPERTY QUERY STRINGS>.
100
101=back
102
103The algorithm implementation that is fetched can then be used with other diverse
104functions that use them. For example the L<EVP_DigestInit_ex(3)> function takes
105as a parameter an B<EVP_MD> object which may have been returned from an earlier
106call to L<EVP_MD_fetch(3)>.
107
108=head2 Implicit fetching
109
110OpenSSL has a number of functions that return an algorithm object with no
111associated implementation, such as L<EVP_sha256(3)>, L<EVP_aes_128_cbc(3)>,
112L<EVP_get_cipherbyname(3)> or L<EVP_get_digestbyname(3)>. These are present for
113compatibility with OpenSSL before version 3.0 where explicit fetching was not
114available.
115
116When they are used with functions like L<EVP_DigestInit_ex(3)> or
117L<EVP_CipherInit_ex(3)>, the actual implementation to be used is
118fetched implicitly using default search criteria (which uses NULL for the
119library context and property query string).
120
121In some cases implicit fetching can also occur when a NULL algorithm parameter
122is supplied. In this case an algorithm implementation is implicitly fetched
123using default search criteria and an algorithm name that is consistent with
124the context in which it is being used.
125
126Functions that use an B<EVP_PKEY_CTX> or an L<EVP_PKEY(3)>, such as
127L<EVP_DigestSignInit(3)>, all fetch the implementations implicitly. Usually the
128algorithm to fetch is determined based on the type of key that is being used and
129the function that has been called.
130
131=head2 Performance
132
133If you perform the same operation many times with the same algorithm then it is
134recommended to use a single explicit fetch of the algorithm and then reuse the
135explicitly fetched algorithm each subsequent time. This will typically be
136faster than implicitly fetching the algorithm every time you use it. See an
137example of Explicit fetching in L</USING ALGORITHMS IN APPLICATIONS>.
138
139Prior to OpenSSL 3.0, functions such as EVP_sha256() which return a "const"
140object were used directly to indicate the algorithm to use in various function
141calls. If you pass the return value of one of these convenience functions to an
142operation then you are using implicit fetching. If you are converting an
143application that worked with an OpenSSL version prior to OpenSSL 3.0 then
144consider changing instances of implicit fetching to explicit fetching instead.
145
146If an explicitly fetched object is not passed to an operation, then any implicit
147fetch will use an internally cached prefetched object, but it will
148still be slower than passing the explicitly fetched object directly.
149
150The following functions can be used for explicit fetching:
151
152=over 4
153
154=item L<EVP_MD_fetch(3)>
155
156Fetch a message digest/hashing algorithm implementation.
157
158=item L<EVP_CIPHER_fetch(3)>
159
160Fetch a symmetric cipher algorithm implementation.
161
162=item L<EVP_KDF_fetch(3)>
163
164Fetch a Key Derivation Function (KDF) algorithm implementation.
165
166=item L<EVP_MAC_fetch(3)>
167
168Fetch a Message Authentication Code (MAC) algorithm implementation.
169
170=item L<EVP_KEM_fetch(3)>
171
172Fetch a Key Encapsulation Mechanism (KEM) algorithm implementation
173
174=item L<OSSL_ENCODER_fetch(3)>
175
176Fetch an encoder algorithm implementation (e.g. to encode keys to a specified
177format).
178
179=item L<OSSL_DECODER_fetch(3)>
180
181Fetch a decoder algorithm implementation (e.g. to decode keys from a specified
182format).
183
184=item L<EVP_RAND_fetch(3)>
185
186Fetch a Pseudo Random Number Generator (PRNG) algorithm implementation.
187
188=back
189
190See L<OSSL_PROVIDER-default(7)/OPERATIONS AND ALGORITHMS>,
191L<OSSL_PROVIDER-FIPS(7)/OPERATIONS AND ALGORITHMS>,
192L<OSSL_PROVIDER-legacy(7)/OPERATIONS AND ALGORITHMS> and
193L<OSSL_PROVIDER-base(7)/OPERATIONS AND ALGORITHMS> for a list of algorithm names
194that can be fetched.
195
196=head1 FETCHING EXAMPLES
197
198The following section provides a series of examples of fetching algorithm
199implementations.
200
201Fetch any available implementation of SHA2-256 in the default context. Note
202that some algorithms have aliases. So "SHA256" and "SHA2-256" are synonymous:
203
204 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", NULL);
205 ...
206 EVP_MD_free(md);
207
208Fetch any available implementation of AES-128-CBC in the default context:
209
210 EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL);
211 ...
212 EVP_CIPHER_free(cipher);
213
214Fetch an implementation of SHA2-256 from the default provider in the default
215context:
216
217 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");
218 ...
219 EVP_MD_free(md);
220
221Fetch an implementation of SHA2-256 that is not from the default provider in the
222default context:
223
224 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider!=default");
225 ...
226 EVP_MD_free(md);
227
228Fetch an implementation of SHA2-256 that is preferably from the FIPS provider in
229the default context:
230
231 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider=?fips");
232 ...
233 EVP_MD_free(md);
234
235Fetch an implementation of SHA2-256 from the default provider in the specified
236library context:
237
238 EVP_MD *md = EVP_MD_fetch(libctx, "SHA2-256", "provider=default");
239 ...
240 EVP_MD_free(md);
241
242Load the legacy provider into the default context and then fetch an
243implementation of WHIRLPOOL from it:
244
245 /* This only needs to be done once - usually at application start up */
246 OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
247
248 EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy");
249 ...
250 EVP_MD_free(md);
251
252Note that in the above example the property string "provider=legacy" is optional
253since, assuming no other providers have been loaded, the only implementation of
254the "whirlpool" algorithm is in the "legacy" provider. Also note that the
255default provider should be explicitly loaded if it is required in addition to
256other providers:
257
258 /* This only needs to be done once - usually at application start up */
259 OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
260 OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");
261
262 EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
263 EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
264 ...
265 EVP_MD_free(md_whirlpool);
266 EVP_MD_free(md_sha256);
267
268
269=head1 USING ALGORITHMS IN APPLICATIONS
270
271Cryptographic algorithms are made available to applications through use of the
272"EVP" APIs. Each of the various operations such as encryption, digesting,
273message authentication codes, etc., have a set of EVP function calls that can
274be invoked to use them. See the L<evp(7)> page for further details.
275
276Most of these follow a common pattern. A "context" object is first created. For
277example for a digest operation you would use an B<EVP_MD_CTX>, and for an
278encryption/decryption operation you would use an B<EVP_CIPHER_CTX>. The
279operation is then initialised ready for use via an "init" function - optionally
280passing in a set of parameters (using the L<OSSL_PARAM(3)> type) to configure how
281the operation should behave. Next data is fed into the operation in a series of
282"update" calls. The operation is finalised using a "final" call which will
283typically provide some kind of output. Finally the context is cleaned up and
284freed.
285
286The following shows a complete example for doing this process for digesting
287data using SHA256. The process is similar for other operations such as
288encryption/decryption, signatures, message authentication codes, etc. Additional
289examples can be found in the OpenSSL demos (see
290L<ossl-guide-libraries-introduction(7)/DEMO APPLICATIONS>).
291
292 #include <stdio.h>
293 #include <openssl/evp.h>
294 #include <openssl/bio.h>
295 #include <openssl/err.h>
296
297 int main(void)
298 {
299     EVP_MD_CTX *ctx = NULL;
300     EVP_MD *sha256 = NULL;
301     const unsigned char msg[] = {
302         0x00, 0x01, 0x02, 0x03
303     };
304     unsigned int len = 0;
305     unsigned char *outdigest = NULL;
306     int ret = 1;
307
308     /* Create a context for the digest operation */
309     ctx = EVP_MD_CTX_new();
310     if (ctx == NULL)
311         goto err;
312
313     /*
314      * Fetch the SHA256 algorithm implementation for doing the digest. We're
315      * using the "default" library context here (first NULL parameter), and
316      * we're not supplying any particular search criteria for our SHA256
317      * implementation (second NULL parameter). Any SHA256 implementation will
318      * do.
319      * In a larger application this fetch would just be done once, and could
320      * be used for multiple calls to other operations such as EVP_DigestInit_ex().
321      */
322     sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
323     if (sha256 == NULL)
324         goto err;
325
326    /* Initialise the digest operation */
327    if (!EVP_DigestInit_ex(ctx, sha256, NULL))
328        goto err;
329
330     /*
331      * Pass the message to be digested. This can be passed in over multiple
332      * EVP_DigestUpdate calls if necessary
333      */
334     if (!EVP_DigestUpdate(ctx, msg, sizeof(msg)))
335         goto err;
336
337     /* Allocate the output buffer */
338     outdigest = OPENSSL_malloc(EVP_MD_get_size(sha256));
339     if (outdigest == NULL)
340         goto err;
341
342     /* Now calculate the digest itself */
343     if (!EVP_DigestFinal_ex(ctx, outdigest, &len))
344         goto err;
345
346     /* Print out the digest result */
347     BIO_dump_fp(stdout, outdigest, len);
348
349     ret = 0;
350
351  err:
352     /* Clean up all the resources we allocated */
353     OPENSSL_free(outdigest);
354     EVP_MD_free(sha256);
355     EVP_MD_CTX_free(ctx);
356     if (ret != 0)
357        ERR_print_errors_fp(stderr);
358     return ret;
359 }
360
361=head1 ENCODING AND DECODING KEYS
362
363Many algorithms require the use of a key. Keys can be generated dynamically
364using the EVP APIs (for example see L<EVP_PKEY_Q_keygen(3)>). However it is often
365necessary to save or load keys (or their associated parameters) to or from some
366external format such as PEM or DER (see L<openssl-glossary(7)>). OpenSSL uses
367encoders and decoders to perform this task.
368
369Encoders and decoders are just algorithm implementations in the same way as
370any other algorithm implementation in OpenSSL. They are implemented by
371providers. The OpenSSL encoders and decoders are available in the default
372provider. They are also duplicated in the base provider.
373
374For information about encoders see L<OSSL_ENCODER_CTX_new_for_pkey(3)>. For
375information about decoders see L<OSSL_DECODER_CTX_new_for_pkey(3)>.
376
377As well as using encoders/decoders directly there are also some helper functions
378that can be used for certain well known and commonly used formats. For example
379see L<PEM_read_PrivateKey(3)> and L<PEM_write_PrivateKey(3)> for information
380about reading and writing key data from PEM encoded files.
381
382=head1 FURTHER READING
383
384See L<ossl-guide-libssl-introduction(7)> for an introduction to using C<libssl>.
385
386=head1 SEE ALSO
387
388L<openssl(1)>, L<ssl(7)>, L<evp(7)>, L<OSSL_LIB_CTX(3)>, L<openssl-threads(7)>,
389L<property(7)>, L<OSSL_PROVIDER-default(7)>, L<OSSL_PROVIDER-base(7)>,
390L<OSSL_PROVIDER-FIPS(7)>, L<OSSL_PROVIDER-legacy(7)>, L<OSSL_PROVIDER-null(7)>,
391L<openssl-glossary(7)>, L<provider(7)>
392
393=head1 COPYRIGHT
394
395Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved.
396
397Licensed under the Apache License 2.0 (the "License").  You may not use
398this file except in compliance with the License.  You can obtain a copy
399in the file LICENSE in the source distribution or at
400L<https://www.openssl.org/source/license.html>.
401
402=cut
403