Debian Codegraph @

upstream/debian-unstable/man7/ossl-guide-libcrypto-introduction.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OSSL-GUIDE-LIBCRYPTO-INTRODUCTION 7SSL"
58 .TH OSSL-GUIDE-LIBCRYPTO-INTRODUCTION 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 ossl\-guide\-libcrypto\-introduction, crypto
65 \&\- OpenSSL Guide: An introduction to libcrypto
66 .SH INTRODUCTION
67 .IX Header "INTRODUCTION"
68 The OpenSSL cryptography library (\f(CW\*(C`libcrypto\*(C'\fR) enables access to a wide range
69 of cryptographic algorithms used in various Internet standards. The services
70 provided by this library are used by the OpenSSL implementations of TLS and
71 CMS, and they have also been used to implement many other third party products
72 and protocols.
73 .PP
74 The functionality includes symmetric encryption, public key cryptography, key
75 agreement, certificate handling, cryptographic hash functions, cryptographic
76 pseudo-random number generators, message authentication codes (MACs), key
77 derivation functions (KDFs), and various utilities.
78 .SS Algorithms
79 .IX Subsection "Algorithms"
80 Cryptographic primitives such as the SHA256 digest, or AES encryption are
81 referred to in OpenSSL as "algorithms". Each algorithm may have multiple
82 implementations available for use. For example the RSA algorithm is available as
83 a "default" implementation suitable for general use, and a "fips" implementation
84 which has been validated to FIPS 140 standards for situations where that is
85 important. It is also possible that a third party could add additional
86 implementations such as in a hardware security module (HSM).
87 .PP
88 Algorithms are implemented in providers. See
89 \&\fBossl\-guide\-libraries\-introduction\fR\|(7) for information about providers.
90 .SS Operations
91 .IX Subsection "Operations"
92 Different algorithms can be grouped together by their purpose. For example there
93 are algorithms for encryption, and different algorithms for digesting data.
94 These different groups are known as "operations" in OpenSSL. Each operation
95 has a different set of functions associated with it. For example to perform an
96 encryption operation using AES (or any other encryption algorithm) you would use
97 the encryption functions detailed on the \fBEVP_EncryptInit\fR\|(3) page. Or to
98 perform a digest operation using SHA256 then you would use the digesting
99 functions on the \fBEVP_DigestInit\fR\|(3) page.
100 .SH "ALGORITHM FETCHING"
101 .IX Header "ALGORITHM FETCHING"
102 In order to use an algorithm an implementation for it must first be "fetched".
103 Fetching is the process of looking through the available implementations,
104 applying selection criteria (via a property query string), and finally choosing
105 the implementation that will be used.
106 .PP
107 Two types of fetching are supported by OpenSSL \- "Explicit fetching" and
108 "Implicit fetching".
109 .SS "Explicit fetching"
110 .IX Subsection "Explicit fetching"
111 Explicit fetching involves directly calling a specific API to fetch an algorithm
112 implementation from a provider. This fetched object can then be passed to other
113 APIs. These explicit fetching functions usually have the name \f(CW\*(C`APINAME_fetch\*(C'\fR,
114 where \f(CW\*(C`APINAME\*(C'\fR is the name of the operation. For example \fBEVP_MD_fetch\fR\|(3)
115 can be used to explicitly fetch a digest algorithm implementation. The user is
116 responsible for freeing the object returned from the \f(CW\*(C`APINAME_fetch\*(C'\fR function
117 using \f(CW\*(C`APINAME_free\*(C'\fR when it is no longer needed.
118 .PP
119 These fetching functions follow a fairly common pattern, where three
120 arguments are passed:
121 .IP "The library context" 4
122 .IX Item "The library context"
123 See \fBOSSL_LIB_CTX\fR\|(3) for a more detailed description.
124 This may be NULL to signify the default (global) library context, or a
125 context created by the user. Only providers loaded in this library context (see
126 \&\fBOSSL_PROVIDER_load\fR\|(3)) will be considered by the fetching function. In case
127 no provider has been loaded in this library context then the default provider
128 will be loaded as a fallback (see \fBOSSL_PROVIDER\-default\fR\|(7)).
129 .IP "An identifier" 4
130 .IX Item "An identifier"
131 For all currently implemented fetching functions this is the algorithm name.
132 Each provider supports a list of algorithm implementations. See the provider
133 specific documentation for information on the algorithm implementations
134 available in each provider:
135 "OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-default\fR\|(7),
136 "OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-FIPS\fR\|(7),
137 "OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-legacy\fR\|(7) and
138 "OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-base\fR\|(7).
139 .Sp
140 Note, while providers may register algorithms against a list of names using a
141 string with a colon separated list of names, fetching algorithms using that
142 format is currently unsupported.
143 .IP "A property query string" 4
144 .IX Item "A property query string"
145 The property query string used to guide selection of the algorithm
146 implementation. See
147 "PROPERTY QUERY STRINGS" in \fBossl\-guide\-libraries\-introduction\fR\|(7).
148 .PP
149 The algorithm implementation that is fetched can then be used with other diverse
150 functions that use them. For example the \fBEVP_DigestInit_ex\fR\|(3) function takes
151 as a parameter an \fBEVP_MD\fR object which may have been returned from an earlier
152 call to \fBEVP_MD_fetch\fR\|(3).
153 .SS "Implicit fetching"
154 .IX Subsection "Implicit fetching"
155 OpenSSL has a number of functions that return an algorithm object with no
156 associated implementation, such as \fBEVP_sha256\fR\|(3), \fBEVP_aes_128_cbc\fR\|(3),
157 \&\fBEVP_get_cipherbyname\fR\|(3) or \fBEVP_get_digestbyname\fR\|(3). These are present for
158 compatibility with OpenSSL before version 3.0 where explicit fetching was not
159 available.
160 .PP
161 When they are used with functions like \fBEVP_DigestInit_ex\fR\|(3) or
162 \&\fBEVP_CipherInit_ex\fR\|(3), the actual implementation to be used is
163 fetched implicitly using default search criteria (which uses NULL for the
164 library context and property query string).
165 .PP
166 In some cases implicit fetching can also occur when a NULL algorithm parameter
167 is supplied. In this case an algorithm implementation is implicitly fetched
168 using default search criteria and an algorithm name that is consistent with
169 the context in which it is being used.
170 .PP
171 Functions that use an \fBEVP_PKEY_CTX\fR or an \fBEVP_PKEY\fR\|(3), such as
172 \&\fBEVP_DigestSignInit\fR\|(3), all fetch the implementations implicitly. Usually the
173 algorithm to fetch is determined based on the type of key that is being used and
174 the function that has been called.
175 .SS Performance
176 .IX Subsection "Performance"
177 If you perform the same operation many times with the same algorithm then it is
178 recommended to use a single explicit fetch of the algorithm and then reuse the
179 explicitly fetched algorithm each subsequent time. This will typically be
180 faster than implicitly fetching the algorithm every time you use it. See an
181 example of Explicit fetching in "USING ALGORITHMS IN APPLICATIONS".
182 .PP
183 Prior to OpenSSL 3.0, functions such as \fBEVP_sha256()\fR which return a "const"
184 object were used directly to indicate the algorithm to use in various function
185 calls. If you pass the return value of one of these convenience functions to an
186 operation then you are using implicit fetching. If you are converting an
187 application that worked with an OpenSSL version prior to OpenSSL 3.0 then
188 consider changing instances of implicit fetching to explicit fetching instead.
189 .PP
190 If an explicitly fetched object is not passed to an operation, then any implicit
191 fetch will use an internally cached prefetched object, but it will
192 still be slower than passing the explicitly fetched object directly.
193 .PP
194 The following functions can be used for explicit fetching:
195 .IP \fBEVP_MD_fetch\fR\|(3) 4
196 .IX Item "EVP_MD_fetch"
197 Fetch a message digest/hashing algorithm implementation.
198 .IP \fBEVP_CIPHER_fetch\fR\|(3) 4
199 .IX Item "EVP_CIPHER_fetch"
200 Fetch a symmetric cipher algorithm implementation.
201 .IP \fBEVP_KDF_fetch\fR\|(3) 4
202 .IX Item "EVP_KDF_fetch"
203 Fetch a Key Derivation Function (KDF) algorithm implementation.
204 .IP \fBEVP_MAC_fetch\fR\|(3) 4
205 .IX Item "EVP_MAC_fetch"
206 Fetch a Message Authentication Code (MAC) algorithm implementation.
207 .IP \fBEVP_KEM_fetch\fR\|(3) 4
208 .IX Item "EVP_KEM_fetch"
209 Fetch a Key Encapsulation Mechanism (KEM) algorithm implementation
210 .IP \fBOSSL_ENCODER_fetch\fR\|(3) 4
211 .IX Item "OSSL_ENCODER_fetch"
212 Fetch an encoder algorithm implementation (e.g. to encode keys to a specified
213 format).
214 .IP \fBOSSL_DECODER_fetch\fR\|(3) 4
215 .IX Item "OSSL_DECODER_fetch"
216 Fetch a decoder algorithm implementation (e.g. to decode keys from a specified
217 format).
218 .IP \fBEVP_RAND_fetch\fR\|(3) 4
219 .IX Item "EVP_RAND_fetch"
220 Fetch a Pseudo Random Number Generator (PRNG) algorithm implementation.
221 .PP
222 See "OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-default\fR\|(7),
223 "OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-FIPS\fR\|(7),
224 "OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-legacy\fR\|(7) and
225 "OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-base\fR\|(7) for a list of algorithm names
226 that can be fetched.
227 .SH "FETCHING EXAMPLES"
228 .IX Header "FETCHING EXAMPLES"
229 The following section provides a series of examples of fetching algorithm
230 implementations.
231 .PP
232 Fetch any available implementation of SHA2\-256 in the default context. Note
233 that some algorithms have aliases. So "SHA256" and "SHA2\-256" are synonymous:
234 .PP
235 .Vb 3
236 \& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", NULL);
237 \& ...
238 \& EVP_MD_free(md);
239 .Ve
240 .PP
241 Fetch any available implementation of AES\-128\-CBC in the default context:
242 .PP
243 .Vb 3
244 \& EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES\-128\-CBC", NULL);
245 \& ...
246 \& EVP_CIPHER_free(cipher);
247 .Ve
248 .PP
249 Fetch an implementation of SHA2\-256 from the default provider in the default
250 context:
251 .PP
252 .Vb 3
253 \& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider=default");
254 \& ...
255 \& EVP_MD_free(md);
256 .Ve
257 .PP
258 Fetch an implementation of SHA2\-256 that is not from the default provider in the
259 default context:
260 .PP
261 .Vb 3
262 \& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider!=default");
263 \& ...
264 \& EVP_MD_free(md);
265 .Ve
266 .PP
267 Fetch an implementation of SHA2\-256 that is preferably from the FIPS provider in
268 the default context:
269 .PP
270 .Vb 3
271 \& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider=?fips");
272 \& ...
273 \& EVP_MD_free(md);
274 .Ve
275 .PP
276 Fetch an implementation of SHA2\-256 from the default provider in the specified
277 library context:
278 .PP
279 .Vb 3
280 \& EVP_MD *md = EVP_MD_fetch(libctx, "SHA2\-256", "provider=default");
281 \& ...
282 \& EVP_MD_free(md);
283 .Ve
284 .PP
285 Load the legacy provider into the default context and then fetch an
286 implementation of WHIRLPOOL from it:
287 .PP
288 .Vb 2
289 \& /* This only needs to be done once \- usually at application start up */
290 \& OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
291 \&
292 \& EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy");
293 \& ...
294 \& EVP_MD_free(md);
295 .Ve
296 .PP
297 Note that in the above example the property string "provider=legacy" is optional
298 since, assuming no other providers have been loaded, the only implementation of
299 the "whirlpool" algorithm is in the "legacy" provider. Also note that the
300 default provider should be explicitly loaded if it is required in addition to
301 other providers:
302 .PP
303 .Vb 3
304 \& /* This only needs to be done once \- usually at application start up */
305 \& OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
306 \& OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");
307 \&
308 \& EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
309 \& EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2\-256", NULL);
310 \& ...
311 \& EVP_MD_free(md_whirlpool);
312 \& EVP_MD_free(md_sha256);
313 .Ve
314 .SH "USING ALGORITHMS IN APPLICATIONS"
315 .IX Header "USING ALGORITHMS IN APPLICATIONS"
316 Cryptographic algorithms are made available to applications through use of the
317 "EVP" APIs. Each of the various operations such as encryption, digesting,
318 message authentication codes, etc., have a set of EVP function calls that can
319 be invoked to use them. See the \fBevp\fR\|(7) page for further details.
320 .PP
321 Most of these follow a common pattern. A "context" object is first created. For
322 example for a digest operation you would use an \fBEVP_MD_CTX\fR, and for an
323 encryption/decryption operation you would use an \fBEVP_CIPHER_CTX\fR. The
324 operation is then initialised ready for use via an "init" function \- optionally
325 passing in a set of parameters (using the \fBOSSL_PARAM\fR\|(3) type) to configure how
326 the operation should behave. Next data is fed into the operation in a series of
327 "update" calls. The operation is finalised using a "final" call which will
328 typically provide some kind of output. Finally the context is cleaned up and
329 freed.
330 .PP
331 The following shows a complete example for doing this process for digesting
332 data using SHA256. The process is similar for other operations such as
333 encryption/decryption, signatures, message authentication codes, etc. Additional
334 examples can be found in the OpenSSL demos (see
335 "DEMO APPLICATIONS" in \fBossl\-guide\-libraries\-introduction\fR\|(7)).
336 .PP
337 .Vb 4
338 \& #include <stdio.h>
339 \& #include <openssl/evp.h>
340 \& #include <openssl/bio.h>
341 \& #include <openssl/err.h>
342 \&
343 \& int main(void)
344 \& {
345 \& EVP_MD_CTX *ctx = NULL;
346 \& EVP_MD *sha256 = NULL;
347 \& const unsigned char msg[] = {
348 \& 0x00, 0x01, 0x02, 0x03
349 \& };
350 \& unsigned int len = 0;
351 \& unsigned char *outdigest = NULL;
352 \& int ret = 1;
353 \&
354 \& /* Create a context for the digest operation */
355 \& ctx = EVP_MD_CTX_new();
356 \& if (ctx == NULL)
357 \& goto err;
358 \&
359 \& /*
360 \& * Fetch the SHA256 algorithm implementation for doing the digest. We\*(Aqre
361 \& * using the "default" library context here (first NULL parameter), and
362 \& * we\*(Aqre not supplying any particular search criteria for our SHA256
363 \& * implementation (second NULL parameter). Any SHA256 implementation will
364 \& * do.
365 \& * In a larger application this fetch would just be done once, and could
366 \& * be used for multiple calls to other operations such as EVP_DigestInit_ex().
367 \& */
368 \& sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
369 \& if (sha256 == NULL)
370 \& goto err;
371 \&
372 \& /* Initialise the digest operation */
373 \& if (!EVP_DigestInit_ex(ctx, sha256, NULL))
374 \& goto err;
375 \&
376 \& /*
377 \& * Pass the message to be digested. This can be passed in over multiple
378 \& * EVP_DigestUpdate calls if necessary
379 \& */
380 \& if (!EVP_DigestUpdate(ctx, msg, sizeof(msg)))
381 \& goto err;
382 \&
383 \& /* Allocate the output buffer */
384 \& outdigest = OPENSSL_malloc(EVP_MD_get_size(sha256));
385 \& if (outdigest == NULL)
386 \& goto err;
387 \&
388 \& /* Now calculate the digest itself */
389 \& if (!EVP_DigestFinal_ex(ctx, outdigest, &len))
390 \& goto err;
391 \&
392 \& /* Print out the digest result */
393 \& BIO_dump_fp(stdout, outdigest, len);
394 \&
395 \& ret = 0;
396 \&
397 \& err:
398 \& /* Clean up all the resources we allocated */
399 \& OPENSSL_free(outdigest);
400 \& EVP_MD_free(sha256);
401 \& EVP_MD_CTX_free(ctx);
402 \& if (ret != 0)
403 \& ERR_print_errors_fp(stderr);
404 \& return ret;
405 \& }
406 .Ve
407 .SH "ENCODING AND DECODING KEYS"
408 .IX Header "ENCODING AND DECODING KEYS"
409 Many algorithms require the use of a key. Keys can be generated dynamically
410 using the EVP APIs (for example see \fBEVP_PKEY_Q_keygen\fR\|(3)). However it is often
411 necessary to save or load keys (or their associated parameters) to or from some
412 external format such as PEM or DER (see \fBopenssl\-glossary\fR\|(7)). OpenSSL uses
413 encoders and decoders to perform this task.
414 .PP
415 Encoders and decoders are just algorithm implementations in the same way as
416 any other algorithm implementation in OpenSSL. They are implemented by
417 providers. The OpenSSL encoders and decoders are available in the default
418 provider. They are also duplicated in the base provider.
419 .PP
420 For information about encoders see \fBOSSL_ENCODER_CTX_new_for_pkey\fR\|(3). For
421 information about decoders see \fBOSSL_DECODER_CTX_new_for_pkey\fR\|(3).
422 .PP
423 As well as using encoders/decoders directly there are also some helper functions
424 that can be used for certain well known and commonly used formats. For example
425 see \fBPEM_read_PrivateKey\fR\|(3) and \fBPEM_write_PrivateKey\fR\|(3) for information
426 about reading and writing key data from PEM encoded files.
427 .SH "FURTHER READING"
428 .IX Header "FURTHER READING"
429 See \fBossl\-guide\-libssl\-introduction\fR\|(7) for an introduction to using \f(CW\*(C`libssl\*(C'\fR.
430 .SH "SEE ALSO"
431 .IX Header "SEE ALSO"
432 \&\fBopenssl\fR\|(1), \fBssl\fR\|(7), \fBevp\fR\|(7), \fBOSSL_LIB_CTX\fR\|(3), \fBopenssl\-threads\fR\|(7),
433 \&\fBproperty\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7), \fBOSSL_PROVIDER\-base\fR\|(7),
434 \&\fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7), \fBOSSL_PROVIDER\-null\fR\|(7),
435 \&\fBopenssl\-glossary\fR\|(7), \fBprovider\fR\|(7)
436 .SH COPYRIGHT
437 .IX Header "COPYRIGHT"
438 Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved.
439 .PP
440 Licensed under the Apache License 2.0 (the "License"). You may not use
441 this file except in compliance with the License. You can obtain a copy
442 in the file LICENSE in the source distribution or at
443 <https://www.openssl.org/source/license.html>.