diff options
Diffstat (limited to 'upstream/archlinux/man7/ossl-guide-libraries-introduction.7ssl')
| -rw-r--r-- | upstream/archlinux/man7/ossl-guide-libraries-introduction.7ssl | 372 |
1 files changed, 372 insertions, 0 deletions
diff --git a/upstream/archlinux/man7/ossl-guide-libraries-introduction.7ssl b/upstream/archlinux/man7/ossl-guide-libraries-introduction.7ssl new file mode 100644 index 00000000..8b26dae4 --- /dev/null +++ b/upstream/archlinux/man7/ossl-guide-libraries-introduction.7ssl @@ -0,0 +1,372 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-LIBRARIES-INTRODUCTION 7ssl" +.TH OSSL-GUIDE-LIBRARIES-INTRODUCTION 7ssl 2024-01-30 3.2.1 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ossl\-guide\-libraries\-introduction +\&\- OpenSSL Guide: An introduction to the OpenSSL libraries +.SH INTRODUCTION +.IX Header "INTRODUCTION" +OpenSSL supplies two libraries that can be used by applications known as +\&\f(CW\*(C`libcrypto\*(C'\fR and \f(CW\*(C`libssl\*(C'\fR. +.PP +The \f(CW\*(C`libcrypto\*(C'\fR 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. +.PP +The \f(CW\*(C`libssl\*(C'\fR 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. +.PP +The \f(CW\*(C`libssl\*(C'\fR library depends on and uses many of the capabilities supplied by +\&\f(CW\*(C`libcrypto\*(C'\fR. Any application linked against \f(CW\*(C`libssl\*(C'\fR will also link against +\&\f(CW\*(C`libcrypto\*(C'\fR, and most applications that do this will directly use API functions +supplied by both libraries. +.PP +Applications may be written that only use \f(CW\*(C`libcrypto\*(C'\fR capabilities and do not +link against \f(CW\*(C`libssl\*(C'\fR at all. +.SH PROVIDERS +.IX Header "PROVIDERS" +As well as the two main libraries, OpenSSL also comes with a set of providers. +.PP +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. +.PP +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 \f(CW\*(C`libcrypto\*(C'\fR or one +that the application has supplied itself directly. Third parties can also supply +providers in the form of loadable modules. +.PP +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. +.PP +See "OPENSSL PROVIDERS" below for a description of the providers that OpenSSL +itself supplies. +.PP +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. +.SH "LIBRARY CONTEXTS" +.IX Header "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. +.PP +If an application does not explicitly create a library context then the +"default" library context will be used. +.PP +Library contexts are represented by the \fBOSSL_LIB_CTX\fR type. Many OpenSSL API +functions take a library context as a parameter. Applications can always pass +\&\fBNULL\fR for this parameter to just use the default library context. +.PP +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. +.PP +Similarly when the application exits, the default library context is +automatically destroyed. No explicit de-initialisation steps need to be taken. +.PP +See \fBOSSL_LIB_CTX\fR\|(3) for more information about library contexts. +See also "ALGORITHM FETCHING" in \fBossl\-guide\-libcrypto\-introduction\fR\|(7). +.SH "PROPERTY QUERY STRINGS" +.IX Header "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. +.PP +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. +.PP +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 \fBEVP_set_default_properties\fR\|(3) or +\&\fBEVP_default_properties_enable_fips\fR\|(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. +.PP +See "ALGORITHM FETCHING" in \fBossl\-guide\-libcrypto\-introduction\fR\|(7) for more +information about fetching. See \fBproperty\fR\|(7) for more information about +properties. +.SH "MULTI-THREADED APPLICATIONS" +.IX Header "MULTI-THREADED APPLICATIONS" +As long as OpenSSL has been built with support for threads (the default case +on most platforms) then most OpenSSL \fIfunctions\fR 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 \fIdata structures\fR are not thread-safe. For example +the \fBBIO_write\fR\|(3) and \fBBIO_read\fR\|(3) functions are thread safe. However it +would not be thread safe to call \fBBIO_write()\fR from one thread while calling +\&\fBBIO_read()\fR in another where both functions are passed the same \fBBIO\fR object +since both of them may attempt to make changes to the same \fBBIO\fR object. +.PP +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 \fBOSSL_LIB_CTX\fR in +multiple threads. +.PP +See \fBopenssl\-threads\fR\|(7) for a more detailed discussion on OpenSSL threading +support. +.SH "ERROR HANDLING" +.IX Header "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). +.PP +Most functions that return a pointer value will return NULL in the event of a +failure. +.PP +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. +.PP +Some functions cannot fail and have a \fBvoid\fR 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). +.PP +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. +.PP +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. +.PP +OpenSSL supplies a set of error handling functions to query the error stack. See +\&\fBERR_get_error\fR\|(3) for information about the functions available for querying +error data. Also see \fBERR_print_errors\fR\|(3) for information on some simple +helper functions for printing error data. Finally look at \fBERR_clear_error\fR\|(3) +for how to clear old errors from the error stack. +.SH "OPENSSL PROVIDERS" +.IX Header "OPENSSL PROVIDERS" +OpenSSL comes with a set of providers. +.PP +The algorithms available in each of these providers may vary due to build time +configuration options. The \fBopenssl\-list\fR\|(1) command can be used to list the +currently available algorithms. +.PP +The names of the algorithms shown from \fBopenssl\-list\fR\|(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. +.PP +As well as the OpenSSL providers third parties can also implement providers. +For information on writing a provider see \fBprovider\fR\|(7). +.SS "Default provider" +.IX Subsection "Default provider" +The default provider is built-in as part of the \fIlibcrypto\fR 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. +.PP +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. +.PP +See \fBOSSL_PROVIDER\-default\fR\|(7). +.SS "Base provider" +.IX Subsection "Base provider" +The base provider is built in as part of the \fIlibcrypto\fR 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. +.PP +See \fBOSSL_PROVIDER\-base\fR\|(7). +.SS "FIPS provider" +.IX Subsection "FIPS provider" +The FIPS provider is a dynamically loadable module, and must therefore +be loaded explicitly, either in code or through OpenSSL configuration +(see \fBconfig\fR\|(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". +.PP +Typically the "Base provider" will also need to be loaded because the FIPS +provider does not support the encoding or decoding of keys. +.PP +See \fBOSSL_PROVIDER\-FIPS\fR\|(7) and \fBfips_module\fR\|(7). +.SS "Legacy provider" +.IX Subsection "Legacy provider" +The legacy provider is a dynamically loadable module, and must therefore +be loaded explicitly, either in code or through OpenSSL configuration +(see \fBconfig\fR\|(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. +.PP +See \fBOSSL_PROVIDER\-legacy\fR\|(7). +.SS "Null provider" +.IX Subsection "Null provider" +The null provider is built in as part of the \fIlibcrypto\fR 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. +.PP +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. +.PP +See \fBOSSL_PROVIDER\-null\fR\|(7). +.SH CONFIGURATION +.IX Header "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 \fBOSSL_LIB_CTX_load_config\fR\|(3) function. +.PP +The configuration file can be used to automatically load providers and set up +default property query strings. +.PP +For information on the OpenSSL configuration file format see \fBconfig\fR\|(5). +.SH "LIBRARY CONVENTIONS" +.IX Header "LIBRARY CONVENTIONS" +Many OpenSSL functions that "get" or "set" a value follow a naming convention +using the numbers \fB0\fR and \fB1\fR, 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". +.PP +For example the functions: +.PP +.Vb 2 +\& int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev); +\& int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj); +.Ve +.PP +In the \fB0\fR 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 +\&\fBX509_CRL_add0_revoked()\fR function above, ownership of the \fIrev\fR object is passed +to the \fIcrl\fR object. Therefore, after calling this function \fIrev\fR should not +be freed directly. It will be freed implicitly when \fIcrl\fR is freed. +.PP +In the \fB1\fR 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 \fBX509_add1_trust_object()\fR function above the application will +still be responsible for freeing the \fIobj\fR value where appropriate. +.PP +Many OpenSSL functions conform to a naming convention of the form +\&\fBCLASSNAME_func_name()\fR. In this naming convention the \fBCLASSNAME\fR is the name +of an OpenSSL data structure (given in capital letters) that the function is +primarily operating on. The \fBfunc_name\fR portion of the name is usually in +lowercase letters and indicates the purpose of the function. +.SH "DEMO APPLICATIONS" +.IX Header "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 \fB.tar.gz\fR file for +the version of OpenSSL that you are using and look at the various files in the +\&\fBdemos\fR sub-directory. +.PP +The Makefiles in the subdirectories give instructions on how to build and run +the demo applications. +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-libcrypto\-introduction\fR\|(7) for a more detailed introduction to +using \f(CW\*(C`libcrypto\*(C'\fR and \fBossl\-guide\-libssl\-introduction\fR\|(7) for more information +on \f(CW\*(C`libssl\*(C'\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\fR\|(1), \fBssl\fR\|(7), \fBevp\fR\|(7), \fBOSSL_LIB_CTX\fR\|(3), \fBopenssl\-threads\fR\|(7), +\&\fBproperty\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7), \fBOSSL_PROVIDER\-base\fR\|(7), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7), \fBOSSL_PROVIDER\-null\fR\|(7), +\&\fBopenssl\-glossary\fR\|(7), \fBprovider\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +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>. |