1CRYPTO(7ossl)                       OpenSSL                      CRYPTO(7ossl)
2
3
4

NAME

6       crypto - OpenSSL cryptographic library
7

SYNOPSIS

9       See the individual manual pages for details.
10

DESCRIPTION

12       The OpenSSL crypto library ("libcrypto") implements a wide range of
13       cryptographic algorithms used in various Internet standards. The
14       services provided by this library are used by the OpenSSL
15       implementations of TLS and CMS, and they have also been used to
16       implement many other third party products and protocols.
17
18       The functionality includes symmetric encryption, public key
19       cryptography, key agreement, certificate handling, cryptographic hash
20       functions, cryptographic pseudo-random number generators, message
21       authentication codes (MACs), key derivation functions (KDFs), and
22       various utilities.
23
24   Algorithms
25       Cryptographic primitives such as the SHA256 digest, or AES encryption
26       are referred to in OpenSSL as "algorithms". Each algorithm may have
27       multiple implementations available for use. For example the RSA
28       algorithm is available as a "default" implementation suitable for
29       general use, and a "fips" implementation which has been validated to
30       FIPS standards for situations where that is important. It is also
31       possible that a third party could add additional implementations such
32       as in a hardware security module (HSM).
33
34   Operations
35       Different algorithms can be grouped together by their purpose. For
36       example there are algorithms for encryption, and different algorithms
37       for digesting data.  These different groups are known as "operations"
38       in OpenSSL. Each operation has a different set of functions associated
39       with it. For example to perform an encryption operation using AES (or
40       any other encryption algorithm) you would use the encryption functions
41       detailed on the EVP_EncryptInit(3) page. Or to perform a digest
42       operation using SHA256 then you would use the digesting functions on
43       the EVP_DigestInit(3) page.
44
45   Providers
46       A provider in OpenSSL is a component that collects together algorithm
47       implementations. In order to use an algorithm you must have at least
48       one provider loaded that contains an implementation of it. OpenSSL
49       comes with a number of providers and they may also be obtained from
50       third parties. If you don't load a provider explicitly (either in
51       program code or via config) then the OpenSSL built-in "default"
52       provider will be automatically loaded.
53
54   Library contexts
55       A library context can be thought of as a "scope" within which
56       configuration options take effect. When a provider is loaded, it is
57       only loaded within the scope of a given library context. In this way it
58       is possible for different components of a complex application to each
59       use a different library context and have different providers loaded
60       with different configuration settings.
61
62       If an application does not explicitly create a library context then the
63       "default" library context will be used.
64
65       Library contexts are represented by the OSSL_LIB_CTX type. Many OpenSSL
66       API functions take a library context as a parameter. Applications can
67       always pass NULL for this parameter to just use the default library
68       context.
69
70       The default library context is automatically created the first time it
71       is needed. This will automatically load any available configuration
72       file and will initialise OpenSSL for use. Unlike in earlier versions of
73       OpenSSL (prior to 1.1.0) no explicit initialisation steps need to be
74       taken.
75
76       Similarly when the application exits the default library context is
77       automatically destroyed. No explicit de-initialisation steps need to be
78       taken.
79
80       See OSSL_LIB_CTX(3) for more information about library contexts.  See
81       also "ALGORITHM FETCHING".
82
83   Multi-threaded applications
84       As long as OpenSSL has been built with support for threads (the default
85       case on most platforms) then most OpenSSL functions are thread-safe in
86       the sense that it is safe to call the same function from multiple
87       threads at the same time. However most OpenSSL data structures are not
88       thread-safe. For example the BIO_write(3) and BIO_read(3) functions are
89       thread safe. However it would not be thread safe to call BIO_write()
90       from one thread while calling BIO_read() in another where both
91       functions are passed the same BIO object since both of them may attempt
92       to make changes to the same BIO object.
93
94       There are exceptions to these rules. A small number of functions are
95       not thread safe at all. Where this is the case this restriction should
96       be noted in the documentation for the function. Similarly some data
97       structures may be partially or fully thread safe. For example it is
98       safe to use an OSSL_LIB_CTX in multiple threads.
99
100       See openssl-threads(7) for a more detailed discussion on OpenSSL
101       threading support.
102

ALGORITHM FETCHING

104       In order to use an algorithm an implementation for it must first be
105       "fetched".  Fetching is the process of looking through the available
106       implementations, applying selection criteria (via a property query
107       string), and finally choosing the implementation that will be used.
108
109       Two types of fetching are supported by OpenSSL - explicit fetching and
110       implicit fetching.
111
112   Property query strings
113       When fetching an algorithm it is possible to specify a property query
114       string to guide the selection process. For example a property query
115       string of "provider=default" could be used to force the selection to
116       only consider algorithm implementations in the default provider.
117
118       Property query strings can be specified explicitly as an argument to a
119       function.  It is also possible to specify a default property query
120       string for the whole library context using the
121       EVP_set_default_properties(3) or EVP_default_properties_enable_fips(3)
122       functions. Where both default properties and function specific
123       properties are specified then they are combined. Function specific
124       properties will override default properties where there is a conflict.
125
126       See property(7) for more information about properties.
127
128   Explicit fetching
129       Users of the OpenSSL libraries never query a provider directly for an
130       algorithm implementation. Instead, the diverse OpenSSL APIs often have
131       explicit fetching functions that do the work, and they return an
132       appropriate algorithm object back to the user. These functions usually
133       have the name "APINAME_fetch", where "APINAME" is the name of the
134       operation. For example EVP_MD_fetch(3) can be used to explicitly fetch
135       a digest algorithm implementation. The user is responsible for freeing
136       the object returned from the "APINAME_fetch" function using
137       "APINAME_free" when it is no longer needed.
138
139       These fetching functions follow a fairly common pattern, where three
140       arguments are passed:
141
142       The library context
143           See OSSL_LIB_CTX(3) for a more detailed description.  This may be
144           NULL to signify the default (global) library context, or a context
145           created by the user. Only providers loaded in this library context
146           (see OSSL_PROVIDER_load(3)) will be considered by the fetching
147           function. In case no provider has been loaded in this library
148           context then the default provider will be loaded as a fallback (see
149           OSSL_PROVIDER-default(7)).
150
151       An identifier
152           For all currently implemented fetching functions this is the
153           algorithm name.
154
155       A property query string
156           The property query string used to guide selection of the algorithm
157           implementation.
158
159       The algorithm implementation that is fetched can then be used with
160       other diverse functions that use them. For example the
161       EVP_DigestInit_ex(3) function takes as a parameter an EVP_MD object
162       which may have been returned from an earlier call to EVP_MD_fetch(3).
163
164   Implicit fetching
165       OpenSSL has a number of functions that return an algorithm object with
166       no associated implementation, such as EVP_sha256(3),
167       EVP_aes_128_cbc(3), EVP_get_cipherbyname(3) or EVP_get_digestbyname(3).
168       These are present for compatibility with OpenSSL before version 3.0
169       where explicit fetching was not available.
170
171       When they are used with functions like EVP_DigestInit_ex(3) or
172       EVP_CipherInit_ex(3), the actual implementation to be used is fetched
173       implicitly using default search criteria.
174
175       In some cases implicit fetching can also occur when a NULL algorithm
176       parameter is supplied. In this case an algorithm implementation is
177       implicitly fetched using default search criteria and an algorithm name
178       that is consistent with the context in which it is being used.
179
180       Functions that revolve around EVP_PKEY_CTX and EVP_PKEY(3), such as
181       EVP_DigestSignInit(3) and friends, all fetch the implementations
182       implicitly.  Because these functions involve both an operation type
183       (such as EVP_SIGNATURE(3)) and an EVP_KEYMGMT(3) for the EVP_PKEY(3),
184       they try the following:
185
186       1.  Fetch the operation type implementation from any provider given a
187           library context and property string stored in the EVP_PKEY_CTX.
188
189           If the provider of the operation type implementation is different
190           from the provider of the EVP_PKEY(3)'s EVP_KEYMGMT(3)
191           implementation, try to fetch a EVP_KEYMGMT(3) implementation in the
192           same provider as the operation type implementation and export the
193           EVP_PKEY(3) to it (effectively making a temporary copy of the
194           original key).
195
196           If anything in this step fails, the next step is used as a
197           fallback.
198
199       2.  As a fallback, try to fetch the operation type implementation from
200           the same provider as the original EVP_PKEY(3)'s EVP_KEYMGMT(3),
201           still using the propery string from the EVP_PKEY_CTX.
202
203   Performance
204       If you perform the same operation many times then it is recommended to
205       use "Explicit fetching" to prefetch an algorithm once initially, and
206       then pass this created object to any operations that are currently
207       using "Implicit fetching".  See an example of Explicit fetching in
208       "USING ALGORITHMS IN APPLICATIONS".
209
210       Prior to OpenSSL 3.0, constant method tables (such as EVP_sha256())
211       were used directly to access methods. If you pass one of these
212       convenience functions to an operation the fixed methods are ignored,
213       and only the name is used to internally fetch methods from a provider.
214
215       If the prefetched object is not passed to operations, then any implicit
216       fetch will use the internally cached prefetched object, but it will
217       still be slower than passing the prefetched object directly.
218
219       Fetching via a provider offers more flexibility, but it is slower than
220       the old method, since it must search for the algorithm in all loaded
221       providers, and then populate the method table using provider supplied
222       methods.  Internally OpenSSL caches similar algorithms on the first
223       fetch (so loading a digest caches all digests).
224
225       The following methods can be used for prefetching:
226
227       EVP_MD_fetch(3)
228       EVP_CIPHER_fetch(3)
229       EVP_KDF_fetch(3)
230       EVP_MAC_fetch(3)
231       EVP_KEM_fetch(3)
232       OSSL_ENCODER_fetch(3)
233       OSSL_DECODER_fetch(3)
234       EVP_RAND_fetch(3)
235
236       The following methods are used internally when performing operations:
237
238       EVP_KEYMGMT_fetch(3)
239       EVP_KEYEXCH_fetch(3)
240       EVP_SIGNATURE_fetch(3)
241       OSSL_STORE_LOADER_fetch(3)
242
243       See OSSL_PROVIDER-default(7), <OSSL_PROVIDER-fips(7)> and
244       <OSSL_PROVIDER-legacy(7)>for a list of algorithm names that can be
245       fetched.
246

FETCHING EXAMPLES

248       The following section provides a series of examples of fetching
249       algorithm implementations.
250
251       Fetch any available implementation of SHA2-256 in the default context.
252       Note that some algorithms have aliases. So "SHA256" and "SHA2-256" are
253       synonymous:
254
255        EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", NULL);
256        ...
257        EVP_MD_free(md);
258
259       Fetch any available implementation of AES-128-CBC in the default
260       context:
261
262        EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL);
263        ...
264        EVP_CIPHER_free(cipher);
265
266       Fetch an implementation of SHA2-256 from the default provider in the
267       default context:
268
269        EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");
270        ...
271        EVP_MD_free(md);
272
273       Fetch an implementation of SHA2-256 that is not from the default
274       provider in the default context:
275
276        EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider!=default");
277        ...
278        EVP_MD_free(md);
279
280       Fetch an implementation of SHA2-256 from the default provider in the
281       specified context:
282
283        EVP_MD *md = EVP_MD_fetch(ctx, "SHA2-256", "provider=default");
284        ...
285        EVP_MD_free(md);
286
287       Load the legacy provider into the default context and then fetch an
288       implementation of WHIRLPOOL from it:
289
290        /* This only needs to be done once - usually at application start up */
291        OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
292
293        EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy");
294        ...
295        EVP_MD_free(md);
296
297       Note that in the above example the property string "provider=legacy" is
298       optional since, assuming no other providers have been loaded, the only
299       implementation of the "whirlpool" algorithm is in the "legacy"
300       provider. Also note that the default provider should be explicitly
301       loaded if it is required in addition to other providers:
302
303        /* This only needs to be done once - usually at application start up */
304        OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
305        OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");
306
307        EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
308        EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
309        ...
310        EVP_MD_free(md_whirlpool);
311        EVP_MD_free(md_sha256);
312

OPENSSL PROVIDERS

314       OpenSSL comes with a set of providers.
315
316       The algorithms available in each of these providers may vary due to
317       build time configuration options. The openssl-list(1) command can be
318       used to list the currently available algorithms.
319
320       The names of the algorithms shown from openssl-list(1) can be used as
321       an algorithm identifier to the appropriate fetching function. Also see
322       the provider specific manual pages linked below for further details
323       about using the algorithms available in each of the providers.
324
325       As well as the OpenSSL providers third parties can also implement
326       providers.  For information on writing a provider see provider(7).
327
328   Default provider
329       The default provider is built in as part of the libcrypto library and
330       contains all of the most commonly used algorithm implementations.
331       Should it be needed (if other providers are loaded and offer
332       implementations of the same algorithms), the property query string
333       "provider=default" can be used as a search criterion for these
334       implementations.  The default provider includes all of the
335       functionality in the base provider below.
336
337       If you don't load any providers at all then the "default" provider will
338       be automatically loaded. If you explicitly load any provider then the
339       "default" provider would also need to be explicitly loaded if it is
340       required.
341
342       See OSSL_PROVIDER-default(7).
343
344   Base provider
345       The base provider is built in as part of the libcrypto library and
346       contains algorithm implementations for encoding and decoding for
347       OpenSSL keys.  Should it be needed (if other providers are loaded and
348       offer implementations of the same algorithms), the property query
349       string "provider=base" can be used as a search criterion for these
350       implementations.  Some encoding and decoding algorithm implementations
351       are not FIPS algorithm implementations in themselves but support
352       algorithms from the FIPS provider and are allowed for use in "FIPS
353       mode". The property query string "fips=yes" can be used to select such
354       algorithms.
355
356       See OSSL_PROVIDER-base(7).
357
358   FIPS provider
359       The FIPS provider is a dynamically loadable module, and must therefore
360       be loaded explicitly, either in code or through OpenSSL configuration
361       (see config(5)). It contains algorithm implementations that have been
362       validated according to the FIPS 140-2 standard. Should it be needed (if
363       other providers are loaded and offer implementations of the same
364       algorithms), the property query string "provider=fips" can be used as a
365       search criterion for these implementations. All approved algorithm
366       implementations in the FIPS provider can also be selected with the
367       property "fips=yes". The FIPS provider may also contain non-approved
368       algorithm implementations and these can be selected with the property
369       "fips=no".
370
371       See OSSL_PROVIDER-FIPS(7) and fips_module(7).
372
373   Legacy provider
374       The legacy provider is a dynamically loadable module, and must
375       therefore be loaded explicitly, either in code or through OpenSSL
376       configuration (see config(5)). It contains algorithm implementations
377       that are considered insecure, or are no longer in common use such as
378       MD2 or RC4. Should it be needed (if other providers are loaded and
379       offer implementations of the same algorithms), the property
380       "provider=legacy" can be used as a search criterion for these
381       implementations.
382
383       See OSSL_PROVIDER-legacy(7).
384
385   Null provider
386       The null provider is built in as part of the libcrypto library. It
387       contains no algorithms in it at all. When fetching algorithms the
388       default provider will be automatically loaded if no other provider has
389       been explicitly loaded. To prevent that from happening you can
390       explicitly load the null provider.
391
392       See OSSL_PROVIDER-null(7).
393

USING ALGORITHMS IN APPLICATIONS

395       Cryptographic algorithms are made available to applications through use
396       of the "EVP" APIs. Each of the various operations such as encryption,
397       digesting, message authentication codes, etc., have a set of EVP
398       function calls that can be invoked to use them. See the evp(7) page for
399       further details.
400
401       Most of these follow a common pattern. A "context" object is first
402       created. For example for a digest operation you would use an
403       EVP_MD_CTX, and for an encryption/decryption operation you would use an
404       EVP_CIPHER_CTX. The operation is then initialised ready for use via an
405       "init" function - optionally passing in a set of parameters (using the
406       OSSL_PARAM(3) type) to configure how the operation should behave. Next
407       data is fed into the operation in a series of "update" calls. The
408       operation is finalised using a "final" call which will typically
409       provide some kind of output. Finally the context is cleaned up and
410       freed.
411
412       The following shows a complete example for doing this process for
413       digesting data using SHA256. The process is similar for other
414       operations such as encryption/decryption, signatures, message
415       authentication codes, etc.
416
417        #include <stdio.h>
418        #include <openssl/evp.h>
419        #include <openssl/bio.h>
420        #include <openssl/err.h>
421
422        int main(void)
423        {
424            EVP_MD_CTX *ctx = NULL;
425            EVP_MD *sha256 = NULL;
426            const unsigned char msg[] = {
427                0x00, 0x01, 0x02, 0x03
428            };
429            unsigned int len = 0;
430            unsigned char *outdigest = NULL;
431            int ret = 1;
432
433            /* Create a context for the digest operation */
434            ctx = EVP_MD_CTX_new();
435            if (ctx == NULL)
436                goto err;
437
438            /*
439             * Fetch the SHA256 algorithm implementation for doing the digest. We're
440             * using the "default" library context here (first NULL parameter), and
441             * we're not supplying any particular search criteria for our SHA256
442             * implementation (second NULL parameter). Any SHA256 implementation will
443             * do.
444             * In a larger application this fetch would just be done once, and could
445             * be used for multiple calls to other operations such as EVP_DigestInit_ex().
446             */
447            sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
448            if (sha256 == NULL)
449                goto err;
450
451           /* Initialise the digest operation */
452           if (!EVP_DigestInit_ex(ctx, sha256, NULL))
453               goto err;
454
455            /*
456             * Pass the message to be digested. This can be passed in over multiple
457             * EVP_DigestUpdate calls if necessary
458             */
459            if (!EVP_DigestUpdate(ctx, msg, sizeof(msg)))
460                goto err;
461
462            /* Allocate the output buffer */
463            outdigest = OPENSSL_malloc(EVP_MD_get_size(sha256));
464            if (outdigest == NULL)
465                goto err;
466
467            /* Now calculate the digest itself */
468            if (!EVP_DigestFinal_ex(ctx, outdigest, &len))
469                goto err;
470
471            /* Print out the digest result */
472            BIO_dump_fp(stdout, outdigest, len);
473
474            ret = 0;
475
476         err:
477            /* Clean up all the resources we allocated */
478            OPENSSL_free(outdigest);
479            EVP_MD_free(sha256);
480            EVP_MD_CTX_free(ctx);
481            if (ret != 0)
482               ERR_print_errors_fp(stderr);
483            return ret;
484        }
485

CONFIGURATION

487       By default OpenSSL will load a configuration file when it is first
488       used. This will set up various configuration settings within the
489       default library context.  Applications that create their own library
490       contexts may optionally configure them with a config file using the
491       OSSL_LIB_CTX_load_config(3) function.
492
493       The configuration file can be used to automatically load providers and
494       set up default property query strings.
495
496       For information on the OpenSSL configuration file format see config(5).
497

ENCODING AND DECODING KEYS

499       Many algorithms require the use of a key. Keys can be generated
500       dynamically using the EVP APIs (for example see EVP_PKEY_Q_keygen(3)).
501       However it is often necessary to save or load keys (or their associated
502       parameters) to or from some external format such as PEM or DER (see
503       openssl-glossary(7)). OpenSSL uses encoders and decoders to perform
504       this task.
505
506       Encoders and decoders are just algorithm implementations in the same
507       way as any other algorithm implementation in OpenSSL. They are
508       implemented by providers. The OpenSSL encoders and decoders are
509       available in the default provider. They are also duplicated in the base
510       provider.
511
512       For information about encoders see OSSL_ENCODER_CTX_new_for_pkey(3).
513       For information about decoders see OSSL_DECODER_CTX_new_for_pkey(3).
514

LIBRARY CONVENTIONS

516       Many OpenSSL functions that "get" or "set" a value follow a naming
517       convention using the numbers 0 and 1, i.e. "get0", "get1", "set0" and
518       "set1". This can also apply to some functions that "add" a value to an
519       existing set, i.e.  "add0" and "add1".
520
521       For example the functions:
522
523        int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev);
524        int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj);
525
526       In the 0 version the ownership of the object is passed to (for an add
527       or set) or retained by (for a get) the parent object. For example after
528       calling the X509_CRL_add0_revoked() function above, ownership of the
529       rev object is passed to the crl object. Therefore, after calling this
530       function rev should not be freed directly. It will be freed implicitly
531       when crl is freed.
532
533       In the 1 version the ownership of the object is not passed to or
534       retained by the parent object. Instead a copy or "up ref" of the object
535       is performed. So after calling the X509_add1_trust_object() function
536       above the application will still be responsible for freeing the obj
537       value where appropriate.
538

SEE ALSO

540       openssl(1), ssl(7), evp(7), OSSL_LIB_CTX(3), openssl-threads(7),
541       property(7), OSSL_PROVIDER-default(7), OSSL_PROVIDER-base(7),
542       OSSL_PROVIDER-FIPS(7), OSSL_PROVIDER-legacy(7), OSSL_PROVIDER-null(7),
543       openssl-glossary(7), provider(7)
544
546       Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.
547
548       Licensed under the Apache License 2.0 (the "License").  You may not use
549       this file except in compliance with the License.  You can obtain a copy
550       in the file LICENSE in the source distribution or at
551       <https://www.openssl.org/source/license.html>.
552
553
554
5553.0.9                             2023-07-27                     CRYPTO(7ossl)
Impressum