9db62e5aab1d8dd04ab85e44d98fe4b994d51827
[openssl.git] / doc / man7 / crypto.pod
1 =pod
2
3 =head1 NAME
4
5 crypto - OpenSSL cryptographic library
6
7 =head1 SYNOPSIS
8
9 See the individual manual pages for details.
10
11 =head1 DESCRIPTION
12
13 The OpenSSL crypto library (C<libcrypto>) implements a wide range of
14 cryptographic algorithms used in various Internet standards. The services
15 provided by this library are used by the OpenSSL implementations of TLS and
16 CMS, and they have also been used to implement many other third party products
17 and protocols.
18
19 The functionality includes symmetric encryption, public key cryptography, key
20 agreement, certificate handling, cryptographic hash functions, cryptographic
21 pseudo-random number generators, message authentication codes (MACs), key
22 derivation functions (KDFs), and various utilities.
23
24 =head2 Algorithms
25
26 Cryptographic primitives such as the SHA256 digest, or AES encryption are
27 referred to in OpenSSL as "algorithms". Each algorithm may have multiple
28 implementations available for use. For example the RSA algorithm is available as
29 a "default" implementation suitable for general use, and a "fips" implementation
30 which has been validated to FIPS standards for situations where that is
31 important. It is also possible that a third party could add additional
32 implementations such as in a hardware security module (HSM).
33
34 =head2 Operations
35
36 Different algorithms can be grouped together by their purpose. For example there
37 are algorithms for encryption, and different algorithms for digesting data.
38 These different groups are known as "operations" in OpenSSL. Each operation
39 has a different set of functions associated with it. For example to perform an
40 encryption operation using AES (or any other encryption algorithm) you would use
41 the encryption functions detailed on the L<EVP_EncryptInit(3)> page. Or to
42 perform a digest operation using SHA256 then you would use the digesting
43 functions on the L<EVP_DigestInit(3)> page.
44
45 =head2 Providers
46
47 A provider in OpenSSL is a component that collects together algorithm
48 implementations. In order to use an algorithm you must have at least one
49 provider loaded that contains an implementation of it. OpenSSL comes with a
50 number of providers and they may also be obtained from third parties. If you
51 don't load a provider explicitly (either in program code or via config) then the
52 OpenSSL built-in "default" provider will be automatically loaded.
53
54 =head2 Library contexts
55
56 A library context can be thought of as a "scope" within which configuration
57 options take effect. When a provider is loaded, it is only loaded within the
58 scope of a given library context. In this way it is possible for different
59 components of a complex application to each use a different library context and
60 have different providers loaded 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 B<OSSL_LIB_CTX> type. Many OpenSSL API
66 functions take a library context as a parameter. Applications can always pass
67 B<NULL> for this parameter to just use the default library context.
68
69 The default library context is automatically created the first time it is
70 needed. This will automatically load any available configuration file and will
71 initialise OpenSSL for use. Unlike in earlier versions of OpenSSL (prior to
72 1.1.0) no explicit initialisation steps need to be taken.
73
74 Similarly when the application exits the default library context is
75 automatically destroyed. No explicit de-initialisation steps need to be taken.
76
77 See L<OSSL_LIB_CTX(3)> for more information about library contexts.
78
79 =head2 Multi-threaded applications
80
81 As long as OpenSSL has been built with support for threads (the default case
82 on most platforms) then most OpenSSL I<functions> are thread-safe in the sense
83 that it is safe to call the same function from multiple threads at the same
84 time. However most OpenSSL I<data structures> are not thread-safe. For example
85 the L<BIO_write(3)> and L<BIO_read(3)> functions are thread safe. However it
86 would not be thread safe to call BIO_write() from one thread while calling
87 BIO_read() in another where both functions are passed the same B<BIO> object
88 since both of them may attempt to make changes to the same B<BIO> object.
89
90 There are exceptions to these rules. A small number of functions are not thread
91 safe at all. Where this is the case this restriction should be noted in the
92 documentation for the function. Similarly some data structures may be partially
93 or fully thread safe. For example it is safe to use an B<OSSL_LIB_CTX> in
94 multiple threads.
95
96 See L<openssl-threads(7)> for a more detailed discussion on OpenSSL threading
97 support.
98
99 =head1 ALGORITHM FETCHING
100
101 In order to use an algorithm an implementation for it must first be "fetched".
102 Fetching is the process of looking through the available implementations,
103 applying selection criteria (via a property query string), and finally choosing
104 the implementation that will be used.
105
106 Two types of fetching are supported by OpenSSL - explicit fetching and implicit
107 fetching.
108
109 =head2 Property query strings
110
111 When fetching an algorithm it is possible to specify a property query string to
112 guide the selection process. For example a property query string of
113 "provider=default" could be used to force the selection to only consider
114 algorithm implementations in the default provider.
115
116 Property query strings can be specified explicitly as an argument to a function.
117 It is also possible to specify a default property query string for the whole
118 library context using the L<EVP_set_default_properties(3)> function. Where both
119 default properties and function specific properties are specified then they are
120 combined. Function specific properties will override default properties where
121 there is a conflict.
122
123 See L<property(7)> for more information about properties.
124
125 =head2 Explicit fetching
126
127 Users of the OpenSSL libraries never query a provider directly for an algorithm
128 implementation. Instead, the diverse OpenSSL APIs often have explicit fetching
129 functions that do the work, and they return an appropriate algorithm object back
130 to the user. These functions usually have the name C<APINAME_fetch>, where
131 C<APINAME> is the name of the operation. For example L<EVP_MD_fetch(3)> can
132 be used to explicitly fetch a digest algorithm implementation. The user is
133 responsible for freeing the object returned from the C<APINAME_fetch> function
134 using C<APINAME_free> when it is no longer needed.
135
136 These fetching functions follow a fairly common pattern, where three
137 arguments are passed:
138
139 =over 4
140
141 =item The library context
142
143 See L<OSSL_LIB_CTX(3)> for a more detailed description.
144 This may be NULL to signify the default (global) library context, or a
145 context created by the user. Only providers loaded in this library context (see
146 L<OSSL_PROVIDER_load(3)>) will be considered by the fetching function. In case
147 no provider has been loaded in this library context then the default provider
148 will be loaded as a fallback (see L<OSSL_PROVIDER-default(7)>).
149
150 =item An identifier
151
152 For all currently implemented fetching functions this is the algorithm name.
153
154 =item A property query string
155
156 The property query string used to guide selection of the algorithm
157 implementation.
158
159 =back
160
161 The algorithm implementation that is fetched can then be used with other diverse
162 functions that use them. For example the L<EVP_DigestInit_ex(3)> function takes
163 as a parameter an B<EVP_MD> object which may have been returned from an earlier
164 call to L<EVP_MD_fetch(3)>.
165
166 =head2 Implicit fetch
167
168 OpenSSL has a number of functions that return an algorithm object with no
169 associated implementation, such as L<EVP_sha256(3)>,
170 L<EVP_blake2b512(3)> or L<EVP_aes_128_cbc(3)>. These are present for
171 compatibility with OpenSSL before version 3.0 where explicit fetching was not
172 available.
173
174 When they are used with functions like L<EVP_DigestInit_ex(3)> or
175 L<EVP_CipherInit_ex(3)>, the actual implementation to be used is
176 fetched implicitly using default search criteria.
177
178 In some cases implicit fetching can also occur when a NULL algorithm parameter
179 is supplied. In this case an algorithm implementation is implicitly fetched
180 using default search criteria and an algorithm name that is consistent with
181 the context in which it is being used.
182
183 =head1 FETCHING EXAMPLES
184
185 The following section provides a series of examples of fetching algorithm
186 implementations.
187
188 Fetch any available implementation of SHA2-256 in the default context. Note
189 that some algorithms have aliases. So "SHA256" and "SHA2-256" are synonymous:
190
191  EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", NULL);
192  ...
193  EVP_MD_free(md);
194
195 Fetch any available implementation of AES-128-CBC in the default context:
196
197  EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL);
198  ...
199  EVP_CIPHER_free(cipher);
200
201 Fetch an implementation of SHA2-256 from the default provider in the default
202 context:
203
204  EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");
205  ...
206  EVP_MD_free(md);
207
208 Fetch an implementation of SHA2-256 that is not from the default provider in the
209 default context:
210
211  EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider!=default");
212  ...
213  EVP_MD_free(md);
214
215 Fetch an implementation of SHA2-256 from the default provider in the specified
216 context:
217
218  EVP_MD *md = EVP_MD_fetch(ctx, "SHA2-256", "provider=default");
219  ...
220  EVP_MD_free(md);
221
222 Load the legacy provider into the default context and then fetch an
223 implementation of WHIRLPOOL from it:
224
225  /* This only needs to be done once - usually at application start up */
226  OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
227
228  EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy");
229  ...
230  EVP_MD_free(md);
231
232 Note that in the above example the property string "provider=legacy" is optional
233 since, assuming no other providers have been loaded, the only implementation of
234 the "whirlpool" algorithm is in the "legacy" provider. Also note that the
235 default provider should be explicitly loaded if it is required in addition to
236 other providers:
237
238  /* This only needs to be done once - usually at application start up */
239  OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
240  OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");
241
242  EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
243  EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
244  ...
245  EVP_MD_free(md_whirlpool);
246  EVP_MD_free(md_sha256);
247
248 =head1 OPENSSL PROVIDERS
249
250 OpenSSL comes with a set of providers.
251
252 The algorithms available in each of these providers may vary due to build time
253 configuration options. The L<openssl-list(1)> command can be used to list the
254 currently available algorithms.
255
256 The names of the algorithms shown from L<openssl-list(1)> can be used as an
257 algorithm identifier to the appropriate fetching function. Also see the provider
258 specific manual pages linked below for further details about using the
259 algorithms available in each of the providers.
260
261 As well as the OpenSSL providers third parties can also implemment providers.
262 For information on writing a provider see L<provider(7)>.
263
264 =head2 Default provider
265
266 The default provider is built in as part of the F<libcrypto> library and
267 contains all of the most commonly used algorithm implementations. Should it be
268 needed (if other providers are loaded and offer implementations of the same
269 algorithms), the property query string "provider=default" can be used as a
270 search criterion for these implementations.  The default provider includes all
271 of the functionality in the base provider below.
272
273 If you don't load any providers at all then the "default" provider will be
274 automatically loaded. If you explicitly load any provider then the "default"
275 provider would also need to be explicitly loaded if it is required.
276
277 See L<OSSL_PROVIDER-default(7)>.
278
279 =head2 Base provider
280
281 The base provider is built in as part of the F<libcrypto> library and contains
282 algorithm implementations for encoding and decoding for OpenSSL keys.
283 Should it be needed (if other providers are loaded and offer
284 implementations of the same algorithms), the property query string
285 "provider=base" can be used as a search criterion for these implementations.
286 Some encoding and decoding algorithm implementations are not FIPS algorithm
287 implementations in themselves but support algorithms from the FIPS provider and
288 are allowed for use in "FIPS mode". The property query string "fips=yes" can be
289 used to select such algorithms.
290
291 See L<OSSL_PROVIDER-base(7)>.
292
293 =head2 FIPS provider
294
295 The FIPS provider is a dynamically loadable module, and must therefore
296 be loaded explicitly, either in code or through OpenSSL configuration
297 (see L<config(5)>). It contains algorithm implementations that have been
298 validated according to the FIPS 140-2 standard. Should it be needed (if other
299 providers are loaded and offer implementations of the same algorithms), the
300 property query string "provider=fips" can be used as a search criterion for
301 these implementations. All approved algorithm implementations in the FIPS
302 provider can also be selected with the property "fips=yes". The FIPS provider
303 may also contain non-approved algorithm implementations and these can be
304 selected with the property "fips=no".
305
306 See L<OSSL_PROVIDER-FIPS(7)>.
307
308 =head2 Legacy provider
309
310 The legacy provider is a dynamically loadable module, and must therefore
311 be loaded explicitly, either in code or through OpenSSL configuration
312 (see L<config(5)>). It contains algorithm implementations that are considered
313 insecure, or are no longer in common use such as MD2 or RC4. Should it be needed
314 (if other providers are loaded and offer implementations of the same algorithms),
315 the property "provider=legacy" can be used as a search criterion for these
316 implementations.
317
318 See L<OSSL_PROVIDER-legacy(7)>.
319
320 =head2 Null provider
321
322 The null provider is built in as part of the F<libcrypto> library. It contains
323 no algorithms in it at all. When fetching algorithms the default provider will
324 be automatically loaded if no other provider has been explicitly loaded. To
325 prevent that from happening you can explicitly load the null provider.
326
327 See L<OSSL_PROVIDER-null(7)>.
328
329 =head1 USING ALGORITHMS IN APPLICATIONS
330
331 Cryptographic algorithms are made available to applications through use of the
332 "EVP" APIs. Each of the various operations such as encryption, digesting,
333 message authentication codes, etc., have a set of EVP function calls that can
334 be invoked to use them. See the L<evp(7)> page for further details.
335
336 Most of these follow a common pattern. A "context" object is first created. For
337 example for a digest operation you would use an B<EVP_MD_CTX>, and for an
338 encryption/decryption operation you would use an B<EVP_CIPHER_CTX>. The
339 operation is then initialised ready for use via an "init" function - optionally
340 passing in a set of parameters (using the B<OSSL_PARAM> type) to configure how
341 the operation should behave. Next data is fed into the operation in a series of
342 "update" calls. The operation is finalised using a "final" call which will
343 typically provide some kind of output. Finally the context is cleaned up and
344 freed.
345
346 The following shows a complete example for doing this process for digesting
347 data using SHA256. The process is similar for other operations such as
348 encryption/decryption, signatures, message authentication codes, etc.
349
350  #include <stdio.h>
351  #include <openssl/evp.h>
352  #include <openssl/bio.h>
353
354  int main(void)
355  {
356      EVP_MD_CTX *ctx = NULL;
357      EVP_MD *sha256 = NULL;
358      const unsigned char msg[] = {
359          0x00, 0x01, 0x02, 0x03
360      };
361      unsigned int len = 0;
362      unsigned char *outdigest = NULL;
363
364      /* Create a context for the digest operation */
365      ctx = EVP_MD_CTX_new();
366      if (ctx == NULL)
367          goto err;
368
369      /*
370       * Fetch the SHA256 algorithm implementation for doing the digest. We're
371       * using the "default" library context here (first NULL parameter), and
372       * we're not supplying any particular search criteria for our SHA256
373       * implementation (second NULL parameter). Any SHA256 implementation will
374       * do.
375       */
376      sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
377      if (sha256 == NULL)
378          goto err;
379
380     /* Initialise the digest operation */
381     if (!EVP_DigestInit_ex(ctx, sha256, NULL))
382         goto err;
383
384      /*
385       * Pass the message to be digested. This can be passed in over multiple
386       * EVP_DigestUpdate calls if necessary
387       */
388      if (!EVP_DigestUpdate(ctx, msg, sizeof(msg)))
389          goto err;
390
391      /* Allocate the output buffer */
392      outdigest = OPENSSL_malloc(EVP_MD_size(sha256));
393      if (outdigest == NULL)
394          goto err;
395
396      /* Now calculate the digest itself */
397      if (!EVP_DigestFinal_ex(ctx, outdigest, &len))
398          goto err;
399
400      /* Print out the digest result */
401      BIO_dump_fp(stdout, outdigest, len);
402
403   err:
404      /* Clean up all the resources we allocated */
405      OPENSSL_free(outdigest);
406      EVP_MD_free(sha256);
407      EVP_MD_CTX_free(ctx);
408  }
409
410 =head1 CONFIGURATION
411
412 By default OpenSSL will load a configuration file when it is first used. This
413 will set up various configuration settings within the default library context.
414 Applications that create their own library contexts may optionally configure
415 them with a config file using the L<OSSL_LIB_CTX_load_config(3)> function.
416
417 The configuration file can be used to automatically load providers and set up
418 default property query strings.
419
420 For information on the OpenSSL configuration file format see L<config(5)>.
421
422 =head1 ENCODING AND DECODING KEYS
423
424 Many algorithms require the use of a key. Keys can be generated dynamically
425 using the EVP APIs (for example see L<EVP_PKEY_Q_keygen(3)>). However it is often
426 necessary to save or load keys (or their associated parameters) to or from some
427 external format such as PEM or DER (see L<openssl-glossary(7)>). OpenSSL uses
428 encoders and decoders to perform this task.
429
430 Encoders and decoders are just algorithm implementations in the same way as
431 any other algorithm implementation in OpenSSL. They are implemented by
432 providers. The OpenSSL encoders and decoders are available in the default
433 provider. They are also duplicated in the base provider.
434
435 For information about encoders see L<OSSL_ENCODER_CTX_new_for_pkey(3)>. For
436 information about decoders see L<OSSL_DECODER_CTX_new_for_pkey(3)>.
437
438 =head1 LIBRARY CONVENTIONS
439
440 Many OpenSSL functions that "get" or "set" a value follow a naming convention
441 using the numbers B<0> and B<1>, i.e. "get0", "get1", "set0" and "set1". This
442 can also apply to some functions that "add" a value to an existing set, i.e.
443 "add0" and "add1".
444
445 For example the functions:
446
447  int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev);
448  int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj);
449
450 In the B<0> version the ownership of the object is passed to (for an add or set)
451 or retained by (for a get) the parent object. For example after calling the
452 X509_CRL_add0_revoked() function above, ownership of the I<rev> object is passed
453 to the I<crl> object. Therefore, after calling this function I<rev> should not
454 be freed directly. It will be freed implicitly when I<crl> is freed.
455
456 In the B<1> version the ownership of the object is not passed to or retained by
457 the parent object. Instead a copy or "up ref" of the object is performed. So
458 after calling the X509_add1_trust_object() function above the application will
459 still be responsible for freeing the I<obj> value where appropriate.
460
461 =head1 SEE ALSO
462
463 L<openssl(1)>, L<ssl(7)>, L<evp(7)>, L<OSSL_LIB_CTX(3)>, L<openssl-threads(7)>,
464 L<property(7)>, L<OSSL_PROVIDER-default(7)>, L<OSSL_PROVIDER-base(7)>,
465 L<OSSL_PROVIDER-FIPS(7)>, L<OSSL_PROVIDER-legacy(7)>, L<OSSL_PROVIDER-null(7)>,
466 L<openssl-glossary(7)>, L<provider(7)>
467
468 =head1 COPYRIGHT
469
470 Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
471
472 Licensed under the Apache License 2.0 (the "License").  You may not use
473 this file except in compliance with the License.  You can obtain a copy
474 in the file LICENSE in the source distribution or at
475 L<https://www.openssl.org/source/license.html>.
476
477 =cut