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