--- /dev/null
+=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<libcrypto> and C<libssl>.
+
+The C<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 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<libssl> 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<libssl> library depends on and uses many of the capabilities supplied by
+C<libcrypto>. Any application linked against C<libssl> will also link against
+C<libcrypto>, and most applications that do this will directly use API functions
+supplied by both libraries.
+
+Applications may be written that only use C<libcrypto> capabilities and do not
+link against C<libssl> 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<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 L</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.
+
+=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<OSSL_LIB_CTX> type. Many OpenSSL API
+functions take a library context as a parameter. Applications can always pass
+B<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 L<OSSL_LIB_CTX(3)> for more information about library contexts.
+See also L<ossl-guide-libcrypto-introduction(7)/ALGORITHM FETCHING>.
+
+=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<EVP_set_default_properties(3)> or
+L<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 L<ossl-guide-libcrypto-introduction(7)/ALGORITHM FETCHING> for more
+information about fetching. See L<property(7)> 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<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 I<data structures> are not thread-safe. For example
+the L<BIO_write(3)> and L<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 B<BIO> object
+since both of them may attempt to make changes to the same B<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 B<OSSL_LIB_CTX> in
+multiple threads.
+
+See L<openssl-threads(7)> 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<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
+L<ERR_get_error(3)> for information about the functions available for querying
+error data. Also see L<ERR_print_errors(3)> for information on some simple
+helper functions for printing error data. Finally look at L<ERR_clear_error(3)>
+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<openssl-list(1)> command can be used to list the
+currently available algorithms.
+
+The names of the algorithms shown from L<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 L<provider(7)>.
+
+=head2 Default provider
+
+The default provider is built-in as part of the F<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 L<OSSL_PROVIDER-default(7)>.
+
+=head2 Base provider
+
+The base provider is built in as part of the F<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 L<OSSL_PROVIDER-base(7)>.
+
+=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<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 L</Base provider> will also need to be loaded because the FIPS
+provider does not support the encoding or decoding of keys.
+
+See L<OSSL_PROVIDER-FIPS(7)> and L<fips_module(7)>.
+
+=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<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 L<OSSL_PROVIDER-legacy(7)>.
+
+=head2 Null provider
+
+The null provider is built in as part of the F<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 L<OSSL_PROVIDER-null(7)>.
+
+=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<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 L<config(5)>.
+
+=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<rev> object is passed
+to the I<crl> object. Therefore, after calling this function I<rev> should not
+be freed directly. It will be freed implicitly when I<crl> 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<obj> value where appropriate.
+
+Many OpenSSL functions conform to a naming convention of the form
+B<CLASSNAME_func_name()>. In this naming convention the B<CLASSNAME> is the name
+of an OpenSSL data structure (given in capital letters) that the function is
+primarily operating on. The B<func_name> 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<https://www.openssl.org/source/>). 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<demos> sub-directory.
+
+The Makefiles in the subdirectories give instructions on how to build and run
+the demo applications.
+
+=head1 FURTHER READING
+
+See L<ossl-guide-libcrypto-introduction(7)> for a more detailed introduction to
+using C<libcrypto> and L<ossl-guide-libssl-introduction(7)> for more information
+on C<libssl>.
+
+=head1 SEE ALSO
+
+L<openssl(1)>, L<ssl(7)>, L<evp(7)>, L<OSSL_LIB_CTX(3)>, L<openssl-threads(7)>,
+L<property(7)>, L<OSSL_PROVIDER-default(7)>, L<OSSL_PROVIDER-base(7)>,
+L<OSSL_PROVIDER-FIPS(7)>, L<OSSL_PROVIDER-legacy(7)>, L<OSSL_PROVIDER-null(7)>,
+L<openssl-glossary(7)>, L<provider(7)>
+
+=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<https://www.openssl.org/source/license.html>.
+
+=cut
projects / thirdparty / openssl.git / commitdiff
