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