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) function. Where both default properties
122 and function specific properties are specified then they are combined.
123 Function specific properties will override default properties where
124 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 fetch
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
204 The following section provides a series of examples of fetching
205 algorithm implementations.
206 Fetch any available implementation of SHA2-256 in the default context.
208 Note that some algorithms have aliases. So "SHA256" and "SHA2-256" are
209 synonymous:
210 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", NULL);
212 ...
213 EVP_MD_free(md);
214 Fetch any available implementation of AES-128-CBC in the default
216 context:
217 EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL);
219 ...
220 EVP_CIPHER_free(cipher);
221 Fetch an implementation of SHA2-256 from the default provider in the
223 default context:
224 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");
226 ...
227 EVP_MD_free(md);
228 Fetch an implementation of SHA2-256 that is not from the default
230 provider in the default context:
231 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider!=default");
233 ...
234 EVP_MD_free(md);
235 Fetch an implementation of SHA2-256 from the default provider in the
237 specified context:
238 EVP_MD *md = EVP_MD_fetch(ctx, "SHA2-256", "provider=default");
240 ...
241 EVP_MD_free(md);
242 Load the legacy provider into the default context and then fetch an
244 implementation of WHIRLPOOL from it:
245 /* This only needs to be done once - usually at application start up */
247 OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
248 EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy");
250 ...
251 EVP_MD_free(md);
252 Note that in the above example the property string "provider=legacy" is
254 optional since, assuming no other providers have been loaded, the only
255 implementation of the "whirlpool" algorithm is in the "legacy"
256 provider. Also note that the default provider should be explicitly
257 loaded if it is required in addition to other providers:
258 /* This only needs to be done once - usually at application start up */
260 OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
261 OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");
262 EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
264 EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
265 ...
266 EVP_MD_free(md_whirlpool);
267 EVP_MD_free(md_sha256);
268
270 OpenSSL comes with a set of providers.
271 The algorithms available in each of these providers may vary due to
273 build time configuration options. The openssl-list(1) command can be
274 used to list the currently available algorithms.
275 The names of the algorithms shown from openssl-list(1) can be used as
277 an algorithm identifier to the appropriate fetching function. Also see
278 the provider specific manual pages linked below for further details
279 about using the algorithms available in each of the providers.
280 As well as the OpenSSL providers third parties can also implement
282 providers. For information on writing a provider see provider(7).
283 Default provider
285 The default provider is built in as part of the libcrypto library and
286 contains all of the most commonly used algorithm implementations.
287 Should it be needed (if other providers are loaded and offer
288 implementations of the same algorithms), the property query string
289 "provider=default" can be used as a search criterion for these
290 implementations. The default provider includes all of the
291 functionality in the base provider below.
292 If you don't load any providers at all then the "default" provider will
294 be automatically loaded. If you explicitly load any provider then the
295 "default" provider would also need to be explicitly loaded if it is
296 required.
297 See OSSL_PROVIDER-default(7).
299 Base provider
301 The base provider is built in as part of the libcrypto library and
302 contains algorithm implementations for encoding and decoding for
303 OpenSSL keys. Should it be needed (if other providers are loaded and
304 offer implementations of the same algorithms), the property query
305 string "provider=base" can be used as a search criterion for these
306 implementations. Some encoding and decoding algorithm implementations
307 are not FIPS algorithm implementations in themselves but support
308 algorithms from the FIPS provider and are allowed for use in "FIPS
309 mode". The property query string "fips=yes" can be used to select such
310 algorithms.
311 See OSSL_PROVIDER-base(7).
313 FIPS provider
315 The FIPS provider is a dynamically loadable module, and must therefore
316 be loaded explicitly, either in code or through OpenSSL configuration
317 (see config(5)). It contains algorithm implementations that have been
318 validated according to the FIPS 140-2 standard. Should it be needed (if
319 other providers are loaded and offer implementations of the same
320 algorithms), the property query string "provider=fips" can be used as a
321 search criterion for these implementations. All approved algorithm
322 implementations in the FIPS provider can also be selected with the
323 property "fips=yes". The FIPS provider may also contain non-approved
324 algorithm implementations and these can be selected with the property
325 "fips=no".
326 See OSSL_PROVIDER-FIPS(7) and fips_module(7).
328 Legacy provider
330 The legacy provider is a dynamically loadable module, and must
331 therefore be loaded explicitly, either in code or through OpenSSL
332 configuration (see config(5)). It contains algorithm implementations
333 that are considered insecure, or are no longer in common use such as
334 MD2 or RC4. Should it be needed (if other providers are loaded and
335 offer implementations of the same algorithms), the property
336 "provider=legacy" can be used as a search criterion for these
337 implementations.
338 See OSSL_PROVIDER-legacy(7).
340 Null provider
342 The null provider is built in as part of the libcrypto library. It
343 contains no algorithms in it at all. When fetching algorithms the
344 default provider will be automatically loaded if no other provider has
345 been explicitly loaded. To prevent that from happening you can
346 explicitly load the null provider.
347 See OSSL_PROVIDER-null(7).
349
351 Cryptographic algorithms are made available to applications through use
352 of the "EVP" APIs. Each of the various operations such as encryption,
353 digesting, message authentication codes, etc., have a set of EVP
354 function calls that can be invoked to use them. See the evp(7) page for
355 further details.
356 Most of these follow a common pattern. A "context" object is first
358 created. For example for a digest operation you would use an
359 EVP_MD_CTX, and for an encryption/decryption operation you would use an
360 EVP_CIPHER_CTX. The operation is then initialised ready for use via an
361 "init" function - optionally passing in a set of parameters (using the
362 OSSL_PARAM type) to configure how the operation should behave. Next
363 data is fed into the operation in a series of "update" calls. The
364 operation is finalised using a "final" call which will typically
365 provide some kind of output. Finally the context is cleaned up and
366 freed.
367 The following shows a complete example for doing this process for
369 digesting data using SHA256. The process is similar for other
370 operations such as encryption/decryption, signatures, message
371 authentication codes, etc.
372 #include <stdio.h>
374 #include <openssl/evp.h>
375 #include <openssl/bio.h>
376 #include <openssl/err.h>
377 int main(void)
379 {
380 EVP_MD_CTX *ctx = NULL;
381 EVP_MD *sha256 = NULL;
382 const unsigned char msg[] = {
383 0x00, 0x01, 0x02, 0x03
384 };
385 unsigned int len = 0;
386 unsigned char *outdigest = NULL;
387 int ret = 1;
388 /* Create a context for the digest operation */
390 ctx = EVP_MD_CTX_new();
391 if (ctx == NULL)
392 goto err;
393 /*
395 * Fetch the SHA256 algorithm implementation for doing the digest. We're
396 * using the "default" library context here (first NULL parameter), and
397 * we're not supplying any particular search criteria for our SHA256
398 * implementation (second NULL parameter). Any SHA256 implementation will
399 * do.
400 */
401 sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
402 if (sha256 == NULL)
403 goto err;
404 /* Initialise the digest operation */
406 if (!EVP_DigestInit_ex(ctx, sha256, NULL))
407 goto err;
408 /*
410 * Pass the message to be digested. This can be passed in over multiple
411 * EVP_DigestUpdate calls if necessary
412 */
413 if (!EVP_DigestUpdate(ctx, msg, sizeof(msg)))
414 goto err;
415 /* Allocate the output buffer */
417 outdigest = OPENSSL_malloc(EVP_MD_get_size(sha256));
418 if (outdigest == NULL)
419 goto err;
420 /* Now calculate the digest itself */
422 if (!EVP_DigestFinal_ex(ctx, outdigest, &len))
423 goto err;
424 /* Print out the digest result */
426 BIO_dump_fp(stdout, outdigest, len);
427 ret = 0;
429 err:
431 /* Clean up all the resources we allocated */
432 OPENSSL_free(outdigest);
433 EVP_MD_free(sha256);
434 EVP_MD_CTX_free(ctx);
435 if (ret != 0)
436 ERR_print_errors_fp(stderr);
437 return ret;
438 }
439
441 By default OpenSSL will load a configuration file when it is first
442 used. This will set up various configuration settings within the
443 default library context. Applications that create their own library
444 contexts may optionally configure them with a config file using the
445 OSSL_LIB_CTX_load_config(3) function.
446 The configuration file can be used to automatically load providers and
448 set up default property query strings.
449 For information on the OpenSSL configuration file format see config(5).
451
453 Many algorithms require the use of a key. Keys can be generated
454 dynamically using the EVP APIs (for example see EVP_PKEY_Q_keygen(3)).
455 However it is often necessary to save or load keys (or their associated
456 parameters) to or from some external format such as PEM or DER (see
457 openssl-glossary(7)). OpenSSL uses encoders and decoders to perform
458 this task.
459 Encoders and decoders are just algorithm implementations in the same
461 way as any other algorithm implementation in OpenSSL. They are
462 implemented by providers. The OpenSSL encoders and decoders are
463 available in the default provider. They are also duplicated in the base
464 provider.
465 For information about encoders see OSSL_ENCODER_CTX_new_for_pkey(3).
467 For information about decoders see OSSL_DECODER_CTX_new_for_pkey(3).
468
470 Many OpenSSL functions that "get" or "set" a value follow a naming
471 convention using the numbers 0 and 1, i.e. "get0", "get1", "set0" and
472 "set1". This can also apply to some functions that "add" a value to an
473 existing set, i.e. "add0" and "add1".
474 For example the functions:
476 int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev);
478 int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj);
479 In the 0 version the ownership of the object is passed to (for an add
481 or set) or retained by (for a get) the parent object. For example after
482 calling the X509_CRL_add0_revoked() function above, ownership of the
483 rev object is passed to the crl object. Therefore, after calling this
484 function rev should not be freed directly. It will be freed implicitly
485 when crl is freed.
486 In the 1 version the ownership of the object is not passed to or
488 retained by the parent object. Instead a copy or "up ref" of the object
489 is performed. So after calling the X509_add1_trust_object() function
490 above the application will still be responsible for freeing the obj
491 value where appropriate.
492
494 openssl(1), ssl(7), evp(7), OSSL_LIB_CTX(3), openssl-threads(7),
495 property(7), OSSL_PROVIDER-default(7), OSSL_PROVIDER-base(7),
496 OSSL_PROVIDER-FIPS(7), OSSL_PROVIDER-legacy(7), OSSL_PROVIDER-null(7),
497 openssl-glossary(7), provider(7)
498
500 Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.
501 Licensed under the Apache License 2.0 (the "License"). You may not use
503 this file except in compliance with the License. You can obtain a copy
504 in the file LICENSE in the source distribution or at
505 <https://www.openssl.org/source/license.html>.
5063.0.5 2022-11-01 CRYPTO(7ossl)