Ubuntu Manpage: ossl-guide-libraries-introduction - OpenSSL Guide: An introduction to the OpenSSL

Provided by: openssl_3.3.1-2ubuntu2_amd64

NAME

       ossl-guide-libraries-introduction - OpenSSL Guide: An introduction to the OpenSSL
       libraries

INTRODUCTION

       OpenSSL supplies two libraries that can be used by applications known as "libcrypto" and
       "libssl".

       The "libcrypto" 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 depended 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 "libssl" library provides functions to perform secure communication between two peers
       across a network. Most significantly it implements support for the SSL/TLS, DTLS and QUIC
       standards.

       The "libssl" library depends on and uses many of the capabilities supplied by "libcrypto".
       Any application linked against "libssl" will also link against "libcrypto", and most
       applications that do this will directly use API functions supplied by both libraries.

       Applications may be written that only use "libcrypto" capabilities and do not link against
       "libssl" at all.

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 "libcrypto" 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 one of
the following OpenSSL provdiers will be loaded automatically:

• The built-in "default" provider when running on a system that is not operating in
FIPS-approved mode.

• The "fips" provider when running on a system that is operating in FIPS-approved mode.

See "OPENSSL PROVIDERS" 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.

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 OSSL_LIB_CTX type. Many OpenSSL API functions take
       a library context as a parameter. Applications can always pass NULL 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 OSSL_LIB_CTX(3) for more information about library contexts.  See also "ALGORITHM
       FETCHING" in ossl-guide-libcrypto-introduction(7).

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 EVP_set_default_properties(3) or EVP_default_properties_enable_fips(3)
       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 "ALGORITHM FETCHING" in ossl-guide-libcrypto-introduction(7) for more information
       about fetching. See property(7) for more information about properties.

MULTI-THREADED APPLICATIONS

       As long as OpenSSL has been built with support for threads (the default case on most
       platforms) then most OpenSSL functions 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 data
       structures are not thread-safe. For example the BIO_write(3) and BIO_read(3) 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 BIO object since
       both of them may attempt to make changes to the same BIO 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 OSSL_LIB_CTX in multiple threads.

       See openssl-threads(7) for a more detailed discussion on OpenSSL threading support.

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 void 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
       ERR_get_error(3) for information about the functions available for querying error data.
       Also see ERR_print_errors(3) for information on some simple helper functions for printing
       error data. Finally look at ERR_clear_error(3) for how to clear old errors from the error
       stack.

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 openssl-list(1) command can be used to list the currently
available algorithms.

The names of the algorithms shown from openssl-list(1) 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 provider(7).

Default provider
The default provider is built-in as part of the libcrypto 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 and the system is not running in FIPS-approved
mode, 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 OSSL_PROVIDER-default(7).

Base provider
The base provider is built in as part of the libcrypto 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 OSSL_PROVIDER-base(7).

FIPS provider
The FIPS provider is a dynamically loadable module, and must therefore be loaded
explicitly, either in code or through OpenSSL configuration (see config(5)). 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 "Base provider" will also need to be loaded because the FIPS provider does
not support the encoding or decoding of keys.

If you don't load any providers at all and the system is running in FIPS-approved mode,
then the FIPS provider will be automatically loaded. If you explicitly load any provider
then the FIPS provider would also need to be explicitly loaded if it is required.

See OSSL_PROVIDER-FIPS(7) and fips_module(7).

Legacy provider
The legacy provider is a dynamically loadable module, and must therefore be loaded
explicitly, either in code or through OpenSSL configuration (see config(5)). 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 OSSL_PROVIDER-legacy(7).

Null provider
The null provider is built in as part of the libcrypto 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 OSSL_PROVIDER-null(7).

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 OSSL_LIB_CTX_load_config(3) 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 config(5).

LIBRARY CONVENTIONS

       Many OpenSSL functions that "get" or "set" a value follow a naming convention using the
       numbers 0 and 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 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 rev object is passed to the crl object. Therefore, after
       calling this function rev should not be freed directly. It will be freed implicitly when
       crl is freed.

       In the 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 obj value where appropriate.

       Many OpenSSL functions conform to a naming convention of the form CLASSNAME_func_name().
       In this naming convention the CLASSNAME is the name of an OpenSSL data structure (given in
       capital letters) that the function is primarily operating on. The func_name portion of the
       name is usually in lowercase letters and indicates the purpose of the function.

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 (<https://www.openssl.org/source/>). Extract the downloaded .tar.gz
       file for the version of OpenSSL that you are using and look at the various files in the
       demos sub-directory.

       The Makefiles in the subdirectories give instructions on how to build and run the demo
       applications.

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 <https://www.openssl.org/source/license.html>.