Debian Codegraph @

upstream/debian-unstable/man7/ossl-guide-libraries-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-LIBRARIES-INTRODUCTION 7SSL"
58 .TH OSSL-GUIDE-LIBRARIES-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\-libraries\-introduction
65 \&\- OpenSSL Guide: An introduction to the OpenSSL libraries
66 .SH INTRODUCTION
67 .IX Header "INTRODUCTION"
68 OpenSSL supplies two libraries that can be used by applications known as
69 \&\f(CW\*(C`libcrypto\*(C'\fR and \f(CW\*(C`libssl\*(C'\fR.
70 .PP
71 The \f(CW\*(C`libcrypto\*(C'\fR library provides APIs for general purpose cryptography such as
72 encryption, digital signatures, hash functions, etc. It additionally supplies
73 supporting APIs for cryptography related standards, e.g. for reading and writing
74 digital certificates (also known as X.509 certificates). Finally it also
75 supplies various additional supporting APIs that are not directly cryptography
76 related but are nonetheless useful and depended upon by other APIs. For
77 example the "BIO" functions provide capabilities for abstracting I/O, e.g. via a
78 file or over a network.
79 .PP
80 The \f(CW\*(C`libssl\*(C'\fR library provides functions to perform secure communication between
81 two peers across a network. Most significantly it implements support for the
82 SSL/TLS, DTLS and QUIC standards.
83 .PP
84 The \f(CW\*(C`libssl\*(C'\fR library depends on and uses many of the capabilities supplied by
85 \&\f(CW\*(C`libcrypto\*(C'\fR. Any application linked against \f(CW\*(C`libssl\*(C'\fR will also link against
86 \&\f(CW\*(C`libcrypto\*(C'\fR, and most applications that do this will directly use API functions
87 supplied by both libraries.
88 .PP
89 Applications may be written that only use \f(CW\*(C`libcrypto\*(C'\fR capabilities and do not
90 link against \f(CW\*(C`libssl\*(C'\fR at all.
91 .SH PROVIDERS
92 .IX Header "PROVIDERS"
93 As well as the two main libraries, OpenSSL also comes with a set of providers.
94 .PP
95 A provider in OpenSSL is a component that collects together algorithm
96 implementations (for example an implementation of the symmetric encryption
97 algorithm AES). In order to use an algorithm you must have at least one
98 provider loaded that contains an implementation of it. OpenSSL comes with a
99 number of providers and they may also be obtained from third parties.
100 .PP
101 Providers may either be "built-in" or in the form of a separate loadable module
102 file (typically one ending in ".so" or ".dll" dependent on the platform). A
103 built-in provider is one that is either already present in \f(CW\*(C`libcrypto\*(C'\fR or one
104 that the application has supplied itself directly. Third parties can also supply
105 providers in the form of loadable modules.
106 .PP
107 If you don't load a provider explicitly (either in program code or via config)
108 then the OpenSSL built-in "default" provider will be automatically loaded.
109 .PP
110 See "OPENSSL PROVIDERS" below for a description of the providers that OpenSSL
111 itself supplies.
112 .PP
113 Loading and unloading providers is quite an expensive operation. It is normally
114 done once, early on in the application lifecycle and those providers are kept
115 loaded for the duration of the application execution.
116 .SH "LIBRARY CONTEXTS"
117 .IX Header "LIBRARY CONTEXTS"
118 Many OpenSSL API functions make use of a library context. A library context can
119 be thought of as a "scope" within which configuration options take effect. When
120 a provider is loaded, it is only loaded within the scope of a given library
121 context. In this way it is possible for different components of a complex
122 application to each use a different library context and have different providers
123 loaded with different configuration settings.
124 .PP
125 If an application does not explicitly create a library context then the
126 "default" library context will be used.
127 .PP
128 Library contexts are represented by the \fBOSSL_LIB_CTX\fR type. Many OpenSSL API
129 functions take a library context as a parameter. Applications can always pass
130 \&\fBNULL\fR for this parameter to just use the default library context.
131 .PP
132 The default library context is automatically created the first time it is
133 needed. This will automatically load any available configuration file and will
134 initialise OpenSSL for use. Unlike in earlier versions of OpenSSL (prior to
135 1.1.0) no explicit initialisation steps need to be taken.
136 .PP
137 Similarly when the application exits, the default library context is
138 automatically destroyed. No explicit de-initialisation steps need to be taken.
139 .PP
140 See \fBOSSL_LIB_CTX\fR\|(3) for more information about library contexts.
141 See also "ALGORITHM FETCHING" in \fBossl\-guide\-libcrypto\-introduction\fR\|(7).
142 .SH "PROPERTY QUERY STRINGS"
143 .IX Header "PROPERTY QUERY STRINGS"
144 In some cases the available providers may mean that more than one implementation
145 of any given algorithm might be available. For example the OpenSSL FIPS provider
146 supplies alternative implementations of many of the same algorithms that are
147 available in the OpenSSL default provider.
148 .PP
149 The process of selecting an algorithm implementation is known as "fetching".
150 When OpenSSL fetches an algorithm to use it is possible to specify a "property
151 query string" to guide the selection process. For example a property query
152 string of "provider=default" could be used to force the selection to only
153 consider algorithm implementations in the default provider.
154 .PP
155 Property query strings can be specified explicitly as an argument to a function.
156 It is also possible to specify a default property query string for the whole
157 library context using the \fBEVP_set_default_properties\fR\|(3) or
158 \&\fBEVP_default_properties_enable_fips\fR\|(3) functions. Where both
159 default properties and function specific properties are specified then they are
160 combined. Function specific properties will override default properties where
161 there is a conflict.
162 .PP
163 See "ALGORITHM FETCHING" in \fBossl\-guide\-libcrypto\-introduction\fR\|(7) for more
164 information about fetching. See \fBproperty\fR\|(7) for more information about
165 properties.
166 .SH "MULTI-THREADED APPLICATIONS"
167 .IX Header "MULTI-THREADED APPLICATIONS"
168 As long as OpenSSL has been built with support for threads (the default case
169 on most platforms) then most OpenSSL \fIfunctions\fR are thread-safe in the sense
170 that it is safe to call the same function from multiple threads at the same
171 time. However most OpenSSL \fIdata structures\fR are not thread-safe. For example
172 the \fBBIO_write\fR\|(3) and \fBBIO_read\fR\|(3) functions are thread safe. However it
173 would not be thread safe to call \fBBIO_write()\fR from one thread while calling
174 \&\fBBIO_read()\fR in another where both functions are passed the same \fBBIO\fR object
175 since both of them may attempt to make changes to the same \fBBIO\fR object.
176 .PP
177 There are exceptions to these rules. A small number of functions are not thread
178 safe at all. Where this is the case this restriction should be noted in the
179 documentation for the function. Similarly some data structures may be partially
180 or fully thread safe. For example it is always safe to use an \fBOSSL_LIB_CTX\fR in
181 multiple threads.
182 .PP
183 See \fBopenssl\-threads\fR\|(7) for a more detailed discussion on OpenSSL threading
184 support.
185 .SH "ERROR HANDLING"
186 .IX Header "ERROR HANDLING"
187 Most OpenSSL functions will provide a return value indicating whether the
188 function has been successful or not. It is considered best practice to always
189 check the return value from OpenSSL functions (where one is available).
190 .PP
191 Most functions that return a pointer value will return NULL in the event of a
192 failure.
193 .PP
194 Most functions that return an integer value will return a positive integer for
195 success. Some of these functions will return 0 to indicate failure. Others may
196 return 0 or a negative value for failure.
197 .PP
198 Some functions cannot fail and have a \fBvoid\fR return type. There are also a
199 small number of functions that do not conform to the above conventions (e.g.
200 they may return 0 to indicate success).
201 .PP
202 Due to the above variations in behaviour it is important to check the
203 documentation for each function for information about how to interpret the
204 return value for it.
205 .PP
206 It is sometimes necessary to get further information about the cause of a
207 failure (e.g. for debugging or logging purposes). Many (but not all) functions
208 will add further information about a failure to the OpenSSL error stack. By
209 using the error stack you can find out information such as a reason code/string
210 for the error as well as the exact file and source line within OpenSSL that
211 emitted the error.
212 .PP
213 OpenSSL supplies a set of error handling functions to query the error stack. See
214 \&\fBERR_get_error\fR\|(3) for information about the functions available for querying
215 error data. Also see \fBERR_print_errors\fR\|(3) for information on some simple
216 helper functions for printing error data. Finally look at \fBERR_clear_error\fR\|(3)
217 for how to clear old errors from the error stack.
218 .SH "OPENSSL PROVIDERS"
219 .IX Header "OPENSSL PROVIDERS"
220 OpenSSL comes with a set of providers.
221 .PP
222 The algorithms available in each of these providers may vary due to build time
223 configuration options. The \fBopenssl\-list\fR\|(1) command can be used to list the
224 currently available algorithms.
225 .PP
226 The names of the algorithms shown from \fBopenssl\-list\fR\|(1) can be used as an
227 algorithm identifier to the appropriate fetching function. Also see the provider
228 specific manual pages linked below for further details about using the
229 algorithms available in each of the providers.
230 .PP
231 As well as the OpenSSL providers third parties can also implement providers.
232 For information on writing a provider see \fBprovider\fR\|(7).
233 .SS "Default provider"
234 .IX Subsection "Default provider"
235 The default provider is built-in as part of the \fIlibcrypto\fR library and
236 contains all of the most commonly used algorithm implementations. Should it be
237 needed (if other providers are loaded and offer implementations of the same
238 algorithms), the property query string "provider=default" can be used as a
239 search criterion for these implementations. The default provider includes all
240 of the functionality in the base provider below.
241 .PP
242 If you don't load any providers at all then the "default" provider will be
243 automatically loaded. If you explicitly load any provider then the "default"
244 provider would also need to be explicitly loaded if it is required.
245 .PP
246 See \fBOSSL_PROVIDER\-default\fR\|(7).
247 .SS "Base provider"
248 .IX Subsection "Base provider"
249 The base provider is built in as part of the \fIlibcrypto\fR library and contains
250 algorithm implementations for encoding and decoding of OpenSSL keys.
251 Should it be needed (if other providers are loaded and offer
252 implementations of the same algorithms), the property query string
253 "provider=base" can be used as a search criterion for these implementations.
254 Some encoding and decoding algorithm implementations are not FIPS algorithm
255 implementations in themselves but support algorithms from the FIPS provider and
256 are allowed for use in "FIPS mode". The property query string "fips=yes" can be
257 used to select such algorithms.
258 .PP
259 See \fBOSSL_PROVIDER\-base\fR\|(7).
260 .SS "FIPS provider"
261 .IX Subsection "FIPS provider"
262 The FIPS provider is a dynamically loadable module, and must therefore
263 be loaded explicitly, either in code or through OpenSSL configuration
264 (see \fBconfig\fR\|(5)). It contains algorithm implementations that have been
265 validated according to FIPS standards. Should it be needed (if other
266 providers are loaded and offer implementations of the same algorithms), the
267 property query string "provider=fips" can be used as a search criterion for
268 these implementations. All approved algorithm implementations in the FIPS
269 provider can also be selected with the property "fips=yes". The FIPS provider
270 may also contain non-approved algorithm implementations and these can be
271 selected with the property "fips=no".
272 .PP
273 Typically the "Base provider" will also need to be loaded because the FIPS
274 provider does not support the encoding or decoding of keys.
275 .PP
276 See \fBOSSL_PROVIDER\-FIPS\fR\|(7) and \fBfips_module\fR\|(7).
277 .SS "Legacy provider"
278 .IX Subsection "Legacy provider"
279 The legacy provider is a dynamically loadable module, and must therefore
280 be loaded explicitly, either in code or through OpenSSL configuration
281 (see \fBconfig\fR\|(5)). It contains algorithm implementations that are considered
282 insecure, or are no longer in common use such as MD2 or RC4. Should it be needed
283 (if other providers are loaded and offer implementations of the same algorithms),
284 the property "provider=legacy" can be used as a search criterion for these
285 implementations.
286 .PP
287 See \fBOSSL_PROVIDER\-legacy\fR\|(7).
288 .SS "Null provider"
289 .IX Subsection "Null provider"
290 The null provider is built in as part of the \fIlibcrypto\fR library. It contains
291 no algorithms in it at all. When fetching algorithms the default provider will
292 be automatically loaded if no other provider has been explicitly loaded. To
293 prevent that from happening you can explicitly load the null provider.
294 .PP
295 You can use this if you create your own library context and want to ensure that
296 all API calls have correctly passed the created library context and are not
297 accidentally using the default library context. Load the null provider into the
298 default library context so that the default library context has no algorithm
299 implementations available.
300 .PP
301 See \fBOSSL_PROVIDER\-null\fR\|(7).
302 .SH CONFIGURATION
303 .IX Header "CONFIGURATION"
304 By default OpenSSL will load a configuration file when it is first used. This
305 will set up various configuration settings within the default library context.
306 Applications that create their own library contexts may optionally configure
307 them with a config file using the \fBOSSL_LIB_CTX_load_config\fR\|(3) function.
308 .PP
309 The configuration file can be used to automatically load providers and set up
310 default property query strings.
311 .PP
312 For information on the OpenSSL configuration file format see \fBconfig\fR\|(5).
313 .SH "LIBRARY CONVENTIONS"
314 .IX Header "LIBRARY CONVENTIONS"
315 Many OpenSSL functions that "get" or "set" a value follow a naming convention
316 using the numbers \fB0\fR and \fB1\fR, i.e. "get0", "get1", "set0" and "set1". This
317 can also apply to some functions that "add" a value to an existing set, i.e.
318 "add0" and "add1".
319 .PP
320 For example the functions:
321 .PP
322 .Vb 2
323 \& int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev);
324 \& int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj);
325 .Ve
326 .PP
327 In the \fB0\fR version the ownership of the object is passed to (for an add or set)
328 or retained by (for a get) the parent object. For example after calling the
329 \&\fBX509_CRL_add0_revoked()\fR function above, ownership of the \fIrev\fR object is passed
330 to the \fIcrl\fR object. Therefore, after calling this function \fIrev\fR should not
331 be freed directly. It will be freed implicitly when \fIcrl\fR is freed.
332 .PP
333 In the \fB1\fR version the ownership of the object is not passed to or retained by
334 the parent object. Instead a copy or "up ref" of the object is performed. So
335 after calling the \fBX509_add1_trust_object()\fR function above the application will
336 still be responsible for freeing the \fIobj\fR value where appropriate.
337 .PP
338 Many OpenSSL functions conform to a naming convention of the form
339 \&\fBCLASSNAME_func_name()\fR. In this naming convention the \fBCLASSNAME\fR is the name
340 of an OpenSSL data structure (given in capital letters) that the function is
341 primarily operating on. The \fBfunc_name\fR portion of the name is usually in
342 lowercase letters and indicates the purpose of the function.
343 .SH "DEMO APPLICATIONS"
344 .IX Header "DEMO APPLICATIONS"
345 OpenSSL is distributed with a set of demo applications which provide some
346 examples of how to use the various API functions. To look at them download the
347 OpenSSL source code from the OpenSSL website
348 (<https://www.openssl.org/source/>). Extract the downloaded \fB.tar.gz\fR file for
349 the version of OpenSSL that you are using and look at the various files in the
350 \&\fBdemos\fR sub-directory.
351 .PP
352 The Makefiles in the subdirectories give instructions on how to build and run
353 the demo applications.
354 .SH "FURTHER READING"
355 .IX Header "FURTHER READING"
356 See \fBossl\-guide\-libcrypto\-introduction\fR\|(7) for a more detailed introduction to
357 using \f(CW\*(C`libcrypto\*(C'\fR and \fBossl\-guide\-libssl\-introduction\fR\|(7) for more information
358 on \f(CW\*(C`libssl\*(C'\fR.
359 .SH "SEE ALSO"
360 .IX Header "SEE ALSO"
361 \&\fBopenssl\fR\|(1), \fBssl\fR\|(7), \fBevp\fR\|(7), \fBOSSL_LIB_CTX\fR\|(3), \fBopenssl\-threads\fR\|(7),
362 \&\fBproperty\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7), \fBOSSL_PROVIDER\-base\fR\|(7),
363 \&\fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7), \fBOSSL_PROVIDER\-null\fR\|(7),
364 \&\fBopenssl\-glossary\fR\|(7), \fBprovider\fR\|(7)
365 .SH COPYRIGHT
366 .IX Header "COPYRIGHT"
367 Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
368 .PP
369 Licensed under the Apache License 2.0 (the "License"). You may not use
370 this file except in compliance with the License. You can obtain a copy
371 in the file LICENSE in the source distribution or at
372 <https://www.openssl.org/source/license.html>.