openssl-env

title: openssl-env(7ossl)

summary: OpenSSL environment variables

text:
# openssl-env(7ossl)

## NAME
openssl-env - OpenSSL environment variables

## DESCRIPTION
The OpenSSL libraries use environment variables to override the compiled-in default paths for various data. To avoid security risks, the environment is usually not consulted when the executable is set-user-ID or set-group-ID.

CTLOG_FILE

Specifies the path to a certificate transparency log list. See CTLOG_STORE_new(3).

OPENSSL

Specifies the path to the openssl executable. Used by the rehash script (see "Script Configuration" in openssl-rehash(1)) and by the CA.pl script (see "NOTES" in CA.pl(1)

OPENSSL_CONF, OPENSSL_CONF_INCLUDE

Specifies the path to a configuration file and the directory for included files. See config(5).

OPENSSL_CONFIG

Specifies a configuration option and filename for the req and ca commands invoked by the CA.pl script. See CA.pl(1).

OPENSSL_ENGINES

Specifies the directory from which dynamic engines are loaded. See openssl-engine(1).

OPENSSL_MALLOC_FD, OPENSSL_MALLOC_FAILURES

If built with debugging, this allows memory allocation to fail. See OPENSSL_malloc(3).

OPENSSL_MODULES

Specifies the directory from which cryptographic providers are loaded. Equivalently, the generic -provider-path command-line option may be used.

OPENSSL_TRACE

By default the OpenSSL trace feature is disabled statically. To enable it, OpenSSL must be built with tracing support, which may be configured like this: "./config enable-trace" Unless OpenSSL tracing support is generally disabled, enable trace output of specific parts of OpenSSL libraries, by name. This output usually makes sense only if you know OpenSSL internals well.

The value of this environment varialble is a comma-separated list of names, with the following available:

TRACE

Traces the OpenSSL trace API itself.

INIT

Traces OpenSSL library initialization and cleanup.

TLS

Traces the TLS/SSL protocol.

TLS_CIPHER

Traces the ciphers used by the TLS/SSL protocol.

CONF

Show details about provider and engine configuration.

ENGINE_TABLE

The function that is used by RSA, DSA (etc) code to select registered ENGINEs, cache defaults and functional references (etc), will generate debugging summaries.

ENGINE_REF_COUNT

Reference counts in the ENGINE structure will be monitored with a line of generated for each change.

PKCS5V2

Traces PKCS#5 v2 key generation.

PKCS12_KEYGEN

Traces PKCS#12 key generation.

PKCS12_DECRYPT

Traces PKCS#12 decryption.

X509V3_POLICY

Generates the complete policy tree at various points during X.509 v3 policy evaluation.

BN_CTX

Traces BIGNUM context operations.

CMP

Traces CMP client and server activity.

STORE

Traces STORE operations.

DECODER

Traces decoder operations.

ENCODER

Traces encoder operations.

REF_COUNT

Traces decrementing certain ASN.1 structure references.

HTTP

Traces the HTTP client and server, such as messages being sent and received.

OPENSSL_WIN32_UTF8

If set, then UI_OpenSSL(3) returns UTF-8 encoded strings, rather than ones encoded in the current code page, and the openssl(1) program also transcodes the command-line parameters from the current code page to UTF-8. This environment variable is only checked on Microsoft Windows platforms.

RANDFILE

The state file for the random number generator. This should not be needed in normal use. See RAND_load_file(3).

SSL_CERT_DIR, SSL_CERT_FILE

Specify the default directory or file containing CA certificates. See SSL_CTX_load_verify_locations(3).

TSGET

Additional arguments for the tsget(1) command.

OPENSSL_ia32cap, OPENSSL_sparcv9cap, OPENSSL_ppccap, OPENSSL_armcap, OPENSSL_s390xcap, OPENSSL_riscvcap

OpenSSL supports a number of different algorithm implementations for various machines and, by default, it determines which to use based on the processor capabilities and run time feature enquiry. These environment variables can be used to exert more control over this selection process. See OPENSSL_ia32cap(3), OPENSSL_s390xcap(3).

NO_PROXY, HTTPS_PROXY, HTTP_PROXY

Specify a proxy hostname. See OSSL_HTTP_parse_url(3).

QLOGDIR

Specifies a QUIC qlog output directory. See openssl-qlog(7).

OSSL_QFILTER

Used to set a QUIC qlog filter specification. See openssl-qlog(7).

## COPYRIGHT
Copyright 2019-2024 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>.


openssl-glossary

package: openssl

title: openssl-glossary(7ossl)

summary: An OpenSSL Glossary

text:
# openssl-glossary(7ossl)

## NAME
openssl-glossary - An OpenSSL Glossary

## DESCRIPTION
Algorithm

Cryptographic primitives such as the SHA256 digest, or AES encryption are referred to in OpenSSL as "algorithms". There can be more than one implementation for any given algorithm available for use. crypto(7)

ASN.1, ASN1

ASN.1 ("Abstract Syntax Notation One") is a notation for describing abstract types and values. It is defined in the ITU-T documents X.680 to X.683: <https://www.itu.int/rec/T-REC-X.680>, <https://www.itu.int/rec/T-REC-X.681>, <https://www.itu.int/rec/T-REC-X.682>, <https://www.itu.int/rec/T-REC-X.683>

Base Provider

An OpenSSL Provider that contains encoders and decoders for OpenSSL keys. All the algorithm implementations in the Base Provider are also available in the Default Provider. OSSL_PROVIDER-base(7)

Decoder

A decoder is a type of algorithm used for decoding keys and parameters from some external format such as PEM or DER. OSSL_DECODER_CTX_new_for_pkey(3)

Default Provider

An OpenSSL Provider that contains the most common OpenSSL algorithm implementations. It is loaded by default if no other provider is available. All the algorithm implementations in the Base Provider are also available in the Default Provider. OSSL_PROVIDER-default(7)

DER ("Distinguished Encoding Rules")

DER is a binary encoding of data, structured according to an ASN.1 specification. This is a common encoding used for cryptographic objects such as private and public keys, certificates, CRLs, ... It is defined in ITU-T document X.690:

<https://www.itu.int/rec/T-REC-X.690>

Encoder

An encoder is a type of algorithm used for encoding keys and parameters to some external format such as PEM or DER. OSSL_ENCODER_CTX_new_for_pkey(3)

Explicit Fetching

Explicit Fetching is a type of Fetching (see Fetching). Explicit Fetching is where a function call is made to obtain an algorithm object representing an implementation such as EVP_MD_fetch(3) or EVP_CIPHER_fetch(3)

Fetching

Fetching is the process of looking through the available algorithm implementations, applying selection criteria (via a property query string), and finally choosing the implementation that will be used. Also see Explicit Fetching and Implicit Fetching.

crypto(7)

FIPS Provider

An OpenSSL Provider that contains OpenSSL algorithm implementations that have been validated according to the FIPS 140-2 standard. OSSL_PROVIDER-FIPS(7)

Implicit Fetching

Implicit Fetching is a type of Fetching (see Fetching). Implicit Fetching is where an algorithm object with no associated implementation is used such as the return value from EVP_sha256(3) or EVP_aes_128_cbc(3). With implicit fetching an implementation is fetched automatically using default selection criteria the first time the algorithm is used.

Legacy Provider

An OpenSSL Provider that contains algorithm implementations that are considered insecure or are no longer in common use. OSSL_PROVIDER-legacy(7)

Library Context

A Library Context in OpenSSL is represented by the type OSSL_LIB_CTX. It can be thought of as a scope within which configuration options apply. If an application does not explicitly create a library context then the "default" one is used. Many OpenSSL functions can take a library context as an argument. A NULL value can always be passed to indicate the default library context. OSSL_LIB_CTX(3)

MSBLOB

MSBLOB is a Microsoft specific binary format for RSA and DSA keys, both private and public. This form is never passphrase protected.

Null Provider

An OpenSSL Provider that contains no algorithm implementations. This can be useful to prevent the default provider from being automatically loaded in a library context. OSSL_PROVIDER-null(7)

Operation

An operation is a group of OpenSSL functions with a common purpose such as encryption, or digesting. crypto(7)

PEM ("Privacy Enhanced Message")

PEM is a format used for encoding of binary content into a mail and ASCII friendly form. The content is a series of base64-encoded lines, surrounded by begin/end markers each on their own line. For example:

```
 -----BEGIN PRIVATE KEY-----
 MIICdg....
 ... bhTQ==
 -----END PRIVATE KEY-----

```

Optional header line(s) may appear after the begin line, and their existence depends on the type of object being written or read.

For all OpenSSL uses, the binary content is expected to be a DER encoded structure.

This is defined in IETF RFC 1421:

<https://tools.ietf.org/html/rfc1421>

PKCS#8

PKCS#8 is a specification of ASN.1 structures that OpenSSL uses for storing or transmitting any private key in a key type agnostic manner. There are two structures worth noting for OpenSSL use, one that contains the key data in unencrypted form (known as "PrivateKeyInfo") and an encrypted wrapper structure (known as "EncryptedPrivateKeyInfo"). This is specified in RFC 5208:

<https://tools.ietf.org/html/rfc5208>

Property

A property is a way of classifying and selecting algorithm implementations. A property is a key/value pair expressed as a string. For example all algorithm implementations in the default provider have the property "provider=default". An algorithm implementation can have multiple properties defined against it. Also see Property Query String.

property(7)

Property Query String

A property query string is a string containing a sequence of properties that can be used to select an algorithm implementation. For example the query string "provider=example,foo=bar" will select algorithms from the "example" provider that have a "foo" property defined for them with a value of "bar". Property Query Strings are used during fetching. See Fetching.

property(7)

Provider

A provider in OpenSSL is a component that groups together algorithm implementations. Providers can come from OpenSSL itself or from third parties. provider(7)

PVK

PVK is a Microsoft specific binary format for RSA and DSA private keys. This form may be passphrase protected.

SubjectPublicKeyInfo

SubjectPublicKeyInfo is an ASN.1 structure that OpenSSL uses for storing and transmitting any public key in a key type agnostic manner. This is specified as part of the specification for certificates, RFC 5280:

<https://tools.ietf.org/html/rfc5280>

## HISTORY
This glossary was added in OpenSSL 3.0.

## COPYRIGHT
Copyright 2020-2022 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>.


openssl-qlog

title: openssl-qlog(7ossl)

summary: OpenSSL qlog tracing functionality

text:
# openssl-qlog(7ossl)

## NAME
openssl-qlog - OpenSSL qlog tracing functionality

## DESCRIPTION
OpenSSL has unstable support for generating logs in the qlog logging format, which can be used to obtain diagnostic data for QUIC connections. The data generated includes information on packets sent and received and the frames contained within them, as well as loss detection and other events.

The qlog output generated by OpenSSL can be used to obtain diagnostic visualisations of a given QUIC connection using tools such as qvis.

WARNING: The output of OpenSSL's qlog functionality uses an unstable format based on a draft specification. qlog output is not subject to any format stability or compatibility guarantees at this time, and will change in incompatible ways in future versions of OpenSSL. See FORMAT STABILITY below for details.

## USAGE
When OpenSSL is built with qlog support, qlog is enabled at run time by setting the standard QLOGDIR environment variable to point to a directory where qlog files should be written. Once set, any QUIC connection established by OpenSSL will have a qlog file written automatically to the specified directory.

Log files are generated in the .sqlog format based on JSON-SEQ (RFC 7464).

The filenames of generated log files under the specified QLOGDIR use the following structure:

```
    {connection_odcid}_{vantage_point_type}.sqlog
```

where {connection_odcid} is the lowercase hexadecimal encoding of a QUIC connection's Original Destination Connection ID, which is the Destination Connection ID used in the header of the first Initial packet sent as part of the connection process, and {vantage_point_type} is either "client" or "server", reflecting the perspective of the endpoint producing the qlog output.

The qlog functionality can be disabled at OpenSSL build time using the no-unstable-qlog configure flag.

## SUPPORTED EVENT TYPES
The following event types are currently supported:

connectivity:connection_started

connectivity:connection_state_updated

connectivity:connection_closed

transport:parameters_set

transport:packet_sent

transport:packet_received

recovery:packet_lost

## FILTERS
By default, all supported event types are logged. The OSSL_QFILTER environment variable can be used to configure a filter specification which determines which event types are to be logged. Each event type can be turned on and off individually. The filter specification is a space-separated list of terms listing event types to enable or disable. The terms are applied in order, thus the effects of later terms override the effects of earlier terms.

### Examples
Here are some example filter specifications:

"*" (or "+*")

Enable all supported qlog event types.

"-*"

Disable all qlog event types.

"* -transport:packet_received"

Enable all qlog event types, but disable the transport:packet_received event type.

"-* transport:packet_sent"

Disable all qlog event types, except for the transport:packet_sent event type.

"-* connectivity:* transport:parameters_set"

Disable all qlog event types, except for transport:parameters_set and all supported event types in the connectivity category.

### Filter Syntax Specification
Formally, the format of the filter specification in ABNF is as follows:

```
    filter              = *filter-term
    filter-term         = add-sub-term
    add-sub-term        = ["-" / "+"] specifier
    specifier           = global-specifier / qualified-specifier
    global-specifier    = wildcard
    qualified-specifier = component-specifier ":" component-specifier
    component-specifier = name / wildcard
    wildcard            = "*"
    name                = 1*(ALPHA / DIGIT / "_" / "-")
```

Filter terms are interpreted as follows:

"+*" (or "*")

Enables all event types.

"-*"

Disables all event types.

"+foo:*" (or "foo:*")

Enables all event types in the foo category.

"-foo:*"

Disables all event types in the foo category.

"+foo:bar" (or "foo:bar")

Enables a specific event type foo:bar.

"-foo:bar"

Disables a specific event type foo:bar.

Partial wildcard matches are not supported at this time.

### Default Configuration
If the OSSL_QFILTER environment variable is not set or set to the empty string, this is equivalent to enabling all event types (i.e., it is equivalent to a filter of "*"). Note that the QLOGDIR environment variable must also be set to enable qlog.

## FORMAT STABILITY
The OpenSSL qlog functionality currently implements a draft version of the qlog specification. Future revisions to the qlog specification in advance of formal standardisation are expected to introduce incompatible and breaking changes to the qlog format. The OpenSSL qlog functionality will transition to producing output in this format in the future once standardisation is complete.

Because of this, the qlog output of OpenSSL will change in incompatible and breaking ways in the future, including in non-major releases of OpenSSL. The qlog output of OpenSSL is considered unstable and not subject to any format stability or compatibility guarantees at this time.

Users of the OpenSSL qlog functionality must be aware that the output may change arbitrarily between releases and that the preservation of compatibility with any given tool between releases is not guaranteed.

### Aims
The OpenSSL draft qlog functionality is primarily intended for use in conjunction with the qvis tool <https://qvis.quictools.info/>. In terms of format compatibility, the output format of the OpenSSL qlog functionality is expected to track what is supported by qvis. As such, future changes to the output of the OpenSSL qlog functionality are expected to track changes in qvis as they occur, and reflect the versions of qlog currently supported by qvis.

This means that prior to the finalisation of the qlog standard, in the event of a disparity between the current draft and what qvis supports, the OpenSSL qlog functionality will generally aim for qvis compatibility over compliance with the latest draft.

As such, OpenSSL's qlog functionality currently implements qlog version 0.3 as defined in draft-ietf-quic-qlog-main-schema-05 and draft-ietf-quic-qlog-quic-events-04. These revisions are intentionally used instead of more recent revisions due to their qvis compatibility.

## LIMITATIONS
The OpenSSL implementation of qlog currently has the following limitations:

- Not all event types defined by the draft specification are implemented.

- Only the JSON-SEQ (.sqlog) output format is supported.

- Only the QLOGDIR environment variable is supported for configuring the qlog output directory. The standard QLOGFILE environment variable is not supported.

- There is no API for programmatically enabling or controlling the qlog functionality.

## SEE ALSO
openssl-quic(7), openssl-env(7)

## HISTORY
This functionality was added in OpenSSL 3.3.

## COPYRIGHT
Copyright 2024 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>.


openssl-quic

title: openssl-quic(7ossl)

summary: OpenSSL QUIC

text:
# openssl-quic(7ossl)

## NAME
openssl-quic - OpenSSL QUIC

## DESCRIPTION
OpenSSL 3.2 and later features support for the QUIC transport protocol. Currently, only client connectivity is supported. This man page describes the usage of QUIC client functionality for both existing and new applications.

QUIC functionality uses the standard SSL API. A QUIC connection is represented by an SSL object in the same way that a TLS connection is. Only minimal changes are needed to existing applications making use of the libssl APIs to make use of QUIC client functionality. To make use of QUIC, use the SSL method OSSL_QUIC_client_method(3) or OSSL_QUIC_client_thread_method(3) with SSL_CTX_new(3).

When a QUIC connection is created, by default, it operates in default stream mode, which is intended to provide compatibility with existing non-QUIC application usage patterns. In this mode, the connection has a single stream associated with it. Calls to SSL_read(3) and SSL_write(3) on the QUIC connection SSL object read and write from that stream. Whether the stream is client-initiated or server-initiated from a QUIC perspective depends on whether SSL_read(3) or SSL_write(3) is called first. See the MODES OF OPERATION section for more information.

The default stream mode is intended for compatibility with existing applications. New applications using QUIC are recommended to disable default stream mode and use the multi-stream API; see the MODES OF OPERATION section and the RECOMMENDATIONS FOR NEW APPLICATIONS section for more information.

The remainder of this man page discusses, in order:

- Default stream mode versus multi-stream mode;

- The changes to existing libssl APIs which are driven by QUIC-related implementation requirements, which existing applications should bear in mind;

- Aspects which must be considered by existing applications when adopting QUIC, including potential changes which may be needed.

- Recommended usage approaches for new applications.

- New, QUIC-specific APIs.

## MODES OF OPERATION

### Default Stream Mode
A QUIC client connection can be used in either default stream mode or multi-stream mode. By default, a newly created QUIC connection SSL object uses default stream mode.

In default stream mode, a stream is implicitly created and bound to the QUIC connection SSL object; SSL_read(3) and SSL_write(3) calls to the QUIC connection SSL object work by default and are mapped to that stream.

When default stream mode is used, any API function which can be called on a QUIC stream SSL object can also be called on a QUIC connection SSL object, in which case it affects the default stream bound to the connection.

The identity of a QUIC stream, including its stream ID, varies depending on whether a stream is client-initiated or server-initiated. In default stream mode, if a client application calls SSL_read(3) first before any call to SSL_write(3) on the connection, it is assumed that the application protocol is using a server-initiated stream, and the SSL_read(3) call will not complete (either blocking, or failing appropriately if nonblocking mode is configured) until the server initiates a stream. Conversely, if the client application calls SSL_write(3) before any call to SSL_read(3) on the connection, it is assumed that a client-initiated stream is to be used and such a stream is created automatically.

Default stream mode is intended to aid compatibility with legacy applications. New applications adopting QUIC should use multi-stream mode, described below, and avoid use of the default stream functionality.

It is possible to use additional streams in default stream mode using SSL_new_stream(3) and SSL_accept_stream(3); note that the default incoming stream policy will need to be changed using SSL_set_incoming_stream_policy(3) in order to use SSL_accept_stream(3) in this case. However, applications using additional streams are strongly recommended to use multi-stream mode instead.

Calling SSL_new_stream(3) or SSL_accept_stream(3) before a default stream has been associated with the QUIC connection SSL object will inhibit future creation of a default stream.

### Multi-Stream Mode
The recommended usage mode for new applications adopting QUIC is multi-stream mode, in which no default stream is attached to the QUIC connection SSL object and attempts to call SSL_read(3) and SSL_write(3) on the QUIC connection SSL object fail. Instead, an application calls SSL_new_stream(3) or SSL_accept_stream(3) to create individual stream SSL objects for sending and receiving application data using SSL_read(3) and SSL_write(3).

To use multi-stream mode, call SSL_set_default_stream_mode(3) with an argument of SSL_DEFAULT_STREAM_MODE_NONE; this function must be called prior to initiating the connection. The default stream mode cannot be changed after initiating a connection.

When multi-stream mode is used, meaning that no default stream is associated with the connection, calls to API functions which are defined as operating on a QUIC stream fail if called on the QUIC connection SSL object. For example, calls such as SSL_write(3) or SSL_get_stream_id(3) will fail.

## CHANGES TO EXISTING APIS
Most SSL APIs, such as SSL_read(3) and SSL_write(3), function as they do for TLS connections and do not have changed semantics, with some exceptions. The changes to the semantics of existing APIs are as follows:

•

Since QUIC uses UDP, SSL_set_bio(3), SSL_set0_rbio(3) and SSL_set0_wbio(3) function as before, but must now receive a BIO with datagram semantics. There are broadly four options for applications to use as a network BIO:

- BIO_s_datagram(3), recommended for most applications, replaces BIO_s_socket(3) and provides a UDP socket.

- BIO_s_dgram_pair(3) provides BIO pair-like functionality but with datagram semantics, and is recommended for existing applications which use a BIO pair or memory BIO to manage libssl's communication with the network.

- BIO_s_dgram_mem(3) provides a simple memory BIO-like interface but with datagram semantics. Unlike BIO_s_dgram_pair(3), it is unidirectional.

- An application may also choose to implement a custom BIO. The new BIO_sendmmsg(3) and BIO_recvmmsg(3) APIs must be supported.

- SSL_set_fd(3), SSL_set_rfd(3) and SSL_set_wfd(3) traditionally instantiate a BIO_s_socket(3). For QUIC, these functions instead instantiate a BIO_s_datagram(3). This is equivalent to instantiating a BIO_s_datagram(3) and using SSL_set0_rbio(3) and SSL_set0_wbio(3).

- Traditionally, whether the application-level I/O APIs (such as SSL_read(3) and SSL_write(3) operated in a blocking fashion was directly correlated with whether the underlying network socket was configured in a blocking fashion. This is no longer the case; applications must explicitly configure the desired application-level blocking mode using SSL_set_blocking_mode(3). See SSL_set_blocking_mode(3) for details.

- Network-level I/O must always be performed in a nonblocking manner. The application can still enjoy blocking semantics for calls to application-level I/O functions such as SSL_read(3) and SSL_write(3), but the underlying network BIO provided to QUIC (such as a BIO_s_datagram(3)) must be configured in nonblocking mode. For application-level blocking functionality, see SSL_set_blocking_mode(3).

- BIO_new_ssl_connect(3) has been changed to automatically use a BIO_s_datagram(3) when used with QUIC, therefore applications which use this do not need to change the BIO they use.

- BIO_new_buffer_ssl_connect(3) cannot be used with QUIC and applications must change to use BIO_new_ssl_connect(3) instead.

- SSL_shutdown(3) has significant changes in relation to how QUIC connections must be shut down. In particular, applications should be advised that the full RFC-conformant QUIC shutdown process may take an extended amount of time. This may not be suitable for short-lived processes which should exit immediately after their usage of a QUIC connection is completed. A rapid shutdown mode is available for such applications. For details, see SSL_shutdown(3).

- SSL_want(3), SSL_want_read(3) and SSL_want_write(3) no longer reflect the I/O state of the network BIO passed to the QUIC SSL object, but instead reflect the flow control state of the QUIC stream associated with the SSL object. When used in nonblocking mode, SSL_ERROR_WANT_READ indicates that the receive part of a QUIC stream does not currently have any more data available to be read, and SSL_ERROR_WANT_WRITE indicates that the stream's internal buffer is full.

To determine if the QUIC implementation currently wishes to be informed of incoming network datagrams, use the new function SSL_net_read_desired(3); likewise, to determine if the QUIC implementation currently wishes to be informed when it is possible to transmit network datagrams, use the new function SSL_net_write_desired(3). Only applications which wish to manage their own event loops need to use these functions; see APPLICATION-DRIVEN EVENT LOOPS for further discussion.

- The use of ALPN is mandatory when using QUIC. Attempts to connect without configuring ALPN will fail. For information on how to configure ALPN, see SSL_set_alpn_protos(3).

- Whether QUIC operates in a client or server mode is determined by the SSL_METHOD used, rather than by calls to SSL_set_connect_state(3) or SSL_set_accept_state(3). It is not necessary to call either of SSL_set_connect_state(3) or SSL_set_accept_state(3) before connecting, but if either of these are called, the function called must be congruent with the SSL_METHOD being used. Currently, only client mode is supported.

- The SSL_set_min_proto_version(3) and SSL_set_max_proto_version(3) APIs are not used and the values passed to them are ignored, as OpenSSL QUIC currently always uses TLS 1.3.

- The following libssl functionality is not available when used with QUIC.

- Async functionality

- SSL_MODE_AUTO_RETRY

- Record Padding and Fragmentation (SSL_set_block_padding(3), etc.)

- SSL_stateless(3) support

- SRTP functionality

- TLSv1.3 Early Data

- TLS Next Protocol Negotiation cannot be used and is superseded by ALPN, which must be used instead. The use of ALPN is mandatory with QUIC.

- Post-Handshake Client Authentication is not available as QUIC prohibits its use.

- QUIC requires the use of TLSv1.3 or later, therefore functionality only relevant to older TLS versions is not available.

- Some cipher suites which are generally available for TLSv1.3 are not available for QUIC, such as TLS_AES_128_CCM_8_SHA256. Your application may need to adjust the list of acceptable cipher suites it passes to libssl.

- CCM mode is not currently supported.

The following libssl functionality is also not available when used with QUIC, but calls to the relevant functions are treated as no-ops:

•

Readahead (SSL_set_read_ahead(3), etc.)

## CONSIDERATIONS FOR EXISTING APPLICATIONS
Existing applications seeking to adopt QUIC should apply the following list to determine what changes they will need to make:

- An application wishing to use QUIC must use OSSL_QUIC_client_method(3) or OSSL_QUIC_client_thread_method(3) as its SSL method. For more information on the differences between these two methods, see THREAD ASSISTED MODE.

- Determine how to provide QUIC with network access. Determine which of the below apply for your application:

- Your application uses BIO_s_socket(3) to construct a BIO which is passed to the SSL object to provide it with network access. Changes needed: Change your application to use BIO_s_datagram(3) instead when using QUIC. The socket must be configured in nonblocking mode. You may or may not need to use SSL_set1_initial_peer_addr(3) to set the initial peer address; see the QUIC-SPECIFIC APIS section for details.

- Your application uses BIO_new_ssl_connect(3) to construct a BIO which is passed to the SSL object to provide it with network access. Changes needed: No changes needed. Use of QUIC is detected automatically and a datagram socket is created instead of a normal TCP socket.

- Your application uses any other I/O strategy in this list but combines it with a BIO_f_buffer(3), for example using BIO_push(3). Changes needed: Disable the usage of BIO_f_buffer(3) when using QUIC. Usage of such a buffer is incompatible with QUIC as QUIC requires datagram semantics in its interaction with the network.

- Your application uses a BIO pair to cause the SSL object to read and write network traffic to a memory buffer. Your application manages the transmission and reception of buffered data itself in a way unknown to libssl. Changes needed: Switch from using a conventional BIO pair to using BIO_s_dgram_pair(3) instead, which has the necessary datagram semantics. You will need to modify your application to transmit and receive using a UDP socket and to use datagram semantics when interacting with the BIO_s_dgram_pair(3) instance.

- Your application uses a custom BIO method to provide the SSL object with network access. Changes needed: The custom BIO must be re-architected to have datagram semantics. BIO_sendmmsg(3) and BIO_recvmmsg(3) must be implemented. These calls must operate in a nonblocking fashion. Optionally, implement the BIO_get_rpoll_descriptor(3) and BIO_get_wpoll_descriptor(3) methods if desired. Implementing these methods is required if blocking semantics at the SSL API level are desired.

- An application must explicitly configure whether it wishes to use the SSL APIs in blocking mode or not. Traditionally, an SSL object has automatically operated in blocking or nonblocking mode based on whether the underlying network BIO operates in blocking or nonblocking mode. QUIC requires the use of a nonblocking network BIO, therefore the blocking mode at the application level must be explicitly configured by the application using the new SSL_set_blocking_mode(3) API. The default mode is blocking. If an application wishes to use the SSL object APIs at application level in a nonblocking manner, it must add a call to SSL_set_blocking_mode(3) to disable blocking mode.

- If your application does not choose to use thread assisted mode, it must ensure that it calls an I/O function on the SSL object (for example, SSL_read(3) or SSL_write(3)), or the new function SSL_handle_events(3), regularly. If the SSL object is used in blocking mode, an ongoing blocking call to an I/O function satisfies this requirement. This is required to ensure that timer events required by QUIC are handled in a timely fashion. Most applications will service the SSL object by calling SSL_read(3) or SSL_write(3) regularly. If an application does not do this, it should ensure that SSL_handle_events(3) is called regularly.

SSL_get_event_timeout(3) can be used to determine when SSL_handle_events(3) must next be called.

If the SSL object is being used with an underlying network BIO which is pollable (such as BIO_s_datagram(3)), the application can use SSL_get_rpoll_descriptor(3), SSL_get_wpoll_descriptor(3) to obtain resources which can be used to determine when SSL_handle_events(3) should be called due to network I/O.

Applications which use thread assisted mode do not need to be concerned with this requirement, as the QUIC implementation ensures timeout events are handled in a timely manner. See THREAD ASSISTED MODE for details.

- Ensure that your usage of SSL_want(3), SSL_want_read(3) and SSL_want_write(3) reflects the API changes described in CHANGES TO EXISTING APIS. In particular, you should use these APIs to determine the ability of a QUIC stream to receive or provide application data, not to to determine if network I/O is required.

- Evaluate your application's use of SSL_shutdown(3) in light of the changes discussed in CHANGES TO EXISTING APIS. Depending on whether your application wishes to prioritise RFC conformance or rapid shutdown, consider using the new SSL_shutdown_ex(3) API instead. See QUIC-SPECIFIC APIS for details.

## RECOMMENDED USAGE IN NEW APPLICATIONS
The recommended usage in new applications varies depending on three independent design decisions:

- Whether the application will use blocking or nonblocking I/O at the application level (configured using SSL_set_blocking_mode(3)). If the application does nonblocking I/O at the application level it can choose to manage its own polling and event loop; see APPLICATION-DRIVEN EVENT LOOPS.

- Whether the application intends to give the QUIC implementation direct access to a network socket (e.g. via BIO_s_datagram(3)) or whether it intends to buffer transmitted and received datagrams via a BIO_s_dgram_pair(3) or custom BIO. The former is preferred where possible as it reduces latency to the network, which enables QUIC to achieve higher performance and more accurate connection round trip time (RTT) estimation.

- Whether thread assisted mode will be used (see THREAD ASSISTED MODE).

Simple demos for QUIC usage under these various scenarios can be found at <https://github.com/openssl/openssl/tree/master/doc/designs/ddd>.

Applications which wish to implement QUIC-specific protocols should be aware of the APIs listed under QUIC-SPECIFIC APIS which provide access to QUIC-specific functionality. For example, SSL_stream_conclude(3) can be used to indicate the end of the sending part of a stream, and SSL_shutdown_ex(3) can be used to provide a QUIC application error code when closing a connection.

Regardless of the design decisions chosen above, it is recommended that new applications avoid use of the default stream mode and use the multi-stream API by calling SSL_set_default_stream_mode(3); see the MODES OF OPERATION section for details.

## QUIC-SPECIFIC APIS
This section details new APIs which are directly or indirectly related to QUIC. For details on the operation of each API, see the referenced man pages.

The following SSL APIs are new but relevant to both QUIC and DTLS:

SSL_get_event_timeout(3)

Determines when the QUIC implementation should next be woken up via a call to SSL_handle_events(3) (or another I/O function such as SSL_read(3) or SSL_write(3)), if ever. This can also be used with DTLS and supersedes DTLSv1_get_timeout(3) for new usage.

SSL_handle_events(3)

This is a non-specific I/O operation which makes a best effort attempt to perform any pending I/O or timeout processing. It can be used to advance the QUIC state machine by processing incoming network traffic, generating outgoing network traffic and handling any expired timeout events. Most other I/O functions on an SSL object, such as SSL_read(3) and SSL_write(3) implicitly perform event handling on the SSL object, so calling this function is only needed if no other I/O function is to be called. This can also be used with DTLS and supersedes DTLSv1_handle_timeout(3) for new usage.

The following SSL APIs are specific to QUIC:

SSL_set_blocking_mode(3), SSL_get_blocking_mode(3)

Configures whether blocking semantics are used at the application level. This determines whether calls to functions such as SSL_read(3) and SSL_write(3) will block.

SSL_get_rpoll_descriptor(3), SSL_get_wpoll_descriptor(3)

These functions facilitate operation in nonblocking mode. When an SSL object is being used with an underlying network read BIO which supports polling, SSL_get_rpoll_descriptor(3) outputs an OS resource which can be used to synchronise on network readability events which should result in a call to SSL_handle_events(3). SSL_get_wpoll_descriptor(3) works in an analogous fashion for the underlying network write BIO.

The poll descriptors provided by these functions need only be used when SSL_net_read_desired(3) and SSL_net_write_desired(3) return 1, respectively.

SSL_net_read_desired(3), SSL_net_write_desired(3)

These functions facilitate operation in nonblocking mode and are used in conjunction with SSL_get_rpoll_descriptor(3) and SSL_get_wpoll_descriptor(3) respectively. They determine whether the respective poll descriptor is currently relevant for the purposes of polling.

SSL_set1_initial_peer_addr(3)

This function can be used to set the initial peer address for an outgoing QUIC connection. This function must be used in the general case when creating an outgoing QUIC connection; however, the correct initial peer address can be autodetected in some cases. See SSL_set1_initial_peer_addr(3) for details.

SSL_shutdown_ex(3)

This augments SSL_shutdown(3) by allowing an application error code to be specified. It also allows a client to decide how quickly it wants a shutdown to be performed, potentially by trading off strict RFC compliance.

SSL_stream_conclude(3)

This allows an application to indicate the normal end of the sending part of a QUIC stream. This corresponds to the FIN flag in the QUIC RFC. The receiving part of a stream remains usable.

SSL_stream_reset(3)

This allows an application to indicate the non-normal termination of the sending part of a stream. This corresponds to the RESET_STREAM frame in the QUIC RFC.

SSL_get_stream_write_state(3) and SSL_get_stream_read_state(3)

This allows an application to determine the current stream states for the sending and receiving parts of a stream respectively.

SSL_get_stream_write_error_code(3) and SSL_get_stream_read_error_code(3)

This allows an application to determine the application error code which was signalled by a peer which has performed a non-normal stream termination of the respective sending or receiving part of a stream, if any.

SSL_get_conn_close_info(3)

This allows an application to determine the error code which was signalled when the local or remote endpoint terminated the QUIC connection.

SSL_get0_connection(3)

Gets the QUIC connection SSL object from a QUIC stream SSL object.

SSL_is_connection(3)

Returns 1 if a SSL object is not a QUIC stream SSL object.

SSL_get_stream_type(3)

Provides information on the kind of QUIC stream which is attached to the SSL object.

SSL_get_stream_id(3)

Returns the QUIC stream ID which the QUIC protocol has associated with a QUIC stream.

SSL_new_stream(3)

Creates a new QUIC stream SSL object representing a new, locally-initiated QUIC stream.

SSL_accept_stream(3)

Potentially yields a new QUIC stream SSL object representing a new remotely-initiated QUIC stream, blocking until one is available if the connection is configured to do so.

SSL_get_accept_stream_queue_len(3)

Provides information on the number of pending remotely-initiated streams.

SSL_set_incoming_stream_policy(3)

Configures how incoming, remotely-initiated streams are handled. The incoming stream policy can be used to automatically reject streams created by the peer, or allow them to be handled using SSL_accept_stream(3).

SSL_set_default_stream_mode(3)

Used to configure or disable default stream mode; see the MODES OF OPERATION section for details.

The following BIO APIs are not specific to QUIC but have been added to facilitate QUIC-specific requirements and are closely associated with its use:

BIO_s_dgram_pair(3)

This is a new BIO method which is similar to a conventional BIO pair but provides datagram semantics.

BIO_get_rpoll_descriptor(3), BIO_get_wpoll_descriptor(3)

This is a new BIO API which allows a BIO to expose a poll descriptor. This API is used to implement the corresponding SSL APIs SSL_get_rpoll_descriptor(3) and SSL_get_wpoll_descriptor(3).

BIO_sendmmsg(3), BIO_recvmmsg(3)

This is a new BIO API which can be implemented by BIOs which implement datagram semantics. It is implemented by BIO_s_datagram(3) and BIO_s_dgram_pair(3). It is used by the QUIC implementation to send and receive UDP datagrams.

BIO_dgram_set_no_trunc(3), BIO_dgram_get_no_trunc(3)

By default, BIO_s_dgram_pair(3) has semantics comparable to those of Berkeley sockets being used with datagram semantics. This allows an alternative mode to be enabled in which datagrams will not be silently truncated if they are too large.

BIO_dgram_set_caps(3), BIO_dgram_get_caps(3)

These functions are used to allow the user of one end of a BIO_s_dgram_pair(3) to indicate its capabilities to the other end of a BIO_s_dgram_pair(3). In particular, this allows an application to inform the QUIC implementation of whether it is prepared to handle local and/or peer addresses in transmitted datagrams and to provide the applicable information in received datagrams.

BIO_dgram_get_local_addr_cap(3), BIO_dgram_set_local_addr_enable(3), BIO_dgram_get_local_addr_enable(3)

Local addressing support refers to the ability of a BIO with datagram semantics to allow a source address to be specified on transmission and to report the destination address on reception. These functions can be used to determine if a BIO can support local addressing and to enable local addressing support if it can.

BIO_err_is_non_fatal(3)

This is used to determine if an error while calling BIO_sendmmsg(3) or BIO_recvmmsg(3) is ephemeral in nature, such as "would block" errors.

## THREAD ASSISTED MODE
The optional thread assisted mode can be used with OSSL_QUIC_client_thread_method(3). In this mode, a background thread is created automatically. The OpenSSL QUIC implementation then takes responsibility for ensuring that timeout events are handled on a timely basis even if no SSL I/O function such as SSL_read(3) or SSL_write(3) is called by the application for a long time.

All necessary locking is handled automatically internally, but the thread safety guarantees for the public SSL API are unchanged. Therefore, an application must still do its own locking if it wishes to make concurrent use of the public SSL APIs.

Because this method relies on threads, it is not available on platforms where threading support is not available or not supported by OpenSSL. However, it does provide the simplest mode of usage for an application.

The implementation may or may not use a common thread or thread pool to service multiple SSL objects in the same SSL_CTX.

## APPLICATION-DRIVEN EVENT LOOPS
OpenSSL's QUIC implementation is designed to facilitate applications which wish to use the SSL APIs in a blocking fashion, but is also designed to facilitate applications which wish to use the SSL APIs in a nonblocking fashion and manage their own event loops and polling directly. This is useful when it is desirable to host OpenSSL's QUIC implementation on top of an application's existing nonblocking I/O infrastructure.

This is supported via the concept of poll descriptors; see BIO_get_rpoll_descriptor(3) for details. Broadly, a BIO_POLL_DESCRIPTOR is a structure which expresses some kind of OS resource which can be used to synchronise on I/O events. The QUIC implementation provides a BIO_POLL_DESCRIPTOR based on the poll descriptor provided by the underlying network BIO. This is typically an OS socket handle, though custom BIOs could choose to implement their own custom poll descriptor format.

Broadly, an application which wishes to manage its own event loop should interact with the SSL object as follows:

- It should provide read and write BIOs with nonblocking datagram semantics to the SSL object using SSL_set0_rbio(3) and SSL_set0_wbio(3). This could be a BIO abstracting a network socket such as BIO_s_datagram(3), or a BIO abstracting some kind of memory buffer such as BIO_s_dgram_pair(3). Use of a custom BIO is also possible.

- It should configure the SSL object into nonblocking mode by calling SSL_set_blocking_mode(3).

- It should configure the SSL object as desired, set an initial peer as needed using SSL_set1_initial_peer_addr(3), and trigger the connection process by calling SSL_connect(3).

- If the network read and write BIOs provided were pollable (for example, a BIO_s_datagram(3), or a custom BIO which implements BIO_get_rpoll_descriptor(3) and BIO_get_wpoll_descriptor(3)), it should perform the following steps repeatedly:

- The application should call SSL_get_rpoll_descriptor(3) and SSL_get_wpoll_descriptor(3) to identify OS resources which can be used for synchronisation.

- It should call SSL_net_read_desired(3) and SSL_net_write_desired(3) to determine whether the QUIC implementation is currently interested in readability and writability events on the underlying network BIO which was provided, and call SSL_get_event_timeout(3) to determine if any timeout event will become applicable in the future.

- It should wait until one of the following events occurs:

- The poll descriptor returned by SSL_get_rpoll_descriptor(3) becomes readable (if SSL_net_read_desired(3) returned 1);

- The poll descriptor returned by SSL_get_wpoll_descriptor(3) becomes writable (if SSL_net_write_desired(3) returned 1);

- The timeout returned by SSL_get_event_timeout(3) (if any) expires.

Once any of these events occurs, SSL_handle_events(3) should be called.

•

If the network read and write BIOs provided were not pollable (for example, in the case of BIO_s_dgram_pair(3)), the application is responsible for managing and synchronising network I/O. It should call SSL_handle_events(3) after it writes data to a BIO_s_dgram_pair(3) or otherwise takes action so that the QUIC implementation can read new datagrams via a call to BIO_recvmmsg(3) on the underlying network BIO. The QUIC implementation may output datagrams via a call to BIO_sendmmsg(3) and the application is responsible for ensuring these are transmitted. The application must call SSL_get_event_timeout(3) after every call to SSL_handle_events(3) (or another I/O function on the SSL object), and ensure that a call to SSL_handle_events(3) is performed after the specified timeout (if any).

## SEE ALSO
SSL_handle_events(3), SSL_get_event_timeout(3), SSL_net_read_desired(3), SSL_net_write_desired(3), SSL_get_rpoll_descriptor(3), SSL_get_wpoll_descriptor(3), SSL_set_blocking_mode(3), SSL_shutdown_ex(3), SSL_set1_initial_peer_addr(3), SSL_stream_conclude(3), SSL_stream_reset(3), SSL_get_stream_read_state(3), SSL_get_stream_read_error_code(3), SSL_get_conn_close_info(3), SSL_get0_connection(3), SSL_get_stream_type(3), SSL_get_stream_id(3), SSL_new_stream(3), SSL_accept_stream(3), SSL_set_incoming_stream_policy(3), SSL_set_default_stream_mode(3)

## COPYRIGHT
Copyright 2022-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>.


openssl-threads

title: openssl-threads(7ossl)

summary: Overview of thread safety in OpenSSL

text:
# openssl-threads(7ossl)

## NAME
openssl-threads - Overview of thread safety in OpenSSL

## DESCRIPTION
In this man page, we use the term thread-safe to indicate that an object or function can be used by multiple threads at the same time.

OpenSSL can be built with or without threads support. The most important use of this support is so that OpenSSL itself can use a single consistent API, as shown in "EXAMPLES" in CRYPTO_THREAD_run_once(3). Multi-platform applications can also use this API.

In particular, being configured for threads support does not imply that all OpenSSL objects are thread-safe. To emphasize: most objects are not safe for simultaneous use. Exceptions to this should be documented on the specific manual pages, and some general high-level guidance is given here.

One major use of the OpenSSL thread API is to implement reference counting. Many objects within OpenSSL are reference-counted, so resources are not released, until the last reference is removed. References are often increased automatically (such as when an X509 certificate object is added into an X509_STORE trust store). There is often an object_up_ref() function that can be used to increase the reference count. Failure to match object_up_ref() calls with the right number of object_free() calls is a common source of memory leaks when a program exits.

Many objects have set and get API's to set attributes in the object. A "set0" passes ownership from the caller to the object and a "get0" returns a pointer but the attribute ownership remains with the object and a reference to it is returned. A "set1" or "get1" function does not change the ownership, but instead updates the attribute's reference count so that the object is shared between the caller and the object; the caller must free the returned attribute when finished. Functions that involve attributes that have reference counts themselves, but are named with just "set" or "get" are historical; and the documentation must state how the references are handled. Get methods are often thread-safe as long as the ownership requirements are met and shared objects are not modified. Set methods, or modifying shared objects, are generally not thread-safe as discussed below.

Objects are thread-safe as long as the API's being invoked don't modify the object; in this case the parameter is usually marked in the API as "const". Not all parameters are marked this way. Note that a "const" declaration does not mean immutable; for example X509_cmp(3) takes pointers to "const" objects, but the implementation uses a C cast to remove that so it can lock objects, generate and cache a DER encoding, and so on.

Another instance of thread-safety is when updates to an object's internal state, such as cached values, are done with locks. One example of this is the reference counting API's described above.

In all cases, however, it is generally not safe for one thread to mutate an object, such as setting elements of a private or public key, while another thread is using that object, such as verifying a signature.

The same API's can usually be used simultaneously on different objects without interference. For example, two threads can calculate a signature using two different EVP_PKEY_CTX objects.

For implicit global state or singletons, thread-safety depends on the facility. The CRYPTO_secure_malloc(3) and related API's have their own lock, while CRYPTO_malloc(3) assumes the underlying platform allocation will do any necessary locking. Some API's, such as NCONF_load(3) and related do no locking at all; this can be considered a bug.

A separate, although related, issue is modifying "factory" objects when other objects have been created from that. For example, an SSL_CTX object created by SSL_CTX_new(3) is used to create per-connection SSL objects by calling SSL_new(3). In this specific case, and probably for factory methods in general, it is not safe to modify the factory object after it has been used to create other objects.

## SEE ALSO
CRYPTO_THREAD_run_once(3), local system threads documentation.

## BUGS
This page is admittedly very incomplete.

## COPYRIGHT
Copyright 2021 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>.


title: openssl_user_macros(7ossl)

summary: User defined macros

text:
# openssl_user_macros(7ossl)

## NAME
openssl_user_macros, OPENSSL_API_COMPAT, OPENSSL_NO_DEPRECATED - User defined macros

## DESCRIPTION
User defined macros allow the programmer to control certain aspects of what is exposed by the OpenSSL headers.

NOTE: to be effective, a user defined macro must be defined before including any header file that depends on it, either in the compilation command ("cc -DMACRO=value") or by defining the macro in source before including any headers.

Other manual pages may refer to this page when declarations depend on user defined macros.

### The macros
OPENSSL_API_COMPAT

The value is a version number, given in one of the following two forms:

"0xMNNFF000L"

This is the form supported for all versions up to 1.1.x, where "M" represents the major number, "NN" represents the minor number, and "FF" represents the fix number, as a hexadecimal number. For version 1.1.0, that's "0x10100000L". Any version number may be given, but these numbers are the current known major deprecation points, making them the most meaningful:

"0x00908000L" (version 0.9.8)

"0x10000000L" (version 1.0.0)

"0x10100000L" (version 1.1.0)

For convenience, higher numbers are accepted as well, as long as feasible. For example, "0x60000000L" will work as expected. However, it is recommended to start using the second form instead:

"mmnnpp"

This form is a simple decimal number calculated with this formula: major * 10000 + minor * 100 + patch

where major, minor and patch are the desired major, minor and patch components of the version number. For example:

30000 corresponds to version 3.0.0

10002 corresponds to version 1.0.2

420101 corresponds to version 42.1.1

If OPENSSL_API_COMPAT is undefined, this default value is used in its place: 30300

OPENSSL_NO_DEPRECATED

If this macro is defined, all deprecated public symbols in all OpenSSL versions up to and including the version given by OPENSSL_API_COMPAT (or the default value given above, when OPENSSL_API_COMPAT isn't defined) will be hidden.

## COPYRIGHT
Copyright 2018-2021 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>.


ossl-guide-introduction

title: ossl-guide-introduction(7ossl)

summary: guide\-introduction

text:
# ossl-guide-introduction(7ossl)

## NAME
ossl-guide-introduction - OpenSSL Guide: An introduction to OpenSSL

## WHAT IS OPENSSL?
OpenSSL is a robust, commercial-grade, full-featured toolkit for general-purpose cryptography and secure communication. Its features are made available via a command line application that enables users to perform various cryptography related functions such as generating keys and certificates. Additionally it supplies two libraries that application developers can use to implement cryptography based capabilities and to securely communicate across a network. Finally, it also has a set of providers that supply implementations of a broad set of cryptographic algorithms.

OpenSSL is fully open source. Version 3.0 and above are distributed under the Apache v2 license.

## GETTING AND INSTALLING OPENSSL
The OpenSSL Project develops and distributes the source code for OpenSSL. You can obtain that source code via the OpenSSL website (<https://www.openssl.org/source>).

Many Operating Systems (notably Linux distributions) supply pre-built OpenSSL binaries either pre-installed or available via the package management system in use for that OS. It is worth checking whether this applies to you before attempting to build OpenSSL from the source code.

Some third parties also supply OpenSSL binaries (e.g. for Windows and some other platforms). The OpenSSL project maintains a list of these third parties at <https://wiki.openssl.org/index.php/Binaries>.

If you build and install OpenSSL from the source code then you should download the appropriate files for the version that you want to use from the link given above. Extract the contents of the tar.gz archive file that you downloaded into an appropriate directory. Inside that archive you will find a file named INSTALL.md which will supply detailed instructions on how to build and install OpenSSL from source. Make sure you read the contents of that file carefully in order to achieve a successful build. In the directory you will also find a set of NOTES files that provide further platform specific information. Make sure you carefully read the file appropriate to your platform. As well as the platform specific NOTES files there is also a NOTES-PERL.md file that provides information about setting up Perl for use by the OpenSSL build system across multiple platforms.

Sometimes you may want to build and install OpenSSL from source on a system which already has a pre-built version of OpenSSL installed on it via the Operating System package management system (for example if you want to use a newer version of OpenSSL than the one supplied by your Operating System). In this case it is strongly recommended to install OpenSSL to a different location than where the pre-built version is installed. You should never replace the pre-built version with a different version as this may break your system.

## CONTENTS OF THE OPENSSL GUIDE
The OpenSSL Guide is a series of documentation pages (starting with this one) that introduce some of the main concepts in OpenSSL. The guide can either be read end-to-end in order, or alternatively you can simply skip to the parts most applicable to your use case. Note however that later pages may depend on and assume knowledge from earlier pages.

The pages in the guide are as follows:

ossl-guide-libraries-introduction(7): An introduction to the OpenSSL libraries

ossl-guide-libcrypto-introduction(7): An introduction to libcrypto

ossl-guide-libssl-introduction(7): An introduction to libssl

ossl-guide-tls-introduction(7): An introduction to SSL/TLS in OpenSSL

ossl-guide-tls-client-block(7): Writing a simple blocking TLS client

ossl-guide-tls-client-non-block(7): Writing a simple nonblocking TLS client

ossl-guide-quic-introduction(7): An introduction to QUIC in OpenSSL

ossl-guide-quic-client-block(7): Writing a simple blocking QUIC client

ossl-guide-quic-multi-stream(7): Writing a simple multi-stream QUIC client

ossl-guide-quic-client-non-block(7): Writing a simple nonblocking QUIC client

ossl-guide-migration(7): Migrating from older OpenSSL versions

## COPYRIGHT
Copyright 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>.


ossl-guide-libcrypto-introduction

summary: guide\-libcrypto\-introduction, crypto

text:
# ossl-guide-libcrypto-introduction(7ossl)

## NAME
ossl-guide-libcrypto-introduction, crypto - OpenSSL Guide: An introduction to libcrypto

## INTRODUCTION
The OpenSSL cryptography library ("libcrypto") enables access to a wide range of cryptographic algorithms used in various Internet standards. The services provided by this library are used by the OpenSSL implementations of TLS and CMS, and they have also been used to implement many other third party products and protocols.

The functionality includes symmetric encryption, public key cryptography, key agreement, certificate handling, cryptographic hash functions, cryptographic pseudo-random number generators, message authentication codes (MACs), key derivation functions (KDFs), and various utilities.

### Algorithms
Cryptographic primitives such as the SHA256 digest, or AES encryption are referred to in OpenSSL as "algorithms". Each algorithm may have multiple implementations available for use. For example the RSA algorithm is available as a "default" implementation suitable for general use, and a "fips" implementation which has been validated to FIPS 140 standards for situations where that is important. It is also possible that a third party could add additional implementations such as in a hardware security module (HSM).

Algorithms are implemented in providers. See ossl-guide-libraries-introduction(7) for information about providers.

### Operations
Different algorithms can be grouped together by their purpose. For example there are algorithms for encryption, and different algorithms for digesting data. These different groups are known as "operations" in OpenSSL. Each operation has a different set of functions associated with it. For example to perform an encryption operation using AES (or any other encryption algorithm) you would use the encryption functions detailed on the EVP_EncryptInit(3) page. Or to perform a digest operation using SHA256 then you would use the digesting functions on the EVP_DigestInit(3) page.

## ALGORITHM FETCHING
In order to use an algorithm an implementation for it must first be "fetched". Fetching is the process of looking through the available implementations, applying selection criteria (via a property query string), and finally choosing the implementation that will be used.

Two types of fetching are supported by OpenSSL - "Explicit fetching" and "Implicit fetching".

### Explicit fetching
Explicit fetching involves directly calling a specific API to fetch an algorithm implementation from a provider. This fetched object can then be passed to other APIs. These explicit fetching functions usually have the name "APINAME_fetch", where "APINAME" is the name of the operation. For example EVP_MD_fetch(3) can be used to explicitly fetch a digest algorithm implementation. The user is responsible for freeing the object returned from the "APINAME_fetch" function using "APINAME_free" when it is no longer needed.

These fetching functions follow a fairly common pattern, where three arguments are passed:

The library context

See OSSL_LIB_CTX(3) for a more detailed description. This may be NULL to signify the default (global) library context, or a context created by the user. Only providers loaded in this library context (see OSSL_PROVIDER_load(3)) will be considered by the fetching function. In case no provider has been loaded in this library context then the default provider will be loaded as a fallback (see OSSL_PROVIDER-default(7)).

An identifier

For all currently implemented fetching functions this is the algorithm name. Each provider supports a list of algorithm implementations. See the provider specific documentation for information on the algorithm implementations available in each provider: "OPERATIONS AND ALGORITHMS" in OSSL_PROVIDER-default(7), "OPERATIONS AND ALGORITHMS" in OSSL_PROVIDER-FIPS(7), "OPERATIONS AND ALGORITHMS" in OSSL_PROVIDER-legacy(7) and "OPERATIONS AND ALGORITHMS" in OSSL_PROVIDER-base(7). Note, while providers may register algorithms against a list of names using a string with a colon separated list of names, fetching algorithms using that format is currently unsupported.

A property query string

The property query string used to guide selection of the algorithm implementation. See "PROPERTY QUERY STRINGS" in ossl-guide-libraries-introduction(7).

The algorithm implementation that is fetched can then be used with other diverse functions that use them. For example the EVP_DigestInit_ex(3) function takes as a parameter an EVP_MD object which may have been returned from an earlier call to EVP_MD_fetch(3).

### Implicit fetching
OpenSSL has a number of functions that return an algorithm object with no associated implementation, such as EVP_sha256(3), EVP_aes_128_cbc(3), EVP_get_cipherbyname(3) or EVP_get_digestbyname(3). These are present for compatibility with OpenSSL before version 3.0 where explicit fetching was not available.

When they are used with functions like EVP_DigestInit_ex(3) or EVP_CipherInit_ex(3), the actual implementation to be used is fetched implicitly using default search criteria (which uses NULL for the library context and property query string).

In some cases implicit fetching can also occur when a NULL algorithm parameter is supplied. In this case an algorithm implementation is implicitly fetched using default search criteria and an algorithm name that is consistent with the context in which it is being used.

Functions that use an EVP_PKEY_CTX or an EVP_PKEY(3), such as EVP_DigestSignInit(3), all fetch the implementations implicitly. Usually the algorithm to fetch is determined based on the type of key that is being used and the function that has been called.

### Performance
If you perform the same operation many times with the same algorithm then it is recommended to use a single explicit fetch of the algorithm and then reuse the explicitly fetched algorithm each subsequent time. This will typically be faster than implicitly fetching the algorithm every time you use it. See an example of Explicit fetching in "USING ALGORITHMS IN APPLICATIONS".

Prior to OpenSSL 3.0, functions such as EVP_sha256() which return a "const" object were used directly to indicate the algorithm to use in various function calls. If you pass the return value of one of these convenience functions to an operation then you are using implicit fetching. If you are converting an application that worked with an OpenSSL version prior to OpenSSL 3.0 then consider changing instances of implicit fetching to explicit fetching instead.

If an explicitly fetched object is not passed to an operation, then any implicit fetch will use an internally cached prefetched object, but it will still be slower than passing the explicitly fetched object directly.

The following functions can be used for explicit fetching:

EVP_MD_fetch(3)

Fetch a message digest/hashing algorithm implementation.

EVP_CIPHER_fetch(3)

Fetch a symmetric cipher algorithm implementation.

EVP_KDF_fetch(3)

Fetch a Key Derivation Function (KDF) algorithm implementation.

EVP_MAC_fetch(3)

Fetch a Message Authentication Code (MAC) algorithm implementation.

EVP_KEM_fetch(3)

Fetch a Key Encapsulation Mechanism (KEM) algorithm implementation

OSSL_ENCODER_fetch(3)

Fetch an encoder algorithm implementation (e.g. to encode keys to a specified format).

OSSL_DECODER_fetch(3)

Fetch a decoder algorithm implementation (e.g. to decode keys from a specified format).

EVP_RAND_fetch(3)

Fetch a Pseudo Random Number Generator (PRNG) algorithm implementation.

See "OPERATIONS AND ALGORITHMS" in OSSL_PROVIDER-default(7), "OPERATIONS AND ALGORITHMS" in OSSL_PROVIDER-FIPS(7), "OPERATIONS AND ALGORITHMS" in OSSL_PROVIDER-legacy(7) and "OPERATIONS AND ALGORITHMS" in OSSL_PROVIDER-base(7) for a list of algorithm names that can be fetched.

## FETCHING EXAMPLES
The following section provides a series of examples of fetching algorithm implementations.

Fetch any available implementation of SHA2-256 in the default context. Note that some algorithms have aliases. So "SHA256" and "SHA2-256" are synonymous:

```
 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", NULL);
 ...
 EVP_MD_free(md);
```

Fetch any available implementation of AES-128-CBC in the default context:

```
 EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL);
 ...
 EVP_CIPHER_free(cipher);
```

Fetch an implementation of SHA2-256 from the default provider in the default context:

```
 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");
 ...
 EVP_MD_free(md);
```

Fetch an implementation of SHA2-256 that is not from the default provider in the default context:

```
 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider!=default");
 ...
 EVP_MD_free(md);
```

Fetch an implementation of SHA2-256 that is preferably from the FIPS provider in the default context:

```
 EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider=?fips");
 ...
 EVP_MD_free(md);
```

Fetch an implementation of SHA2-256 from the default provider in the specified library context:

```
 EVP_MD *md = EVP_MD_fetch(libctx, "SHA2-256", "provider=default");
 ...
 EVP_MD_free(md);
```

Load the legacy provider into the default context and then fetch an implementation of WHIRLPOOL from it:

```
 /* This only needs to be done once - usually at application start up */
 OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
 EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy");
 ...
 EVP_MD_free(md);
```

Note that in the above example the property string "provider=legacy" is optional since, assuming no other providers have been loaded, the only implementation of the "whirlpool" algorithm is in the "legacy" provider. Also note that the default provider should be explicitly loaded if it is required in addition to other providers:

```
 /* This only needs to be done once - usually at application start up */
 OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
 OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");
 EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
 EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
 ...
 EVP_MD_free(md_whirlpool);
 EVP_MD_free(md_sha256);
```

## USING ALGORITHMS IN APPLICATIONS
Cryptographic algorithms are made available to applications through use of the "EVP" APIs. Each of the various operations such as encryption, digesting, message authentication codes, etc., have a set of EVP function calls that can be invoked to use them. See the evp(7) page for further details.

Most of these follow a common pattern. A "context" object is first created. For example for a digest operation you would use an EVP_MD_CTX, and for an encryption/decryption operation you would use an EVP_CIPHER_CTX. The operation is then initialised ready for use via an "init" function - optionally passing in a set of parameters (using the OSSL_PARAM(3) type) to configure how the operation should behave. Next data is fed into the operation in a series of "update" calls. The operation is finalised using a "final" call which will typically provide some kind of output. Finally the context is cleaned up and freed.

The following shows a complete example for doing this process for digesting data using SHA256. The process is similar for other operations such as encryption/decryption, signatures, message authentication codes, etc. Additional examples can be found in the OpenSSL demos (see "DEMO APPLICATIONS" in ossl-guide-libraries-introduction(7)).

```
 #include <stdio.h>
 #include <openssl/evp.h>
 #include <openssl/bio.h>
 #include <openssl/err.h>
 int main(void)
 {
     EVP_MD_CTX *ctx = NULL;
     EVP_MD *sha256 = NULL;
     const unsigned char msg[] = {
         0x00, 0x01, 0x02, 0x03
     };
     unsigned int len = 0;
     unsigned char *outdigest = NULL;
     int ret = 1;
     /* Create a context for the digest operation */
     ctx = EVP_MD_CTX_new();
     if (ctx == NULL)
         goto err;
     /*
      * Fetch the SHA256 algorithm implementation for doing the digest. We're
      * using the "default" library context here (first NULL parameter), and
      * we're not supplying any particular search criteria for our SHA256
      * implementation (second NULL parameter). Any SHA256 implementation will
      * do.
      * In a larger application this fetch would just be done once, and could
      * be used for multiple calls to other operations such as EVP_DigestInit_ex().
      */
     sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
     if (sha256 == NULL)
         goto err;
    /* Initialise the digest operation */
    if (!EVP_DigestInit_ex(ctx, sha256, NULL))
        goto err;
     /*
      * Pass the message to be digested. This can be passed in over multiple
      * EVP_DigestUpdate calls if necessary
      */
     if (!EVP_DigestUpdate(ctx, msg, sizeof(msg)))
         goto err;
     /* Allocate the output buffer */
     outdigest = OPENSSL_malloc(EVP_MD_get_size(sha256));
     if (outdigest == NULL)
         goto err;
     /* Now calculate the digest itself */
     if (!EVP_DigestFinal_ex(ctx, outdigest, &len))
         goto err;
     /* Print out the digest result */
     BIO_dump_fp(stdout, outdigest, len);
     ret = 0;
  err:
     /* Clean up all the resources we allocated */
     OPENSSL_free(outdigest);
     EVP_MD_free(sha256);
     EVP_MD_CTX_free(ctx);
     if (ret != 0)
        ERR_print_errors_fp(stderr);
     return ret;
 }
```

## ENCODING AND DECODING KEYS
Many algorithms require the use of a key. Keys can be generated dynamically using the EVP APIs (for example see EVP_PKEY_Q_keygen(3)). However it is often necessary to save or load keys (or their associated parameters) to or from some external format such as PEM or DER (see openssl-glossary(7)). OpenSSL uses encoders and decoders to perform this task.

Encoders and decoders are just algorithm implementations in the same way as any other algorithm implementation in OpenSSL. They are implemented by providers. The OpenSSL encoders and decoders are available in the default provider. They are also duplicated in the base provider.

For information about encoders see OSSL_ENCODER_CTX_new_for_pkey(3). For information about decoders see OSSL_DECODER_CTX_new_for_pkey(3).

As well as using encoders/decoders directly there are also some helper functions that can be used for certain well known and commonly used formats. For example see PEM_read_PrivateKey(3) and PEM_write_PrivateKey(3) for information about reading and writing key data from PEM encoded files.

## FURTHER READING
See ossl-guide-libssl-introduction(7) for an introduction to using "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-2024 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>.


ossl-guide-libraries-introduction

summary: guide\-libraries\-introduction

text:
# ossl-guide-libraries-introduction(7ossl)

## 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>.


ossl-guide-libssl-introduction

title: ossl-guide-libssl-introduction(7ossl)

summary: guide\-libssl\-introduction, ssl

text:
# ossl-guide-libssl-introduction(7ossl)

## NAME
ossl-guide-libssl-introduction, ssl - OpenSSL Guide: An introduction to libssl

## INTRODUCTION
The OpenSSL "libssl" library provides implementations of several secure network communications protocols. Specifically it provides SSL/TLS (SSLv3, TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3), DTLS (DTLSv1 and DTLSv1.2) and QUIC (client side only). The library depends on "libcrypto" for its underlying cryptographic operations (see ossl-guide-libcrypto-introduction(7)).

The set of APIs supplied by "libssl" is common across all of these different network protocols, so a developer familiar with writing applications using one of these protocols should be able to transition to using another with relative ease.

An application written to use "libssl" will include the <openssl/ssl.h> header file and will typically use two main data structures, i.e. SSL and SSL_CTX.

An SSL object is used to represent a connection to a remote peer. Once a connection with a remote peer has been established data can be exchanged with that peer.

When using DTLS any data that is exchanged uses "datagram" semantics, i.e. the packets of data can be delivered in any order, and they are not guaranteed to arrive at all. In this case the SSL object used for the connection is also used for exchanging data with the peer.

Both TLS and QUIC support the concept of a "stream" of data. Data sent via a stream is guaranteed to be delivered in order without any data loss. A stream can be uni- or bi-directional.

SSL/TLS only supports one stream of data per connection and it is always bi-directional. In this case the SSL object used for the connection also represents that stream. See ossl-guide-tls-introduction(7) for more information.

The QUIC protocol can support multiple streams per connection and they can be uni- or bi-directional. In this case an SSL object can represent the underlying connection, or a stream, or both. Where multiple streams are in use a separate SSL object is used for each one. See ossl-guide-quic-introduction(7) for more information.

An SSL_CTX object is used to create the SSL object for the underlying connection. A single SSL_CTX object can be used to create many connections (each represented by a separate SSL object). Many API functions in libssl exist in two forms: one that takes an SSL_CTX and one that takes an SSL. Typically settings that you apply to the SSL_CTX will then be inherited by any SSL object that you create from it. Alternatively you can apply settings directly to the SSL object without affecting other SSL objects. Note that you should not normally make changes to an SSL_CTX after the first SSL object has been created from it.

## DATA STRUCTURES
As well as SSL_CTX and SSL there are a number of other data structures that an application may need to use. They are summarised below.

SSL_METHOD (SSL Method)

This structure is used to indicate the kind of connection you want to make, e.g. whether it is to represent the client or the server, and whether it is to use SSL/TLS, DTLS or QUIC (client only). It is passed as a parameter when creating the SSL_CTX.

SSL_SESSION (SSL Session)

After establishing a connection with a peer the agreed cryptographic material can be reused to create future connections with the same peer more rapidly. The set of data used for such a future connection establishment attempt is collected together into an SSL_SESSION object. A single successful connection with a peer may generate zero or more such SSL_SESSION objects for use in future connection attempts.

SSL_CIPHER (SSL Cipher)

During connection establishment the client and server agree upon cryptographic algorithms they are going to use for encryption and other uses. A single set of cryptographic algorithms that are to be used together is known as a ciphersuite. Such a set is represented by an SSL_CIPHER object. The set of available ciphersuites that can be used are configured in the SSL_CTX or SSL.

## FURTHER READING
See ossl-guide-tls-introduction(7) for an introduction to the SSL/TLS protocol and ossl-guide-quic-introduction(7) for an introduction to QUIC.

See ossl-guide-libcrypto-introduction(7) for an introduction to "libcrypto".

## SEE ALSO
ossl-guide-libcrypto-introduction(7), ossl-guide-tls-introduction(7), ossl-guide-quic-introduction(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>.