.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" 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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . 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 turned on, 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 .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "OSSL-GUIDE-LIBRARIES-INTRODUCTION 7ossl" .TH OSSL-GUIDE-LIBRARIES-INTRODUCTION 7ossl "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 \*(L"\s-1BIO\*(R"\s0 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 \&\s-1SSL/TLS, DTLS\s0 and \s-1QUIC\s0 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 \s-1API\s0 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 \s-1AES\s0). 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 \*(L"built-in\*(R" or in the form of a separate loadable module file (typically one ending in \*(L".so\*(R" or \*(L".dll\*(R" 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 \*(L"default\*(R" provider will be automatically loaded. .PP See \*(L"\s-1OPENSSL PROVIDERS\*(R"\s0 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 \s-1API\s0 functions make use of a library context. A library context can be thought of as a \*(L"scope\*(R" 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 \&\*(L"default\*(R" library context will be used. .PP Library contexts are represented by the \fB\s-1OSSL_LIB_CTX\s0\fR type. Many OpenSSL \s-1API\s0 functions take a library context as a parameter. Applications can always pass \&\fB\s-1NULL\s0\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 \s-1\fIOSSL_LIB_CTX\s0\fR\|(3) for more information about library contexts. See also \*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fIossl\-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 \s-1FIPS\s0 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 \*(L"fetching\*(R". When OpenSSL fetches an algorithm to use it is possible to specify a \*(L"property query string\*(R" to guide the selection process. For example a property query string of \*(L"provider=default\*(R" 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 \fIEVP_set_default_properties\fR\|(3) or \&\fIEVP_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 \*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fIossl\-guide\-libcrypto\-introduction\fR\|(7) for more information about fetching. See \fIproperty\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 \fIBIO_write\fR\|(3) and \fIBIO_read\fR\|(3) functions are thread safe. However it would not be thread safe to call \fIBIO_write()\fR from one thread while calling \&\fIBIO_read()\fR in another where both functions are passed the same \fB\s-1BIO\s0\fR object since both of them may attempt to make changes to the same \fB\s-1BIO\s0\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 \fB\s-1OSSL_LIB_CTX\s0\fR in multiple threads. .PP See \fIopenssl\-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 \s-1NULL\s0 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 \&\fIERR_get_error\fR\|(3) for information about the functions available for querying error data. Also see \fIERR_print_errors\fR\|(3) for information on some simple helper functions for printing error data. Finally look at \fIERR_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 \fIopenssl\-list\fR\|(1) command can be used to list the currently available algorithms. .PP The names of the algorithms shown from \fIopenssl\-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 \fIprovider\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 \*(L"provider=default\*(R" 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 \*(L"default\*(R" provider will be automatically loaded. If you explicitly load any provider then the \*(L"default\*(R" provider would also need to be explicitly loaded if it is required. .PP See \fIOSSL_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 \&\*(L"provider=base\*(R" can be used as a search criterion for these implementations. Some encoding and decoding algorithm implementations are not \s-1FIPS\s0 algorithm implementations in themselves but support algorithms from the \s-1FIPS\s0 provider and are allowed for use in \*(L"\s-1FIPS\s0 mode\*(R". The property query string \*(L"fips=yes\*(R" can be used to select such algorithms. .PP See \fIOSSL_PROVIDER\-base\fR\|(7). .SS "\s-1FIPS\s0 provider" .IX Subsection "FIPS provider" The \s-1FIPS\s0 provider is a dynamically loadable module, and must therefore be loaded explicitly, either in code or through OpenSSL configuration (see \fIconfig\fR\|(5)). It contains algorithm implementations that have been validated according to \s-1FIPS\s0 standards. Should it be needed (if other providers are loaded and offer implementations of the same algorithms), the property query string \*(L"provider=fips\*(R" can be used as a search criterion for these implementations. All approved algorithm implementations in the \s-1FIPS\s0 provider can also be selected with the property \*(L"fips=yes\*(R". The \s-1FIPS\s0 provider may also contain non-approved algorithm implementations and these can be selected with the property \*(L"fips=no\*(R". .PP Typically the \*(L"Base provider\*(R" will also need to be loaded because the \s-1FIPS\s0 provider does not support the encoding or decoding of keys. .PP See \s-1\fIOSSL_PROVIDER\-FIPS\s0\fR\|(7) and \fIfips_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 \fIconfig\fR\|(5)). It contains algorithm implementations that are considered insecure, or are no longer in common use such as \s-1MD2\s0 or \s-1RC4.\s0 Should it be needed (if other providers are loaded and offer implementations of the same algorithms), the property \*(L"provider=legacy\*(R" can be used as a search criterion for these implementations. .PP See \fIOSSL_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 \s-1API\s0 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 \fIOSSL_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 \fIOSSL_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 \fIconfig\fR\|(5). .SH "LIBRARY CONVENTIONS" .IX Header "LIBRARY CONVENTIONS" Many OpenSSL functions that \*(L"get\*(R" or \*(L"set\*(R" a value follow a naming convention using the numbers \fB0\fR and \fB1\fR, i.e. \*(L"get0\*(R", \*(L"get1\*(R", \*(L"set0\*(R" and \*(L"set1\*(R". This can also apply to some functions that \*(L"add\*(R" a value to an existing set, i.e. \&\*(L"add0\*(R" and \*(L"add1\*(R". .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 \&\fIX509_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 \*(L"up ref\*(R" of the object is performed. So after calling the \fIX509_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 \&\fB\f(BICLASSNAME_func_name()\fB\fR. In this naming convention the \fB\s-1CLASSNAME\s0\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 \s-1API\s0 functions. To look at them download the OpenSSL source code from the OpenSSL website (). 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 \fIossl\-guide\-libcrypto\-introduction\fR\|(7) for a more detailed introduction to using \f(CW\*(C`libcrypto\*(C'\fR and \fIossl\-guide\-libssl\-introduction\fR\|(7) for more information on \f(CW\*(C`libssl\*(C'\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIopenssl\fR\|(1), \fIssl\fR\|(7), \fIevp\fR\|(7), \s-1\fIOSSL_LIB_CTX\s0\fR\|(3), \fIopenssl\-threads\fR\|(7), \&\fIproperty\fR\|(7), \fIOSSL_PROVIDER\-default\fR\|(7), \fIOSSL_PROVIDER\-base\fR\|(7), \&\s-1\fIOSSL_PROVIDER\-FIPS\s0\fR\|(7), \fIOSSL_PROVIDER\-legacy\fR\|(7), \fIOSSL_PROVIDER\-null\fR\|(7), \&\fIopenssl\-glossary\fR\|(7), \fIprovider\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 \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at .