1CRYPTO(7ossl) OpenSSL CRYPTO(7ossl)
2
6 crypto - OpenSSL cryptographic library
7
9 See the individual manual pages for details.
10
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 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 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 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 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 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 If an application does not explicitly create a library context then the
63 "default" library context will be used.
64 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 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 Similarly when the application exits the default library context is
77 automatically destroyed. No explicit de-initialisation steps need to be
78 taken.
79 See OSSL_LIB_CTX(3) for more information about library contexts. See
81 also "ALGORITHM FETCHING".
82 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 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 See openssl-threads(7) for a more detailed discussion on OpenSSL
101 threading support.
102
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 Two types of fetching are supported by OpenSSL - explicit fetching and
110 implicit fetching.
111 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 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 See property(7) for more information about properties.
127 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 These fetching functions follow a fairly common pattern, where three
140 arguments are passed:
141 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 An identifier
152 For all currently implemented fetching functions this is the
153 algorithm name.
154 A property query string
156 The property query string used to guide selection of the algorithm
157 implementation.
158 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 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 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 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 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 1. Fetch the operation type implementation from any provider given a
187 library context and property string stored in the EVP_PKEY_CTX.
188 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 If anything in this step fails, the next step is used as a
197 fallback.
198 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 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 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 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 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 The following methods can be used for prefetching:
226 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 The following methods are used internally when performing operations:
237 EVP_KEYMGMT_fetch(3)
239 EVP_KEYEXCH_fetch(3)
240 EVP_SIGNATURE_fetch(3)
241 OSSL_STORE_LOADER_fetch(3)
242 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
248 The following section provides a series of examples of fetching
249 algorithm implementations.
250 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 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", NULL);
256 ...
257 EVP_MD_free(md);
258 Fetch any available implementation of AES-128-CBC in the default
260 context:
261 EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL);
263 ...
264 EVP_CIPHER_free(cipher);
265 Fetch an implementation of SHA2-256 from the default provider in the
267 default context:
268 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");
270 ...
271 EVP_MD_free(md);
272 Fetch an implementation of SHA2-256 that is not from the default
274 provider in the default context:
275 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider!=default");
277 ...
278 EVP_MD_free(md);
279 Fetch an implementation of SHA2-256 from the default provider in the
281 specified context:
282 EVP_MD *md = EVP_MD_fetch(ctx, "SHA2-256", "provider=default");
284 ...
285 EVP_MD_free(md);
286 Load the legacy provider into the default context and then fetch an
288 implementation of WHIRLPOOL from it:
289 /* This only needs to be done once - usually at application start up */
291 OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
292 EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy");
294 ...
295 EVP_MD_free(md);
296 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 /* 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 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
314 OpenSSL comes with a set of providers.
315 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 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 As well as the OpenSSL providers third parties can also implement
326 providers. For information on writing a provider see provider(7).
327 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 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 See OSSL_PROVIDER-default(7).
343 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 See OSSL_PROVIDER-base(7).
357 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 See OSSL_PROVIDER-FIPS(7) and fips_module(7).
372 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 See OSSL_PROVIDER-legacy(7).
384 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 See OSSL_PROVIDER-null(7).
393
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 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 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 #include <stdio.h>
418 #include <openssl/evp.h>
419 #include <openssl/bio.h>
420 #include <openssl/err.h>
421 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 /* Create a context for the digest operation */
434 ctx = EVP_MD_CTX_new();
435 if (ctx == NULL)
436 goto err;
437 /*
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 /* Initialise the digest operation */
452 if (!EVP_DigestInit_ex(ctx, sha256, NULL))
453 goto err;
454 /*
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 /* Allocate the output buffer */
463 outdigest = OPENSSL_malloc(EVP_MD_get_size(sha256));
464 if (outdigest == NULL)
465 goto err;
466 /* Now calculate the digest itself */
468 if (!EVP_DigestFinal_ex(ctx, outdigest, &len))
469 goto err;
470 /* Print out the digest result */
472 BIO_dump_fp(stdout, outdigest, len);
473 ret = 0;
475 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
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 The configuration file can be used to automatically load providers and
494 set up default property query strings.
495 For information on the OpenSSL configuration file format see config(5).
497
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 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 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
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 For example the functions:
522 int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev);
524 int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj);
525 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 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
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 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>.
5523.0.9 2023-07-27 CRYPTO(7ossl)