5 ossl-guide-libcrypto-introduction, crypto
6 - OpenSSL Guide: An introduction to libcrypto
11 The OpenSSL cryptography library (C<libcrypto>) enables access to a wide range
12 of cryptographic algorithms used in various Internet standards. The services
13 provided by this library are used by the OpenSSL implementations of TLS and
14 CMS, and they have also been used to implement many other third party products
17 The functionality includes symmetric encryption, public key cryptography, key
18 agreement, certificate handling, cryptographic hash functions, cryptographic
19 pseudo-random number generators, message authentication codes (MACs), key
20 derivation functions (KDFs), and various utilities.
24 Cryptographic primitives such as the SHA256 digest, or AES encryption are
25 referred to in OpenSSL as "algorithms". Each algorithm may have multiple
26 implementations available for use. For example the RSA algorithm is available as
27 a "default" implementation suitable for general use, and a "fips" implementation
28 which has been validated to FIPS 140 standards for situations where that is
29 important. It is also possible that a third party could add additional
30 implementations such as in a hardware security module (HSM).
32 Algorithms are implemented in providers. See
33 L<ossl-guide-libraries-introduction(7)> for information about providers.
37 Different algorithms can be grouped together by their purpose. For example there
38 are algorithms for encryption, and different algorithms for digesting data.
39 These different groups are known as "operations" in OpenSSL. Each operation
40 has a different set of functions associated with it. For example to perform an
41 encryption operation using AES (or any other encryption algorithm) you would use
42 the encryption functions detailed on the L<EVP_EncryptInit(3)> page. Or to
43 perform a digest operation using SHA256 then you would use the digesting
44 functions on the L<EVP_DigestInit(3)> page.
46 =head1 ALGORITHM FETCHING
48 In order to use an algorithm an implementation for it must first be "fetched".
49 Fetching is the process of looking through the available implementations,
50 applying selection criteria (via a property query string), and finally choosing
51 the implementation that will be used.
53 Two types of fetching are supported by OpenSSL - L</Explicit fetching> and
54 L</Implicit fetching>.
56 =head2 Explicit fetching
58 Explicit fetching involves directly calling a specific API to fetch an algorithm
59 implementation from a provider. This fetched object can then be passed to other
60 APIs. These explicit fetching functions usually have the name C<APINAME_fetch>,
61 where C<APINAME> is the name of the operation. For example L<EVP_MD_fetch(3)>
62 can be used to explicitly fetch a digest algorithm implementation. The user is
63 responsible for freeing the object returned from the C<APINAME_fetch> function
64 using C<APINAME_free> when it is no longer needed.
66 These fetching functions follow a fairly common pattern, where three
71 =item The library context
73 See L<OSSL_LIB_CTX(3)> for a more detailed description.
74 This may be NULL to signify the default (global) library context, or a
75 context created by the user. Only providers loaded in this library context (see
76 L<OSSL_PROVIDER_load(3)>) will be considered by the fetching function. In case
77 no provider has been loaded in this library context then the default provider
78 will be loaded as a fallback (see L<OSSL_PROVIDER-default(7)>).
82 For all currently implemented fetching functions this is the algorithm name.
83 Each provider supports a list of algorithm implementations. See the provider
84 specific documentation for information on the algorithm implementations
85 available in each provider:
86 L<OSSL_PROVIDER-default(7)/OPERATIONS AND ALGORITHMS>,
87 L<OSSL_PROVIDER-FIPS(7)/OPERATIONS AND ALGORITHMS>,
88 L<OSSL_PROVIDER-legacy(7)/OPERATIONS AND ALGORITHMS> and
89 L<OSSL_PROVIDER-base(7)/OPERATIONS AND ALGORITHMS>.
91 Note, while providers may register algorithms against a list of names using a
92 string with a colon separated list of names, fetching algorithms using that
93 format is currently unsupported.
95 =item A property query string
97 The property query string used to guide selection of the algorithm
99 L<ossl-guide-libraries-introduction(7)/PROPERTY QUERY STRINGS>.
103 The algorithm implementation that is fetched can then be used with other diverse
104 functions that use them. For example the L<EVP_DigestInit_ex(3)> function takes
105 as a parameter an B<EVP_MD> object which may have been returned from an earlier
106 call to L<EVP_MD_fetch(3)>.
108 =head2 Implicit fetching
110 OpenSSL has a number of functions that return an algorithm object with no
111 associated implementation, such as L<EVP_sha256(3)>, L<EVP_aes_128_cbc(3)>,
112 L<EVP_get_cipherbyname(3)> or L<EVP_get_digestbyname(3)>. These are present for
113 compatibility with OpenSSL before version 3.0 where explicit fetching was not
116 When they are used with functions like L<EVP_DigestInit_ex(3)> or
117 L<EVP_CipherInit_ex(3)>, the actual implementation to be used is
118 fetched implicitly using default search criteria (which uses NULL for the
119 library context and property query string).
121 In some cases implicit fetching can also occur when a NULL algorithm parameter
122 is supplied. In this case an algorithm implementation is implicitly fetched
123 using default search criteria and an algorithm name that is consistent with
124 the context in which it is being used.
126 Functions that use an B<EVP_PKEY_CTX> or an L<EVP_PKEY(3)>, such as
127 L<EVP_DigestSignInit(3)>, all fetch the implementations implicitly. Usually the
128 algorithm to fetch is determined based on the type of key that is being used and
129 the function that has been called.
133 If you perform the same operation many times with the same algorithm then it is
134 recommended to use a single explicit fetch of the algorithm and then reuse the
135 explicitly fetched algorithm each subsequent time. This will typically be
136 faster than implicitly fetching the algorithm every time you use it. See an
137 example of Explicit fetching in L</USING ALGORITHMS IN APPLICATIONS>.
139 Prior to OpenSSL 3.0, functions such as EVP_sha256() which return a "const"
140 object were used directly to indicate the algorithm to use in various function
141 calls. If you pass the return value of one of these convenience functions to an
142 operation then you are using implicit fetching. If you are converting an
143 application that worked with an OpenSSL version prior to OpenSSL 3.0 then
144 consider changing instances of implicit fetching to explicit fetching instead.
146 If an explicitly fetched object is not passed to an operation, then any implicit
147 fetch will use an internally cached prefetched object, but it will
148 still be slower than passing the explicitly fetched object directly.
150 The following functions can be used for explicit fetching:
154 =item L<EVP_MD_fetch(3)>
156 Fetch a message digest/hashing algorithm implementation.
158 =item L<EVP_CIPHER_fetch(3)>
160 Fetch a symmetric cipher algorithm implementation.
162 =item L<EVP_KDF_fetch(3)>
164 Fetch a Key Derivation Function (KDF) algorithm implementation.
166 =item L<EVP_MAC_fetch(3)>
168 Fetch a Message Authentication Code (MAC) algorithm implementation.
170 =item L<EVP_KEM_fetch(3)>
172 Fetch a Key Encapsulation Mechanism (KEM) algorithm implementation
174 =item L<OSSL_ENCODER_fetch(3)>
176 Fetch an encoder algorithm implementation (e.g. to encode keys to a specified
179 =item L<OSSL_DECODER_fetch(3)>
181 Fetch a decoder algorithm implementation (e.g. to decode keys from a specified
184 =item L<EVP_RAND_fetch(3)>
186 Fetch a Pseudo Random Number Generator (PRNG) algorithm implementation.
190 See L<OSSL_PROVIDER-default(7)/OPERATIONS AND ALGORITHMS>,
191 L<OSSL_PROVIDER-FIPS(7)/OPERATIONS AND ALGORITHMS>,
192 L<OSSL_PROVIDER-legacy(7)/OPERATIONS AND ALGORITHMS> and
193 L<OSSL_PROVIDER-base(7)/OPERATIONS AND ALGORITHMS> for a list of algorithm names
196 =head1 FETCHING EXAMPLES
198 The following section provides a series of examples of fetching algorithm
201 Fetch any available implementation of SHA2-256 in the default context. Note
202 that some algorithms have aliases. So "SHA256" and "SHA2-256" are synonymous:
204 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", NULL);
208 Fetch any available implementation of AES-128-CBC in the default context:
210 EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL);
212 EVP_CIPHER_free(cipher);
214 Fetch an implementation of SHA2-256 from the default provider in the default
217 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");
221 Fetch an implementation of SHA2-256 that is not from the default provider in the
224 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider!=default");
228 Fetch an implementation of SHA2-256 that is preferably from the FIPS provider in
231 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider=?fips");
235 Fetch an implementation of SHA2-256 from the default provider in the specified
238 EVP_MD *md = EVP_MD_fetch(libctx, "SHA2-256", "provider=default");
242 Load the legacy provider into the default context and then fetch an
243 implementation of WHIRLPOOL from it:
245 /* This only needs to be done once - usually at application start up */
246 OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
248 EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy");
252 Note that in the above example the property string "provider=legacy" is optional
253 since, assuming no other providers have been loaded, the only implementation of
254 the "whirlpool" algorithm is in the "legacy" provider. Also note that the
255 default provider should be explicitly loaded if it is required in addition to
258 /* This only needs to be done once - usually at application start up */
259 OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
260 OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");
262 EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
263 EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
265 EVP_MD_free(md_whirlpool);
266 EVP_MD_free(md_sha256);
269 =head1 USING ALGORITHMS IN APPLICATIONS
271 Cryptographic algorithms are made available to applications through use of the
272 "EVP" APIs. Each of the various operations such as encryption, digesting,
273 message authentication codes, etc., have a set of EVP function calls that can
274 be invoked to use them. See the L<evp(7)> page for further details.
276 Most of these follow a common pattern. A "context" object is first created. For
277 example for a digest operation you would use an B<EVP_MD_CTX>, and for an
278 encryption/decryption operation you would use an B<EVP_CIPHER_CTX>. The
279 operation is then initialised ready for use via an "init" function - optionally
280 passing in a set of parameters (using the L<OSSL_PARAM(3)> type) to configure how
281 the operation should behave. Next data is fed into the operation in a series of
282 "update" calls. The operation is finalised using a "final" call which will
283 typically provide some kind of output. Finally the context is cleaned up and
286 The following shows a complete example for doing this process for digesting
287 data using SHA256. The process is similar for other operations such as
288 encryption/decryption, signatures, message authentication codes, etc. Additional
289 examples can be found in the OpenSSL demos (see
290 L<ossl-guide-libraries-introduction(7)/DEMO APPLICATIONS>).
293 #include <openssl/evp.h>
294 #include <openssl/bio.h>
295 #include <openssl/err.h>
299 EVP_MD_CTX *ctx = NULL;
300 EVP_MD *sha256 = NULL;
301 const unsigned char msg[] = {
302 0x00, 0x01, 0x02, 0x03
304 unsigned int len = 0;
305 unsigned char *outdigest = NULL;
308 /* Create a context for the digest operation */
309 ctx = EVP_MD_CTX_new();
314 * Fetch the SHA256 algorithm implementation for doing the digest. We're
315 * using the "default" library context here (first NULL parameter), and
316 * we're not supplying any particular search criteria for our SHA256
317 * implementation (second NULL parameter). Any SHA256 implementation will
319 * In a larger application this fetch would just be done once, and could
320 * be used for multiple calls to other operations such as EVP_DigestInit_ex().
322 sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
326 /* Initialise the digest operation */
327 if (!EVP_DigestInit_ex(ctx, sha256, NULL))
331 * Pass the message to be digested. This can be passed in over multiple
332 * EVP_DigestUpdate calls if necessary
334 if (!EVP_DigestUpdate(ctx, msg, sizeof(msg)))
337 /* Allocate the output buffer */
338 outdigest = OPENSSL_malloc(EVP_MD_get_size(sha256));
339 if (outdigest == NULL)
342 /* Now calculate the digest itself */
343 if (!EVP_DigestFinal_ex(ctx, outdigest, &len))
346 /* Print out the digest result */
347 BIO_dump_fp(stdout, outdigest, len);
352 /* Clean up all the resources we allocated */
353 OPENSSL_free(outdigest);
355 EVP_MD_CTX_free(ctx);
357 ERR_print_errors_fp(stderr);
361 =head1 ENCODING AND DECODING KEYS
363 Many algorithms require the use of a key. Keys can be generated dynamically
364 using the EVP APIs (for example see L<EVP_PKEY_Q_keygen(3)>). However it is often
365 necessary to save or load keys (or their associated parameters) to or from some
366 external format such as PEM or DER (see L<openssl-glossary(7)>). OpenSSL uses
367 encoders and decoders to perform this task.
369 Encoders and decoders are just algorithm implementations in the same way as
370 any other algorithm implementation in OpenSSL. They are implemented by
371 providers. The OpenSSL encoders and decoders are available in the default
372 provider. They are also duplicated in the base provider.
374 For information about encoders see L<OSSL_ENCODER_CTX_new_for_pkey(3)>. For
375 information about decoders see L<OSSL_DECODER_CTX_new_for_pkey(3)>.
377 As well as using encoders/decoders directly there are also some helper functions
378 that can be used for certain well known and commonly used formats. For example
379 see L<PEM_read_PrivateKey(3)> and L<PEM_write_PrivateKey(3)> for information
380 about reading and writing key data from PEM encoded files.
382 =head1 FURTHER READING
384 See L<ossl-guide-libssl-introduction(7)> for an introduction to using C<libssl>.
388 L<openssl(1)>, L<ssl(7)>, L<evp(7)>, L<OSSL_LIB_CTX(3)>, L<openssl-threads(7)>,
389 L<property(7)>, L<OSSL_PROVIDER-default(7)>, L<OSSL_PROVIDER-base(7)>,
390 L<OSSL_PROVIDER-FIPS(7)>, L<OSSL_PROVIDER-legacy(7)>, L<OSSL_PROVIDER-null(7)>,
391 L<openssl-glossary(7)>, L<provider(7)>
395 Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved.
397 Licensed under the Apache License 2.0 (the "License"). You may not use
398 this file except in compliance with the License. You can obtain a copy
399 in the file LICENSE in the source distribution or at
400 L<https://www.openssl.org/source/license.html>.