From: Matt Caswell Date: Thu, 13 Jul 2023 14:02:09 +0000 (+0100) Subject: Provide an introduction to the OpenSSL libraries X-Git-Tag: openssl-3.2.0-alpha1~267 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=09ae9d6847294ef9cfeefaa83e176227ae098313;p=thirdparty%2Fopenssl.git Provide an introduction to the OpenSSL libraries Give an overview of the two libraries and some key concepts common to both. Reviewed-by: Hugo Landau Reviewed-by: Tim Hudson Reviewed-by: Matthias St. Pierre Reviewed-by: Anton Arapov (Merged from https://github.com/openssl/openssl/pull/21560) --- diff --git a/doc/man7/ossl-guide-libraries-introduction.pod b/doc/man7/ossl-guide-libraries-introduction.pod new file mode 100644 index 00000000000..78e0853d8e6 --- /dev/null +++ b/doc/man7/ossl-guide-libraries-introduction.pod @@ -0,0 +1,331 @@ +=pod + +=head1 NAME + +ossl-guide-libraries-introduction +- OpenSSL Guide: An introduction to the OpenSSL libraries + +=head1 INTRODUCTION + +OpenSSL supplies two libraries that can be used by applications known as +C and C. + +The C library provides APIs for general purpose cryptography such as +encryption, digital signatures, hash functions, etc. It additionally supplies +supporting APIs for cryptography related standards, e.g. for reading and writing +digital certificates (also known as X.509 certificates). Finally it also +supplies various additional supporting APIs that are not directly cryptography +related but are nonetheless useful and dependended upon by other APIs. For +example the "BIO" functions provide capabilities for abstracting I/O, e.g. via a +file or over a network. + +The C library provides functions to perform secure communication between +two peers across a network. Most signficiantly it implements support for the +SSL/TLS, DTLS and QUIC standards. + +The C library depends on and uses many of the capabilities supplied by +C. Any application linked against C will also link against +C, and most applications that do this will directly use API functions +supplied by both libraries. + +Applications may be written that only use C capabilities and do not +link against C at all. + +=head1 PROVIDERS + +As well as the two main libraries, OpenSSL also comes with a set of providers. + +A provider in OpenSSL is a component that collects together algorithm +implementations (for example an implementation of the symmetric encryption +algorithm AES). In order to use an algorithm you must have at least one +provider loaded that contains an implementation of it. OpenSSL comes with a +number of providers and they may also be obtained from third parties. + +Providers may either be "built-in" or in the form of a separate loadable module +file (typically one ending in ".so" or ".dll" dependent on the platform). A +built-in provider is one that is either already present in C or one +that the application has supplied itself directly. Third parties can also supply +providers in the form of loadable modules. + +If you don't load a provider explicitly (either in program code or via config) +then the OpenSSL built-in "default" provider will be automatically loaded. + +See L below for a description of the providers that OpenSSL +itself supplies. + +Loading and unloading providers is quite an expensive operation. It is normally +done once, early on in the application lifecycle and those providers are kept +loaded for the duration of the application execution. + +=head1 LIBRARY CONTEXTS + +Many OpenSSL API functions make use of a library context. A library context can +be thought of as a "scope" within which configuration options take effect. When +a provider is loaded, it is only loaded within the scope of a given library +context. In this way it is possible for different components of a complex +application to each use a different library context and have different providers +loaded with different configuration settings. + +If an application does not explicitly create a library context then the +"default" library context will be used. + +Library contexts are represented by the B type. Many OpenSSL API +functions take a library context as a parameter. Applications can always pass +B for this parameter to just use the default library context. + +The default library context is automatically created the first time it is +needed. This will automatically load any available configuration file and will +initialise OpenSSL for use. Unlike in earlier versions of OpenSSL (prior to +1.1.0) no explicit initialisation steps need to be taken. + +Similarly when the application exits, the default library context is +automatically destroyed. No explicit de-initialisation steps need to be taken. + +See L for more information about library contexts. +See also L. + +=head1 PROPERTY QUERY STRINGS + +In some cases the available providers may mean that more than one implementation +of any given algorithm might be available. For example the OpenSSL FIPS provider +supplies alternative implementations of many of the same algorithms that are +available in the OpenSSL default provider. + +The process of selecting an algorithm implementation is known as "fetching". +When OpenSSL fetches an algorithm to use it is possible to specify a "property +query string" to guide the selection process. For example a property query +string of "provider=default" could be used to force the selection to only +consider algorithm implementations in the default provider. + +Property query strings can be specified explicitly as an argument to a function. +It is also possible to specify a default property query string for the whole +library context using the L or +L functions. Where both +default properties and function specific properties are specified then they are +combined. Function specific properties will override default properties where +there is a conflict. + +See L for more +information about fetching. See L for more information about +properties. + +=head1 MULTI-THREADED APPLICATIONS + +As long as OpenSSL has been built with support for threads (the default case +on most platforms) then most OpenSSL I are thread-safe in the sense +that it is safe to call the same function from multiple threads at the same +time. However most OpenSSL I are not thread-safe. For example +the L and L functions are thread safe. However it +would not be thread safe to call BIO_write() from one thread while calling +BIO_read() in another where both functions are passed the same B object +since both of them may attempt to make changes to the same B object. + +There are exceptions to these rules. A small number of functions are not thread +safe at all. Where this is the case this restriction should be noted in the +documentation for the function. Similarly some data structures may be partially +or fully thread safe. For example it is always safe to use an B in +multiple threads. + +See L for a more detailed discussion on OpenSSL threading +support. + +=head1 ERROR HANDLING + +Most OpenSSL functions will provide a return value indicating whether the +function has been successful or not. It is considered best practice to always +check the return value from OpenSSL functions (where one is available). + +Most functions that return a pointer value will return NULL in the event of a +failure. + +Most functions that return an integer value will return a positive integer for +success. Some of these functions will return 0 to indicate failure. Others may +return 0 or a negative value for failure. + +Some functions cannot fail and have a B return type. There are also a +small number of functions that do not conform to the above conventions (e.g. +they may return 0 to indicate success). + +Due to the above variations in behaviour it is important to check the +documentation for each function for information about how to interpret the +return value for it. + +It is sometimes necessary to get further information about the cause of a +failure (e.g. for debugging or logging purposes). Many (but not all) functions +will add further information about a failure to the OpenSSL error stack. By +using the error stack you can find out information such as a reason code/string +for the error as well as the exact file and source line within OpenSSL that +emitted the error. + +OpenSSL supplies a set of error handling functions to query the error stack. See +L for information about the functions available for querying +error data. Also see L for information on some simple +helper functions for printing error data. Finally look at L +for how to clear old errors from the error stack. + +=head1 OPENSSL PROVIDERS + +OpenSSL comes with a set of providers. + +The algorithms available in each of these providers may vary due to build time +configuration options. The L command can be used to list the +currently available algorithms. + +The names of the algorithms shown from L can be used as an +algorithm identifier to the appropriate fetching function. Also see the provider +specific manual pages linked below for further details about using the +algorithms available in each of the providers. + +As well as the OpenSSL providers third parties can also implement providers. +For information on writing a provider see L. + +=head2 Default provider + +The default provider is built-in as part of the F library and +contains all of the most commonly used algorithm implementations. Should it be +needed (if other providers are loaded and offer implementations of the same +algorithms), the property query string "provider=default" can be used as a +search criterion for these implementations. The default provider includes all +of the functionality in the base provider below. + +If you don't load any providers at all then the "default" provider will be +automatically loaded. If you explicitly load any provider then the "default" +provider would also need to be explicitly loaded if it is required. + +See L. + +=head2 Base provider + +The base provider is built in as part of the F library and contains +algorithm implementations for encoding and decoding of OpenSSL keys. +Should it be needed (if other providers are loaded and offer +implementations of the same algorithms), the property query string +"provider=base" can be used as a search criterion for these implementations. +Some encoding and decoding algorithm implementations are not FIPS algorithm +implementations in themselves but support algorithms from the FIPS provider and +are allowed for use in "FIPS mode". The property query string "fips=yes" can be +used to select such algorithms. + +See L. + +=head2 FIPS provider + +The FIPS provider is a dynamically loadable module, and must therefore +be loaded explicitly, either in code or through OpenSSL configuration +(see L). It contains algorithm implementations that have been +validated according to FIPS standards. Should it be needed (if other +providers are loaded and offer implementations of the same algorithms), the +property query string "provider=fips" can be used as a search criterion for +these implementations. All approved algorithm implementations in the FIPS +provider can also be selected with the property "fips=yes". The FIPS provider +may also contain non-approved algorithm implementations and these can be +selected with the property "fips=no". + +Typically the L will also need to be loaded because the FIPS +provider does not support the encoding or decoding of keys. + +See L and L. + +=head2 Legacy provider + +The legacy provider is a dynamically loadable module, and must therefore +be loaded explicitly, either in code or through OpenSSL configuration +(see L). It contains algorithm implementations that are considered +insecure, or are no longer in common use such as MD2 or RC4. Should it be needed +(if other providers are loaded and offer implementations of the same algorithms), +the property "provider=legacy" can be used as a search criterion for these +implementations. + +See L. + +=head2 Null provider + +The null provider is built in as part of the F library. It contains +no algorithms in it at all. When fetching algorithms the default provider will +be automatically loaded if no other provider has been explicitly loaded. To +prevent that from happening you can explicitly load the null provider. + +You can use this if you create your own library context and want to ensure that +all API calls have correctly passed the created library context and are not +accidentally using the default library context. Load the null provider into the +default library context so that the default library context has no algorithm +implementations available. + +See L. + +=head1 CONFIGURATION + +By default OpenSSL will load a configuration file when it is first used. This +will set up various configuration settings within the default library context. +Applications that create their own library contexts may optionally configure +them with a config file using the L function. + +The configuration file can be used to automatically load providers and set up +default property query strings. + +For information on the OpenSSL configuration file format see L. + +=head1 LIBRARY CONVENTIONS + +Many OpenSSL functions that "get" or "set" a value follow a naming convention +using the numbers B<0> and B<1>, i.e. "get0", "get1", "set0" and "set1". This +can also apply to some functions that "add" a value to an existing set, i.e. +"add0" and "add1". + +For example the functions: + + int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev); + int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj); + +In the B<0> version the ownership of the object is passed to (for an add or set) +or retained by (for a get) the parent object. For example after calling the +X509_CRL_add0_revoked() function above, ownership of the I object is passed +to the I object. Therefore, after calling this function I should not +be freed directly. It will be freed implicitly when I is freed. + +In the B<1> version the ownership of the object is not passed to or retained by +the parent object. Instead a copy or "up ref" of the object is performed. So +after calling the X509_add1_trust_object() function above the application will +still be responsible for freeing the I value where appropriate. + +Many OpenSSL functions conform to a naming convention of the form +B. In this naming convention the B is the name +of an OpenSSL data structure (given in capital letters) that the function is +primarily operating on. The B portion of the name is usually in +lowercase letters and indicates the purpose of the function. + +=head1 DEMO APPLICATIONS + +OpenSSL is distributed with a set of demo applications which provide some +examples of how to use the various API functions. To look at them download the +OpenSSL source code from the OpenSSL website +(L). Extract the downloaded B<.tar.gz> file for +the version of OpenSSL that you are using and look at the various files in the +B sub-directory. + +The Makefiles in the subdirectories give instructions on how to build and run +the demo applications. + +=head1 FURTHER READING + +See L for a more detailed introduction to +using C and L for more information +on C. + +=head1 SEE ALSO + +L, L, L, L, L, +L, L, L, +L, L, L, +L, L + +=head1 COPYRIGHT + +Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut