OSSL-GUIDE-LIBRARIES-INTRODUCTION(7ossl) OpenSSL
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 the OpenSSL built-in "default" provider will be
automatically loaded.
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 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.
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.
FURTHER READING
See ossl-guide-libcrypto-introduction(7) for a more detailed
introduction to using "libcrypto" and ossl-guide-libssl-introduction(7)
for more information on "libssl".
SEE ALSO
openssl(1), ssl(7), evp(7), OSSL_LIB_CTX(3), openssl-threads(7),
property(7), OSSL_PROVIDER-default(7), OSSL_PROVIDER-base(7),
OSSL_PROVIDER-FIPS(7), OSSL_PROVIDER-legacy(7), OSSL_PROVIDER-null(7),
openssl-glossary(7), provider(7)
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>.
3.3.2 2024-09-04
OSSL-GUIDE-LIBRARIES-INTRODUCTION(7ossl)
openssl 3.3.2 - Generated Tue Oct 1 16:28:36 CDT 2024