RAND

title: RAND(7ossl)

summary: the OpenSSL random generator

text:
# RAND(7ossl)

## NAME
RAND - the OpenSSL random generator

## DESCRIPTION
Random numbers are a vital part of cryptography, they are needed to provide unpredictability for tasks like key generation, creating salts, and many more. Software-based generators must be seeded with external randomness before they can be used as a cryptographically-secure pseudo-random number generator (CSPRNG). The availability of common hardware with special instructions and modern operating systems, which may use items such as interrupt jitter and network packet timings, can be reasonable sources of seeding material.

OpenSSL comes with a default implementation of the RAND API which is based on the deterministic random bit generator (DRBG) model as described in [NIST SP 800-90A Rev. 1]. The default random generator will initialize automatically on first use and will be fully functional without having to be initialized ('seeded') explicitly. It seeds and reseeds itself automatically using trusted random sources provided by the operating system.

As a normal application developer, you do not have to worry about any details, just use RAND_bytes(3) to obtain random data. Having said that, there is one important rule to obey: Always check the error return value of RAND_bytes(3) and do not take randomness for granted. Although (re-)seeding is automatic, it can fail because no trusted random source is available or the trusted source(s) temporarily fail to provide sufficient random seed material. In this case the CSPRNG enters an error state and ceases to provide output, until it is able to recover from the error by reseeding itself. For more details on reseeding and error recovery, see EVP_RAND(7).

For values that should remain secret, you can use RAND_priv_bytes(3) instead. This method does not provide 'better' randomness, it uses the same type of CSPRNG. The intention behind using a dedicated CSPRNG exclusively for private values is that none of its output should be visible to an attacker (e.g., used as salt value), in order to reveal as little information as possible about its internal state, and that a compromise of the "public" CSPRNG instance will not affect the secrecy of these private values.

In the rare case where the default implementation does not satisfy your special requirements, the default RAND internals can be replaced by your own EVP_RAND(3) objects.

Changing the default random generator should be necessary only in exceptional cases and is not recommended, unless you have a profound knowledge of cryptographic principles and understand the implications of your changes.

Finally, it is possible for a provider to bypass the default RAND setup for RAND_bytes(3) and associated functions. A provider can be specified as the single randomness source via the RAND_set1_random_provider(3) function or via configuration using the random_provider option in config(5). Once specified, the nominated provider will be used directly when calling the RAND_bytes(3) family of functions.

## DEFAULT SETUP
The default OpenSSL RAND method is based on the EVP_RAND deterministic random bit generator (DRBG) classes. A DRBG is a certain type of cryptographically-secure pseudo-random number generator (CSPRNG), which is described in [NIST SP 800-90A Rev. 1].

## SEE ALSO
RAND_bytes(3), RAND_priv_bytes(3), EVP_RAND(3), RAND_get0_primary(3), config(5), EVP_RAND(7), RAND_set1_random_provider(3).

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


RSA-PSS

package: openssl

title: RSA-PSS(7ossl)

summary: EVP_PKEY RSA\-PSS algorithm support

text:
# RSA-PSS(7ossl)

## NAME
RSA-PSS - EVP_PKEY RSA-PSS algorithm support

## DESCRIPTION
The RSA-PSS EVP_PKEY implementation is a restricted version of the RSA algorithm which only supports signing, verification and key generation using PSS padding modes with optional parameter restrictions.

It has associated private key and public key formats.

This algorithm shares several control operations with the RSA algorithm but with some restrictions described below.

### Signing and Verification
Signing and verification is similar to the RSA algorithm except the padding mode is always PSS. If the key in use has parameter restrictions then the corresponding signature parameters are set to the restrictions: for example, if the key can only be used with digest SHA256, MGF1 SHA256 and minimum salt length 32 then the digest, MGF1 digest and salt length will be set to SHA256, SHA256 and 32 respectively.

### Key Generation
By default no parameter restrictions are placed on the generated key.

## NOTES
The public key format is documented in RFC4055.

The PKCS#8 private key format used for RSA-PSS keys is similar to the RSA format except it uses the id-RSASSA-PSS OID and the parameters field, if present, restricts the key parameters in the same way as the public key.

## CONFORMING TO
RFC 4055

## SEE ALSO
EVP_PKEY_CTX_set_rsa_pss_keygen_md(3), EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md(3), EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen(3), EVP_PKEY_CTX_new(3), EVP_PKEY_CTX_ctrl_str(3), EVP_PKEY_derive(3)

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

branch: sisyphus


title: X25519(7ossl)

summary: EVP_PKEY X25519 and X448 support

text:
# X25519(7ossl)

## NAME
X25519, X448 - EVP_PKEY X25519 and X448 support

## DESCRIPTION
The X25519 and X448 EVP_PKEY implementation supports key generation and key derivation using X25519 and X448. It has associated private and public key formats compatible with RFC 8410.

No additional parameters can be set during key generation.

The peer public key must be set using EVP_PKEY_derive_set_peer() when performing key derivation.

## NOTES
A context for the X25519 algorithm can be obtained by calling:

```
 EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_X25519, NULL);
```

For the X448 algorithm a context can be obtained by calling:

```
 EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_X448, NULL);
```

X25519 or X448 private keys can be set directly using EVP_PKEY_new_raw_private_key(3) or loaded from a PKCS#8 private key file using PEM_read_bio_PrivateKey(3) (or similar function). Completely new keys can also be generated (see the example below). Setting a private key also sets the associated public key.

X25519 or X448 public keys can be set directly using EVP_PKEY_new_raw_public_key(3) or loaded from a SubjectPublicKeyInfo structure in a PEM file using PEM_read_bio_PUBKEY(3) (or similar function).

## EXAMPLES
This example generates an X25519 private key and writes it to standard output in PEM format:

```
 #include <openssl/evp.h>
 #include <openssl/pem.h>
 ...
 EVP_PKEY *pkey = NULL;
 EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_X25519, NULL);
 EVP_PKEY_keygen_init(pctx);
 EVP_PKEY_keygen(pctx, &pkey);
 EVP_PKEY_CTX_free(pctx);
 PEM_write_PrivateKey(stdout, pkey, NULL, NULL, 0, NULL, NULL);
```

The key derivation example in EVP_PKEY_derive(3) can be used with X25519 and X448.

## SEE ALSO
EVP_PKEY_CTX_new(3), EVP_PKEY_keygen(3), EVP_PKEY_derive(3), EVP_PKEY_derive_set_peer(3)

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


bio

title: bio(7ossl)

summary: Basic I/O abstraction

text:
# bio(7ossl)

## NAME
bio - Basic I/O abstraction

## SYNOPSIS

```
 #include <openssl/bio.h>
```

## DESCRIPTION
A BIO is an I/O abstraction, it hides many of the underlying I/O details from an application. If an application uses a BIO for its I/O it can transparently handle SSL connections, unencrypted network connections and file I/O.

There are two types of BIO, a source/sink BIO and a filter BIO.

As its name implies a source/sink BIO is a source and/or sink of data, examples include a socket BIO and a file BIO.

A filter BIO takes data from one BIO and passes it through to another, or the application. The data may be left unmodified (for example a message digest BIO) or translated (for example an encryption BIO). The effect of a filter BIO may change according to the I/O operation it is performing: for example an encryption BIO will encrypt data if it is being written to and decrypt data if it is being read from.

BIOs can be joined together to form a chain (a single BIO is a chain with one component). A chain normally consists of one source/sink BIO and one or more filter BIOs. Data read from or written to the first BIO then traverses the chain to the end (normally a source/sink BIO).

Some BIOs (such as memory BIOs) can be used immediately after calling BIO_new(). Others (such as file BIOs) need some additional initialization, and frequently a utility function exists to create and initialize such BIOs.

If BIO_free() is called on a BIO chain it will only free one BIO resulting in a memory leak.

Calling BIO_free_all() on a single BIO has the same effect as calling BIO_free() on it other than the discarded return value.

Normally the type argument is supplied by a function which returns a pointer to a BIO_METHOD. There is a naming convention for such functions: a source/sink BIO typically starts with BIO_s_ and a filter BIO with BIO_f_.

### TCP Fast Open
TCP Fast Open (RFC7413), abbreviated "TFO", is supported by the BIO interface since OpenSSL 3.2. TFO is supported in the following operating systems:

- Linux kernel 3.13 and later, where TFO is enabled by default.

- Linux kernel 4.11 and later, using TCP_FASTOPEN_CONNECT.

- FreeBSD 10.3 to 11.4, supports server TFO only.

- FreeBSD 12.0 and later, supports both client and server TFO.

- macOS 10.14 and later.

Each operating system has a slightly different API for TFO. Please refer to the operating systems' API documentation when using sockets directly.

## EXAMPLES
Create a memory BIO:

```
 BIO *mem = BIO_new(BIO_s_mem());
```

## SEE ALSO
BIO_ctrl(3), BIO_f_base64(3), BIO_f_buffer(3), BIO_f_cipher(3), BIO_f_md(3), BIO_f_null(3), BIO_f_ssl(3), BIO_f_readbuffer(3), BIO_find_type(3), BIO_get_conn_mode(3), BIO_new(3), BIO_new_bio_pair(3), BIO_push(3), BIO_read_ex(3), BIO_s_accept(3), BIO_s_bio(3), BIO_s_connect(3), BIO_s_fd(3), BIO_s_file(3), BIO_s_mem(3), BIO_s_null(3), BIO_s_socket(3), BIO_set_callback(3), BIO_set_conn_mode(3), BIO_set_tfo(3), BIO_set_tfo_accept(3), BIO_should_retry(3)

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


ct

title: ct(7ossl)

summary: Certificate Transparency

text:
# ct(7ossl)

## NAME
ct - Certificate Transparency

## SYNOPSIS

```
 #include <openssl/ct.h>
```

## DESCRIPTION
This library implements Certificate Transparency (CT) verification for TLS clients, as defined in RFC 6962. This verification can provide some confidence that a certificate has been publicly logged in a set of CT logs.

By default, these checks are disabled. They can be enabled using SSL_CTX_enable_ct(3) or SSL_enable_ct(3).

This library can also be used to parse and examine CT data structures, such as Signed Certificate Timestamps (SCTs), or to read a list of CT logs. There are functions for: - decoding and encoding SCTs in DER and TLS wire format. - printing SCTs. - verifying the authenticity of SCTs. - loading a CT log list from a CONF file.

## SEE ALSO
d2i_SCT_LIST(3), CTLOG_STORE_new(3), CTLOG_STORE_get0_log_by_id(3), SCT_new(3), SCT_print(3), SCT_validate(3), SCT_validate(3), CT_POLICY_EVAL_CTX_new(3), SSL_CTX_set_ct_validation_callback(3)

## HISTORY
The ct library was added in OpenSSL 1.1.0.

## COPYRIGHT
Copyright 2016-2017 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: des_modes(7ossl)

text:
# des_modes(7ossl)

## NAME
des_modes - the variants of DES and other crypto algorithms of OpenSSL

## DESCRIPTION
Several crypto algorithms for OpenSSL can be used in a number of modes. Those are used for using block ciphers in a way similar to stream ciphers, among other things.

## OVERVIEW

### Electronic Codebook Mode (ECB)
Normally, this is found as the function algorithm_ecb_encrypt().

- 64 bits are enciphered at a time.

- The order of the blocks can be rearranged without detection.

- The same plaintext block always produces the same ciphertext block (for the same key) making it vulnerable to a 'dictionary attack'.

- An error will only affect one ciphertext block.

### Cipher Block Chaining Mode (CBC)
Normally, this is found as the function algorithm_cbc_encrypt(). Be aware that des_cbc_encrypt() is not really DES CBC (it does not update the IV); use des_ncbc_encrypt() instead.

- a multiple of 64 bits are enciphered at a time.

- The CBC mode produces the same ciphertext whenever the same plaintext is encrypted using the same key and starting variable.

- The chaining operation makes the ciphertext blocks dependent on the current and all preceding plaintext blocks and therefore blocks can not be rearranged.

- The use of different starting variables prevents the same plaintext enciphering to the same ciphertext.

- An error will affect the current and the following ciphertext blocks.

### Cipher Feedback Mode (CFB)
Normally, this is found as the function algorithm_cfb_encrypt().

- a number of bits (j) <= 64 are enciphered at a time.

- The CFB mode produces the same ciphertext whenever the same plaintext is encrypted using the same key and starting variable.

- The chaining operation makes the ciphertext variables dependent on the current and all preceding variables and therefore j-bit variables are chained together and can not be rearranged.

- The use of different starting variables prevents the same plaintext enciphering to the same ciphertext.

- The strength of the CFB mode depends on the size of k (maximal if j == k). In my implementation this is always the case.

- Selection of a small value for j will require more cycles through the encipherment algorithm per unit of plaintext and thus cause greater processing overheads.

- Only multiples of j bits can be enciphered.

- An error will affect the current and the following ciphertext variables.

### Output Feedback Mode (OFB)
Normally, this is found as the function algorithm_ofb_encrypt().

- a number of bits (j) <= 64 are enciphered at a time.

- The OFB mode produces the same ciphertext whenever the same plaintext enciphered using the same key and starting variable. More over, in the OFB mode the same key stream is produced when the same key and start variable are used. Consequently, for security reasons a specific start variable should be used only once for a given key.

- The absence of chaining makes the OFB more vulnerable to specific attacks.

- The use of different start variables values prevents the same plaintext enciphering to the same ciphertext, by producing different key streams.

- Selection of a small value for j will require more cycles through the encipherment algorithm per unit of plaintext and thus cause greater processing overheads.

- Only multiples of j bits can be enciphered.

- OFB mode of operation does not extend ciphertext errors in the resultant plaintext output. Every bit error in the ciphertext causes only one bit to be in error in the deciphered plaintext.

- OFB mode is not self-synchronizing. If the two operation of encipherment and decipherment get out of synchronism, the system needs to be re-initialized.

- Each re-initialization should use a value of the start variable different from the start variable values used before with the same key. The reason for this is that an identical bit stream would be produced each time from the same parameters. This would be susceptible to a 'known plaintext' attack.

### Triple ECB Mode
Normally, this is found as the function algorithm_ecb3_encrypt().

- Encrypt with key1, decrypt with key2 and encrypt with key3 again.

- As for ECB encryption but increases the key length to 168 bits. There are theoretic attacks that can be used that make the effective key length 112 bits, but this attack also requires 2^56 blocks of memory, not very likely, even for the NSA.

- If both keys are the same it is equivalent to encrypting once with just one key.

- If the first and last key are the same, the key length is 112 bits. There are attacks that could reduce the effective key strength to only slightly more than 56 bits, but these require a lot of memory.

- If all 3 keys are the same, this is effectively the same as normal ecb mode.

### Triple CBC Mode
Normally, this is found as the function algorithm_ede3_cbc_encrypt().

- Encrypt with key1, decrypt with key2 and then encrypt with key3.

- As for CBC encryption but increases the key length to 168 bits with the same restrictions as for triple ecb mode.

## NOTES
This text was been written in large parts by Eric Young in his original documentation for SSLeay, the predecessor of OpenSSL. In turn, he attributed it to:

```
        AS 2805.5.2
        Australian Standard
        Electronic funds transfer - Requirements for interfaces,
        Part 5.2: Modes of operation for an n-bit block cipher algorithm
        Appendix A
```

## SEE ALSO
BF_encrypt(3), DES_crypt(3)

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


evp

title: evp(7ossl)

summary: high\-level cryptographic functions

text:
# evp(7ossl)

## NAME
evp - high-level cryptographic functions

## SYNOPSIS

```
 #include <openssl/evp.h>
```

## DESCRIPTION
The EVP library provides a high-level interface to cryptographic functions.

The EVP_SealXXX and EVP_OpenXXX functions provide public key encryption and decryption to implement digital "envelopes".

The EVP_DigestSignXXX and EVP_DigestVerifyXXX functions implement digital signatures and Message Authentication Codes (MACs). Also see the older EVP_SignXXX and EVP_VerifyXXX functions.

Symmetric encryption is available with the EVP_EncryptXXX functions. The EVP_DigestXXX functions provide message digests.

The EVP_PKEYXXX functions provide a high-level interface to asymmetric algorithms. To create a new EVP_PKEY see EVP_PKEY_new(3). EVP_PKEYs can be associated with a private key of a particular algorithm by using the functions described on the EVP_PKEY_fromdata(3) page, or new keys can be generated using EVP_PKEY_keygen(3). EVP_PKEYs can be compared using EVP_PKEY_eq(3), or printed using EVP_PKEY_print_private(3). EVP_PKEY_todata(3) can be used to convert a key back into an OSSL_PARAM(3) array.

The EVP_PKEY functions support the full range of asymmetric algorithm operations:

For key agreement see EVP_PKEY_derive(3)

For signing and verifying see EVP_PKEY_sign(3), EVP_PKEY_verify(3) and EVP_PKEY_verify_recover(3). However, note that these functions do not perform a digest of the data to be signed. Therefore, normally you would use the EVP_DigestSignInit(3) functions for this purpose.

For encryption and decryption see EVP_PKEY_encrypt(3) and EVP_PKEY_decrypt(3) respectively. However, note that these functions perform encryption and decryption only. As public key encryption is an expensive operation, normally you would wrap an encrypted message in a "digital envelope" using the EVP_SealInit(3) and EVP_OpenInit(3) functions.

The EVP_BytesToKey(3) function provides some limited support for password based encryption. Careful selection of the parameters will provide a PKCS#5 PBKDF1 compatible implementation. However, new applications should not typically use this (preferring, for example, PBKDF2 from PCKS#5).

The EVP_EncodeXXX and EVP_DecodeXXX functions implement base64 encoding and decoding.

All the symmetric algorithms (ciphers), digests and asymmetric algorithms (public key algorithms) can be replaced by ENGINE modules providing alternative implementations. If ENGINE implementations of ciphers or digests are registered as defaults, then the various EVP functions will automatically use those implementations automatically in preference to built in software implementations. For more information, consult the engine(3) man page.

Although low-level algorithm specific functions exist for many algorithms their use is discouraged. They cannot be used with an ENGINE and ENGINE versions of new algorithms cannot be accessed using the low-level functions. Also makes code harder to adapt to new algorithms and some options are not cleanly supported at the low-level and some operations are more efficient using the high-level interface.

## SEE ALSO
EVP_DigestInit(3), EVP_EncryptInit(3), EVP_OpenInit(3), EVP_SealInit(3), EVP_DigestSignInit(3), EVP_SignInit(3), EVP_VerifyInit(3), EVP_EncodeInit(3), EVP_PKEY_new(3), EVP_PKEY_fromdata(3), EVP_PKEY_todata(3), EVP_PKEY_keygen(3), EVP_PKEY_print_private(3), EVP_PKEY_decrypt(3), EVP_PKEY_encrypt(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), EVP_PKEY_verify_recover(3), EVP_PKEY_derive(3), EVP_BytesToKey(3), ENGINE_by_id(3)

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


title: fips_module(7ossl)

summary: OpenSSL fips module guide

text:
# fips_module(7ossl)

## NAME
fips_module - OpenSSL fips module guide

## SYNOPSIS
See the individual manual pages for details.

## DESCRIPTION
This guide details different ways that OpenSSL can be used in conjunction with the FIPS module. Which is the correct approach to use will depend on your own specific circumstances and what you are attempting to achieve.

For information related to installing the FIPS module see <https://github.com/openssl/openssl/blob/master/README-FIPS.md>.

Note that the old functions FIPS_mode() and FIPS_mode_set() are no longer present so you must remove them from your application if you use them.

Applications written to use the OpenSSL 3.0 FIPS module should not use any legacy APIs or features that avoid the FIPS module. Specifically this includes:

- Low level cryptographic APIs (use the high level APIs, such as EVP, instead)

- Engines

- Any functions that create or modify custom "METHODS" (for example EVP_MD_meth_new(), EVP_CIPHER_meth_new(), EVP_PKEY_meth_new(), RSA_meth_new(), EC_KEY_METHOD_new(), etc.)

All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to avoid using all deprecated functions. See ossl-guide-migration(7) for a list of deprecated functions.

### Making all applications use the FIPS module by default
One simple approach is to cause all applications that are using OpenSSL to only use the FIPS module for cryptographic algorithms by default.

This approach can be done purely via configuration. As long as applications are built and linked against OpenSSL 3.0 and do not override the loading of the default config file or its settings then they can automatically start using the FIPS module without the need for any further code changes.

To do this the default OpenSSL config file will have to be modified. The location of this config file will depend on the platform, and any options that were given during the build process. You can check the location of the config file by running this command:

```
    $ openssl version -d
    OPENSSLDIR: "/usr/local/ssl"
```

Caution: Many Operating Systems install OpenSSL by default. It is a common error to not have the correct version of OpenSSL in your $PATH. Check that you are running an OpenSSL 3.0 version like this:

```
    $ openssl version -v
    OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)
```

The OPENSSLDIR value above gives the directory name for where the default config file is stored. So in this case the default config file will be called /usr/local/ssl/openssl.cnf.

Edit the config file to add the following lines near the beginning:

```
    config_diagnostics = 1
    openssl_conf = openssl_init
    .include /usr/local/ssl/fipsmodule.cnf
    [openssl_init]
    providers = provider_sect
    alg_section = algorithm_sect
    [provider_sect]
    fips = fips_sect
    base = base_sect
    [base_sect]
    activate = 1
    [algorithm_sect]
    default_properties = fips=yes
```

Obviously the include file location above should match the path and name of the FIPS module config file that you installed earlier. See <https://github.com/openssl/openssl/blob/master/README-FIPS.md>.

For FIPS usage, it is recommended that the config_diagnostics option is enabled to prevent accidental use of non-FIPS validated algorithms via broken or mistaken configuration. See config(5).

Any applications that use OpenSSL 3.0 and are started after these changes are made will start using only the FIPS module unless those applications take explicit steps to avoid this default behaviour. Note that this configuration also activates the "base" provider. The base provider does not include any cryptographic algorithms (and therefore does not impact the validation status of any cryptographic operations), but does include other supporting algorithms that may be required. It is designed to be used in conjunction with the FIPS module.

This approach has the primary advantage that it is simple, and no code changes are required in applications in order to benefit from the FIPS module. There are some disadvantages to this approach:

- You may not want all applications to use the FIPS module. It may be the case that some applications should and some should not use the FIPS module.

- If applications take explicit steps to not load the default config file or set different settings. This method will not work for these cases.

- The algorithms available in the FIPS module are a subset of the algorithms that are available in the default OpenSSL Provider. If any applications attempt to use any algorithms that are not present, then they will fail.

- Usage of certain deprecated APIs avoids the use of the FIPS module. If any applications use those APIs then the FIPS module will not be used.

### Selectively making applications use the FIPS module by default
A variation on the above approach is to do the same thing on an individual application basis. The default OpenSSL config file depends on the compiled in value for OPENSSLDIR as described in the section above. However it is also possible to override the config file to be used via the OPENSSL_CONF environment variable. For example the following, on Unix, will cause the application to be executed with a non-standard config file location:

```
    $ OPENSSL_CONF=/my/nondefault/openssl.cnf myapplication
```

Using this mechanism you can control which config file is loaded (and hence whether the FIPS module is loaded) on an application by application basis.

This removes the disadvantage listed above that you may not want all applications to use the FIPS module. All the other advantages and disadvantages still apply.

### Programmatically loading the FIPS module (default library context)
Applications may choose to load the FIPS provider explicitly rather than relying on config to do this. The config file is still necessary in order to hold the FIPS module config data (such as its self test status and integrity data). But in this case we do not automatically activate the FIPS provider via that config file.

To do things this way configure as per "Making all applications use the FIPS module by default" above, but edit the fipsmodule.cnf file to remove or comment out the line which says "activate = 1" (note that setting this value to 0 is not sufficient). This means all the required config information will be available to load the FIPS module, but it is not automatically loaded when the application starts. The FIPS provider can then be loaded programmatically like this:

```
    #include <openssl/provider.h>
    int main(void)
    {
        OSSL_PROVIDER *fips;
        OSSL_PROVIDER *base;
        fips = OSSL_PROVIDER_load(NULL, "fips");
        if (fips == NULL) {
            printf("Failed to load FIPS provider\n");
            exit(EXIT_FAILURE);
        }
        base = OSSL_PROVIDER_load(NULL, "base");
        if (base == NULL) {
            OSSL_PROVIDER_unload(fips);
            printf("Failed to load base provider\n");
            exit(EXIT_FAILURE);
        }
        /* Rest of application */
        OSSL_PROVIDER_unload(base);
        OSSL_PROVIDER_unload(fips);
        exit(EXIT_SUCCESS);
    }
```

Note that this should be one of the first things that you do in your application. If any OpenSSL functions get called that require the use of cryptographic functions before this occurs then, if no provider has yet been loaded, then the default provider will be automatically loaded. If you then later explicitly load the FIPS provider then you will have both the FIPS and the default provider loaded at the same time. It is unspecified which implementation of an algorithm will be used if multiple implementations are available and you have not explicitly specified via a property query (see below) which one should be used.

Also note that in this example we have additionally loaded the "base" provider. This loads a sub-set of algorithms that are also available in the default provider - specifically non cryptographic ones which may be used in conjunction with the FIPS provider. For example this contains algorithms for encoding and decoding keys. If you decide not to load the default provider then you will usually want to load the base provider instead.

In this example we are using the "default" library context. OpenSSL functions operate within the scope of a library context. If no library context is explicitly specified then the default library context is used. For further details about library contexts see the OSSL_LIB_CTX(3) man page.

### Loading the FIPS module at the same time as other providers
It is possible to have the FIPS provider and other providers (such as the default provider) all loaded at the same time into the same library context. You can use a property query string during algorithm fetches to specify which implementation you would like to use.

For example to fetch an implementation of SHA256 which conforms to FIPS standards you can specify the property query "fips=yes" like this:

```
    EVP_MD *sha256;
    sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");
```

If no property query is specified, or more than one implementation matches the property query then it is unspecified which implementation of a particular algorithm will be returned.

This example shows an explicit request for an implementation of SHA256 from the default provider:

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

It is also possible to set a default property query string. The following example sets the default property query of "fips=yes" for all fetches within the default library context:

```
    EVP_set_default_properties(NULL, "fips=yes");
```

If a fetch function has both an explicit property query specified, and a default property query is defined then the two queries are merged together and both apply. The local property query overrides the default properties if the same property name is specified in both.

There are two important built-in properties that you should be aware of:

The "provider" property enables you to specify which provider you want an implementation to be fetched from, e.g. "provider=default" or "provider=fips". All algorithms implemented in a provider have this property set on them.

There is also the "fips" property. All FIPS algorithms match against the property query "fips=yes". There are also some non-cryptographic algorithms available in the default and base providers that also have the "fips=yes" property defined for them. These are the encoder and decoder algorithms that can (for example) be used to write out a key generated in the FIPS provider to a file. The encoder and decoder algorithms are not in the FIPS module itself but are allowed to be used in conjunction with the FIPS algorithms.

It is possible to specify default properties within a config file. For example the following config file automatically loads the default and FIPS providers and sets the default property value to be "fips=yes". Note that this config file does not load the "base" provider. All supporting algorithms that are in "base" are also in "default", so it is unnecessary in this case:

```
    config_diagnostics = 1
    openssl_conf = openssl_init
    .include /usr/local/ssl/fipsmodule.cnf
    [openssl_init]
    providers = provider_sect
    alg_section = algorithm_sect
    [provider_sect]
    fips = fips_sect
    default = default_sect
    [default_sect]
    activate = 1
    [algorithm_sect]
    default_properties = fips=yes
```

### Programmatically loading the FIPS module (nondefault library context)
In addition to using properties to separate usage of the FIPS module from other usages this can also be achieved using library contexts. In this example we create two library contexts. In one we assume the existence of a config file called openssl-fips.cnf that automatically loads and configures the FIPS and base providers. The other library context will just use the default provider.

```
    OSSL_LIB_CTX *fips_libctx, *nonfips_libctx;
    OSSL_PROVIDER *defctxnull = NULL;
    EVP_MD *fipssha256 = NULL, *nonfipssha256 = NULL;
    int ret = 1;
    /*
     * Create two nondefault library contexts. One for fips usage and
     * one for non-fips usage
     */
    fips_libctx = OSSL_LIB_CTX_new();
    nonfips_libctx = OSSL_LIB_CTX_new();
    if (fips_libctx == NULL || nonfips_libctx == NULL)
        goto err;
    /* Prevent anything from using the default library context */
    defctxnull = OSSL_PROVIDER_load(NULL, "null");
    /*
     * Load config file for the FIPS library context. We assume that
     * this config file will automatically activate the FIPS and base
     * providers so we don't need to explicitly load them here.
     */
    if (!OSSL_LIB_CTX_load_config(fips_libctx, "openssl-fips.cnf"))
        goto err;
    /*
     * Set the default property query on the FIPS library context to
     * ensure that only FIPS algorithms can be used.  There are a few non-FIPS
     * approved algorithms in the FIPS provider for backward compatibility reasons.
     */
    if (!EVP_set_default_properties(fips_libctx, "fips=yes"))
        goto err;
    /*
     * We don't need to do anything special to load the default
     * provider into nonfips_libctx. This happens automatically if no
     * other providers are loaded.
     * Because we don't call OSSL_LIB_CTX_load_config() explicitly for
     * nonfips_libctx it will just use the default config file.
     */
    /* As an example get some digests */
    /* Get a FIPS validated digest */
    fipssha256 = EVP_MD_fetch(fips_libctx, "SHA2-256", NULL);
    if (fipssha256 == NULL)
        goto err;
    /* Get a non-FIPS validated digest */
    nonfipssha256 = EVP_MD_fetch(nonfips_libctx, "SHA2-256", NULL);
    if (nonfipssha256 == NULL)
        goto err;
    /* Use the digests */
    printf("Success\n");
    ret = 0;
    err:
    EVP_MD_free(fipssha256);
    EVP_MD_free(nonfipssha256);
    OSSL_LIB_CTX_free(fips_libctx);
    OSSL_LIB_CTX_free(nonfips_libctx);
    OSSL_PROVIDER_unload(defctxnull);
    return ret;
```

Note that we have made use of the special "null" provider here which we load into the default library context. We could have chosen to use the default library context for FIPS usage, and just create one additional library context for other usages - or vice versa. However if code has not been converted to use library contexts then the default library context will be automatically used. This could be the case for your own existing applications as well as certain parts of OpenSSL itself. Not all parts of OpenSSL are library context aware. If this happens then you could "accidentally" use the wrong library context for a particular operation. To be sure this doesn't happen you can load the "null" provider into the default library context. Because a provider has been explicitly loaded, the default provider will not automatically load. This means code using the default context by accident will fail because no algorithms will be available.

See "Library Context" in ossl-guide-migration(7) for additional information about the Library Context.

### Using Encoders and Decoders with the FIPS module
Encoders and decoders are used to read and write keys or parameters from or to some external format (for example a PEM file). If your application generates keys or parameters that then need to be written into PEM or DER format then it is likely that you will need to use an encoder to do this. Similarly you need a decoder to read previously saved keys and parameters. In most cases this will be invisible to you if you are using APIs that existed in OpenSSL 1.1.1 or earlier such as i2d_PrivateKey(3). However the appropriate encoder/decoder will need to be available in the library context associated with the key or parameter object. The built-in OpenSSL encoders and decoders are implemented in both the default and base providers and are not in the FIPS module boundary. However since they are not cryptographic algorithms themselves it is still possible to use them in conjunction with the FIPS module, and therefore these encoders/decoders have the "fips=yes" property against them. You should ensure that either the default or base provider is loaded into the library context in this case.

### Using the FIPS module in SSL/TLS
Writing an application that uses libssl in conjunction with the FIPS module is much the same as writing a normal libssl application. If you are using global properties and the default library context to specify usage of FIPS validated algorithms then this will happen automatically for all cryptographic algorithms in libssl. If you are using a nondefault library context to load the FIPS provider then you can supply this to libssl using the function SSL_CTX_new_ex(3). This works as a drop in replacement for the function SSL_CTX_new(3) except it provides you with the capability to specify the library context to be used. You can also use the same function to specify libssl specific properties to use.

In this first example we create two SSL_CTX objects using two different library contexts.

```
    /*
     * We assume that a nondefault library context with the FIPS
     * provider loaded has been created called fips_libctx.
     */
    SSL_CTX *fips_ssl_ctx = SSL_CTX_new_ex(fips_libctx, "fips=yes", TLS_method());
    /*
     * We assume that a nondefault library context with the default
     * provider loaded has been created called non_fips_libctx.
     */
    SSL_CTX *non_fips_ssl_ctx = SSL_CTX_new_ex(non_fips_libctx, NULL,
                                               TLS_method());
```

In this second example we create two SSL_CTX objects using different properties to specify FIPS usage:

```
    /*
     * The "fips=yes" property includes all FIPS approved algorithms
     * as well as encoders from the default provider that are allowed
     * to be used. The NULL below indicates that we are using the
     * default library context.
     */
    SSL_CTX *fips_ssl_ctx = SSL_CTX_new_ex(NULL, "fips=yes", TLS_method());
    /*
     * The "provider!=fips" property allows algorithms from any
     * provider except the FIPS provider
     */
    SSL_CTX *non_fips_ssl_ctx = SSL_CTX_new_ex(NULL, "provider!=fips",
                                               TLS_method());
```

### Confirming that an algorithm is being provided by the FIPS module
A chain of links needs to be followed to go from an algorithm instance to the provider that implements it. The process is similar for all algorithms. Here the example of a digest is used.

To go from an EVP_MD_CTX to an EVP_MD, use EVP_MD_CTX_md(3) . To go from the EVP_MD to its OSSL_PROVIDER, use EVP_MD_get0_provider(3). To extract the name from the OSSL_PROVIDER, use OSSL_PROVIDER_get0_name(3).

### FIPS indicators
FIPS indicators have been added to the FIPS provider in OpenSSL 3.4. FIPS 140-3 requires indicators to be used if the FIPS provider allows non approved algorithms. An algorithm is approved if it passes all required checks such as minimum key size. By default an error will occur if any check fails. For backwards compatibility individual algorithms may override the checks by using either an option in the FIPS configuration (See "FIPS indicator options" in fips_config(5)) OR in code using an algorithm context setter. Overriding the check means that the algorithm is not FIPS compliant. OSSL_INDICATOR_set_callback(3) can be called to register a callback to log unapproved algorithms. At the end of any algorithm operation the approved status can be queried using an algorithm context getter to retrieve the indicator (e.g. "fips-indicator"). An example of an algorithm context setter is "key-check" in "Supported parameters" in EVP_KDF-HKDF(7).

The following algorithms use "fips-indicator" to query if the algorithm is approved:

DSA Key generation

DSA Key generation is no longer approved. See "DSA parameters" in EVP_PKEY-DSA(7)

DSA Signatures

DSA Signature generation is no longer approved. See "Signature Parameters" in EVP_SIGNATURE-DSA(7)

ECDSA Signatures

See "ECDSA Signature Parameters" in EVP_SIGNATURE-ECDSA(7)

EC Key Generation

See "Common EC parameters" in EVP_PKEY-EC(7)

RSA Encryption

"pkcs1" padding is no longer approved. See "RSA Asymmetric Cipher parameters" in EVP_ASYM_CIPHER-RSA(7) and "RSA KEM parameters" in EVP_KEM-RSA(7)

RSA Signatures

See "Signature Parameters" in EVP_SIGNATURE-RSA(7)

DRBGS

See "Supported parameters" in EVP_RAND-HASH-DRBG(7) and EVP_RAND-HMAC-DRBG(7)/Supported parameters>

DES

Triple-DES is not longer approved for encryption. See "Parameters" in EVP_CIPHER-DES(7)

DH

See "DH and DHX key exchange parameters" in EVP_KEYEXCH-DH(7)

ECDH

See "ECDH Key Exchange parameters" in EVP_KEYEXCH-ECDH(7)

KDFS

See relevant KDF documentation e.g. "Supported parameters" in EVP_KDF-HKDF(7)

CMAC and KMAC

See "Supported parameters" in EVP_MAC-CMAC(7) and "Supported parameters" in EVP_MAC-KMAC(7)

The following FIPS algorithms are unapproved and use the "fips-indicator".

RAND-TEST-RAND

See "Supported parameters" in EVP_RAND-TEST-RAND(7) The indicator callback is NOT triggered for this algorithm since it is used internally for non security purposes.

X25519 and X448 Key Generation and Key Exchange

The unapproved (non FIPS validated) algorithms have a property query value of "fips=no".

The following algorithms use a unique indicator and do not trigger the indicator callback.

AES-GCM ciphers support the indicator "iv-generated"

See "PARAMETERS" in EVP_EncryptInit(3) for further information.

ECDSA and RSA Signatures support the indicator "verify-message".

See "ECDSA Signature Parameters" in EVP_SIGNATURE-ECDSA(7) and "Signature Parameters" in EVP_SIGNATURE-RSA(7) /for further information.

## NOTES
Some released versions of OpenSSL do not include a validated FIPS provider. To determine which versions have undergone the validation process, please refer to the OpenSSL Downloads page <https://www.openssl.org/source/>. If you require FIPS-approved functionality, it is essential to build your FIPS provider using one of the validated versions listed there. Normally, it is possible to utilize a FIPS provider constructed from one of the validated versions alongside libcrypto and libssl compiled from any release within the same major release series. This flexibility enables you to address bug fixes and CVEs that fall outside the FIPS boundary.

As the FIPS provider still supports non-FIPS validated algorithms, The property query "fips=yes" is mandatory for applications that want to operate in a FIPS approved manner.

## SEE ALSO
ossl-guide-migration(7), crypto(7), fips_config(5), <https://www.openssl.org/source/>

## HISTORY
The FIPS module guide was created for use with the new FIPS provider in OpenSSL 3.0. FIPS indicators were added in OpenSSL 3.4.

## COPYRIGHT
Copyright 2021-2025 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: life_cycle-cipher(7ossl)

summary: The cipher algorithm life\-cycle

text:
# life_cycle-cipher(7ossl)

## NAME
life_cycle-cipher - The cipher algorithm life-cycle

## DESCRIPTION
All symmetric ciphers (CIPHERs) go through a number of stages in their life-cycle:

start

This state represents the CIPHER before it has been allocated. It is the starting state for any life-cycle transitions.

newed

This state represents the CIPHER after it has been allocated.

initialised

These states represent the CIPHER when it is set up and capable of processing input. There are three possible initialised states:

initialised using EVP_CipherInit

initialised for decryption using EVP_DecryptInit

initialised for encryption using EVP_EncryptInit

updated

These states represent the CIPHER when it is set up and capable of processing additional input or generating output. The three possible states directly correspond to those for initialised above. The three different streams should not be mixed.

finaled

This state represents the CIPHER when it has generated output.

freed

This state is entered when the CIPHER is freed. It is the terminal state for all life-cycle transitions.

### State Transition Diagram
The usual life-cycle of a CIPHER is illustrated:

+---------------------------+

| |

| start |

| |

+---------------------------+ + - - - - - - - - - - - - - +

| ' any of the initialised '

| EVP_CIPHER_CTX_new ' updated or finaled states '

v ' '

+---------------------------+ + - - - - - - - - - - - - - +

| | |

| newed | | EVP_CIPHER_CTX_reset

| | <----+

+---------------------------+

| | |

+---------+ | +---------+

EVP_DecryptInit | | EVP_CipherInit | EVP_EncryptInit

v v v

+---------------------------+ +---------------------------+ +---------------------------+

| | | | | |

| initialised | | initialised | | initialised |

| for decryption | | | | for encryption |

+---------------------------+ +---------------------------+ +---------------------------+

| | |

| EVP_DecryptUpdate | EVP_CipherUpdate EVP_EncryptUpdate |

| v |

| +---------------------------+ |

| | |--------------------+ |

| | updated | EVP_CipherUpdate | |

| | | <------------------+ |

v +---------------------------+ v

+---------------------------+ | +---------------------------+

| |---------------------+ | | |

| updated | EVP_DecryptUpdate | | | updated |------+

| for decryption | <-------------------+ | | for encryption | |

+---------------------------+ | +---------------------------+ |

| EVP_CipherFinal | | ^ |

+-------+ | +--------+ | |

EVP_DecryptFinal | | | EVP_EncryptFinal +-------------------+

v v v EVP_EncryptUpdate

+---------------------------+

| |-----------------------------+

| finaled | |

| | <---------------------------+

+---------------------------+ EVP_CIPHER_CTX_get_params

| (AEAD encryption)

| EVP_CIPHER_CTX_free

v

+---------------------------+

| |

| freed |

| |

+---------------------------+

### Formal State Transitions
This section defines all of the legal state transitions. This is the canonical list.

Function Call ---------------------------------------------- Current State -----------------------------------------------

start newed initialised updated finaled initialised updated initialised updated freed

decryption decryption encryption encryption

EVP_CIPHER_CTX_new newed

EVP_CipherInit initialised initialised initialised initialised initialised initialised initialised initialised

EVP_DecryptInit initialised initialised initialised initialised initialised initialised initialised initialised

decryption decryption decryption decryption decryption decryption decryption decryption

EVP_EncryptInit initialised initialised initialised initialised initialised initialised initialised initialised

encryption encryption encryption encryption encryption encryption encryption encryption

EVP_CipherUpdate updated updated

EVP_DecryptUpdate updated updated

decryption decryption

EVP_EncryptUpdate updated updated

encryption encryption

EVP_CipherFinal finaled

EVP_DecryptFinal finaled

EVP_EncryptFinal finaled

EVP_CIPHER_CTX_free freed freed freed freed freed freed freed freed freed

EVP_CIPHER_CTX_reset newed newed newed newed newed newed newed newed

EVP_CIPHER_CTX_get_params newed initialised updated initialised updated initialised updated

decryption decryption encryption encryption

EVP_CIPHER_CTX_set_params newed initialised updated initialised updated initialised updated

decryption decryption encryption encryption

EVP_CIPHER_CTX_gettable_params newed initialised updated initialised updated initialised updated

decryption decryption encryption encryption

EVP_CIPHER_CTX_settable_params newed initialised updated initialised updated initialised updated

decryption decryption encryption encryption

## NOTES
At some point the EVP layer will begin enforcing the transitions described herein.

## SEE ALSO
provider-cipher(7), EVP_EncryptInit(3)

## 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: life_cycle-digest(7ossl)

summary: The digest algorithm life\-cycle

text:
# life_cycle-digest(7ossl)

## NAME
life_cycle-digest - The digest algorithm life-cycle

## DESCRIPTION
All message digests (MDs) go through a number of stages in their life-cycle:

start

This state represents the MD before it has been allocated. It is the starting state for any life-cycle transitions.

newed

This state represents the MD after it has been allocated.

initialised

This state represents the MD when it is set up and capable of processing input.

updated

This state represents the MD when it is set up and capable of processing additional input or generating output.

finaled

This state represents the MD when it has generated output. For an XOF digest, this state represents the MD when it has generated a single-shot output.

squeezed

For an XOF digest, this state represents the MD when it has generated output. It can be called multiple times to generate more output. The output length is variable for each call.

freed

This state is entered when the MD is freed. It is the terminal state for all life-cycle transitions.

### State Transition Diagram
The usual life-cycle of a MD is illustrated:

+--------------------+

| start |

+--------------------+

| EVP_MD_CTX_reset

| EVP_MD_CTX_new +-------------------------------------------------+

v v |

EVP_MD_CTX_reset + - - - - - - - - - - - - - - - - - - - - - - + EVP_MD_CTX_reset |

+-------------------> ' newed ' <--------------------+ |

| + - - - - - - - - - - - - - - - - - - - - - - + | |

| | | |

| | EVP_DigestInit | |

| v | |

| EVP_DigestInit + - - - - - - - - - - - - - - - - - - - - - - + | |

+----+-------------------> ' initialised ' <+ EVP_DigestInit | |

| | + - - - - - - - - - - - - - - - - - - - - - - + | | |

| | | ^ | | |

| | | EVP_DigestUpdate | EVP_DigestInit | | |

| | v | | | |

| | +---------------------------------------------+ | | |

| +-------------------- | | | | |

| | | | | |

| EVP_DigestUpdate | | | | |

| +-------------------- | | | | |

| | | updated | | | |

| +-------------------> | | | | |

| | | | | |

| | | | | |

+----+------------------------- | | -+-------------------+----+ |

| | +---------------------------------------------+ | | | |

| | | | | | |

| | | EVP_DigestSqueeze +-------------------+ | | |

| | v | | | |

| | EVP_DigestSqueeze +---------------------------------------------+ | | |

| | +-------------------- | | | | |

| | | | squeezed | | | |

| | +-------------------> | | ---------------------+ | |

| | +---------------------------------------------+ | |

| | | | |

| | +---------------------------------------+ | |

| | | | |

| | +---------------------------------------------+ EVP_DigestFinalXOF | | |

| +------------------------- | finaled | <--------------------+----+ |

| +---------------------------------------------+ | |

| EVP_DigestFinal ^ | | | |

+---------------------------------+ | | EVP_MD_CTX_free | |

| v | |

| +------------------+ EVP_MD_CTX_free | |

| | freed | <--------------------+ |

| +------------------+ |

| |

+------------------------------------------------------+

### Formal State Transitions
This section defines all of the legal state transitions. This is the canonical list.

Function Call --------------------- Current State -----------------------------------

start newed initialised updated finaled squeezed freed

EVP_MD_CTX_new newed

EVP_DigestInit initialised initialised initialised initialised initialised

EVP_DigestUpdate updated updated

EVP_DigestFinal finaled

EVP_DigestFinalXOF finaled

EVP_DigestSqueeze squeezed squeezed

EVP_MD_CTX_free freed freed freed freed freed

EVP_MD_CTX_reset newed newed newed newed

EVP_MD_CTX_get_params newed initialised updated

EVP_MD_CTX_set_params newed initialised updated

EVP_MD_CTX_gettable_params newed initialised updated

EVP_MD_CTX_settable_params newed initialised updated

EVP_MD_CTX_copy_ex newed initialised updated squeezed

## NOTES
At some point the EVP layer will begin enforcing the transitions described herein.

## SEE ALSO
provider-digest(7), EVP_DigestInit(3)

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


title: life_cycle-kdf(7ossl)

summary: The KDF algorithm life\-cycle

text:
# life_cycle-kdf(7ossl)

## NAME
life_cycle-kdf - The KDF algorithm life-cycle

## DESCRIPTION
All key derivation functions (KDFs) and pseudo random functions (PRFs) go through a number of stages in their life-cycle:

start

This state represents the KDF/PRF before it has been allocated. It is the starting state for any life-cycle transitions.

newed

This state represents the KDF/PRF after it has been allocated.

deriving

This state represents the KDF/PRF when it is set up and capable of generating output.

freed

This state is entered when the KDF/PRF is freed. It is the terminal state for all life-cycle transitions.

### State Transition Diagram
The usual life-cycle of a KDF/PRF is illustrated:

+-------------------+

| start |

+-------------------+

|

| EVP_KDF_CTX_new

v

+-------------------+

| newed | <+

+-------------------+ |

| |

| EVP_KDF_derive |

v | EVP_KDF_CTX_reset

EVP_KDF_derive +-------------------+ |

+ - - - - - - - - | | |

' | deriving | |

+ - - - - - - - -> | | -+

+-------------------+

|

| EVP_KDF_CTX_free

v

+-------------------+

| freed |

+-------------------+

### Formal State Transitions
This section defines all of the legal state transitions. This is the canonical list.

Function Call ------------- Current State -------------

start newed deriving freed

EVP_KDF_CTX_new newed

EVP_KDF_derive deriving deriving

EVP_KDF_CTX_free freed freed freed

EVP_KDF_CTX_reset newed newed

EVP_KDF_CTX_get_params newed deriving

EVP_KDF_CTX_set_params newed deriving

EVP_KDF_CTX_gettable_params newed deriving

EVP_KDF_CTX_settable_params newed deriving

## NOTES
At some point the EVP layer will begin enforcing the transitions described herein.

## SEE ALSO
provider-kdf(7), EVP_KDF(3).

## HISTORY
The provider KDF interface was introduced in OpenSSL 3.0.

## 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: life_cycle-mac(7ossl)

summary: The MAC algorithm life\-cycle

text:
# life_cycle-mac(7ossl)

## NAME
life_cycle-mac - The MAC algorithm life-cycle

## DESCRIPTION
All message authentication codes (MACs) go through a number of stages in their life-cycle:

start

This state represents the MAC before it has been allocated. It is the starting state for any life-cycle transitions.

newed

This state represents the MAC after it has been allocated.

initialised

This state represents the MAC when it is set up and capable of processing input.

updated

This state represents the MAC when it is set up and capable of processing additional input or generating output.

finaled

This state represents the MAC when it has generated output.

freed

This state is entered when the MAC is freed. It is the terminal state for all life-cycle transitions.

### State Transition Diagram
The usual life-cycle of a MAC is illustrated:

+-------------------+

| start |

+-------------------+

|

| EVP_MAC_CTX_new

v

+-------------------+

| newed |

+-------------------+

|

| EVP_MAC_init

v

+-------------------+

+> | initialised | <+

| +-------------------+ |

| | |

| | EVP_MAC_update | EVP_MAC_init

| v |

EVP_MAC_init | +-------------------+ |

| | updated | -+

| +-------------------+

| | |

| | EVP_MAC_final | EVP_MAC_finalXOF

| v v

| +-------------------+

+- | finaled |

+-------------------+

|

| EVP_MAC_CTX_free

v

+-------------------+

| freed |

+-------------------+

### Formal State Transitions
This section defines all of the legal state transitions. This is the canonical list.

Function Call --------------------- Current State ----------------------

start newed initialised updated finaled freed

EVP_MAC_CTX_new newed

EVP_MAC_init initialised initialised initialised initialised

EVP_MAC_update updated updated

EVP_MAC_final finaled

EVP_MAC_finalXOF finaled

EVP_MAC_CTX_free freed freed freed freed freed

EVP_MAC_CTX_get_params newed initialised updated

EVP_MAC_CTX_set_params newed initialised updated

EVP_MAC_CTX_gettable_params newed initialised updated

EVP_MAC_CTX_settable_params newed initialised updated

## NOTES
At some point the EVP layer will begin enforcing the transitions described herein.

## SEE ALSO
provider-mac(7), EVP_MAC(3).

## HISTORY
The provider MAC interface was introduced in OpenSSL 3.0.

## 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: life_cycle-pkey(7ossl)

summary: The PKEY algorithm life\-cycle

text:
# life_cycle-pkey(7ossl)

## NAME
life_cycle-pkey - The PKEY algorithm life-cycle

## DESCRIPTION
All public keys (PKEYs) go through a number of stages in their life-cycle:

start

This state represents the PKEY before it has been allocated. It is the starting state for any life-cycle transitions.

newed

This state represents the PKEY after it has been allocated.

decapsulate

This state represents the PKEY when it is ready to perform a private key decapsulation operation.

decrypt

This state represents the PKEY when it is ready to decrypt some ciphertext.

derive

This state represents the PKEY when it is ready to derive a shared secret.

digest sign

This state represents the PKEY when it is ready to perform a private key signature operation.

encapsulate

This state represents the PKEY when it is ready to perform a public key encapsulation operation.

encrypt

This state represents the PKEY when it is ready to encrypt some plaintext.

key generation

This state represents the PKEY when it is ready to generate a new public/private key.

parameter generation

This state represents the PKEY when it is ready to generate key parameters.

verify

This state represents the PKEY when it is ready to verify a public key signature.

verify recover

This state represents the PKEY when it is ready to recover a public key signature data.

freed

This state is entered when the PKEY is freed. It is the terminal state for all life-cycle transitions.

### State Transition Diagram
The usual life-cycle of a PKEY object is illustrated:

+-------------+

| |

| start |

| |

EVP_PKEY_derive +-------------+

+-------------+ EVP_PKEY_derive_set_peer | +-------------+

| |----------------------------+ | +----------------------------| |

| derive | | | | EVP_PKEY_verify | verify |

| |<---------------------------+ | +--------------------------->| |

+-------------+ | +-------------+

^ | ^

| EVP_PKEY_derive_init | EVP_PKEY_verify_init |

+---------------------------------------+ | +---------------------------------------+

| | |

+-------------+ | | | +-------------+

| |----------------------------+ | | | +----------------------------| |

| digest sign | EVP_PKEY_sign | | | | | EVP_PKEY_verify_recover | verify |

| |<---------------------------+ | | | +--------------------------->| recover |

+-------------+ | | | +-------------+

^ | | | ^

| EVP_PKEY_sign_init | | | EVP_PKEY_verify_recover_init |

+---------------------------------+ | | | +---------------------------------+

| | | | |

+-------------+ | | | | | +-------------+

| |----------------------------+ | | | | | +----------------------------| |

| decapsulate | EVP_PKEY_decapsulate | | | | | | | EVP_PKEY_decrypt | decrypt |

| |<---------------------------+ | | v | | +--------------------------->| |

+-------------+ | +-------------+ | +-------------+

^ +---| |---+ ^

| EVP_PKEY_decapsulate_init | | EVP_PKEY_decrypt_init |

+-------------------------------------| newed |-------------------------------------+

| |

+---| |---+

+-------------+ | +-------------+ | +-------------+

| |----------------------------+ | | | | +----------------------------| |

| encapsulate | EVP_PKEY_encapsulate | | | | | | EVP_PKEY_encrypt | encrypt |

| |<---------------------------+ | | | | +--------------------------->| |

+-------------+ | | | | +-------------+

^ | | | | ^

| EVP_PKEY_encapsulate_init | | | | EVP_PKEY_encrypt_init |

+---------------------------------+ | | +---------------------------------+

| |

+---------------------------------------+ +---------------------------------------+

| EVP_PKEY_paramgen_init EVP_PKEY_keygen_init |

v v

+-------------+ +-------------+

| |----------------------------+ +----------------------------| |

| parameter | | | | key |

| generation |<---------------------------+ +--------------------------->| generation |

+-------------+ EVP_PKEY_paramgen EVP_PKEY_keygen +-------------+

EVP_PKEY_gen EVP_PKEY_gen

+ - - - - - + +-----------+

' ' EVP_PKEY_CTX_free | |

' any state '------------------->| freed |

' ' | |

+ - - - - - + +-----------+

### Formal State Transitions
This section defines all of the legal state transitions. This is the canonical list.

Function Call ---------------------------------------------------------------------- Current State ----------------------------------------------------------------------

start newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key freed

sign recover generation generation

EVP_PKEY_CTX_new newed

EVP_PKEY_CTX_new_id newed

EVP_PKEY_CTX_new_from_name newed

EVP_PKEY_CTX_new_from_pkey newed

EVP_PKEY_sign_init digest digest digest digest digest digest digest digest digest digest digest

sign sign sign sign sign sign sign sign sign sign sign

EVP_PKEY_sign digest

sign

EVP_PKEY_verify_init verify verify verify verify verify verify verify verify verify verify verify

EVP_PKEY_verify verify

EVP_PKEY_verify_recover_init verify verify verify verify verify verify verify verify verify verify verify

recover recover recover recover recover recover recover recover recover recover recover

EVP_PKEY_verify_recover verify

recover

EVP_PKEY_encrypt_init encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt encrypt

EVP_PKEY_encrypt encrypt

EVP_PKEY_decrypt_init decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt decrypt

EVP_PKEY_decrypt decrypt

EVP_PKEY_derive_init derive derive derive derive derive derive derive derive derive derive derive

EVP_PKEY_derive_set_peer derive

EVP_PKEY_derive derive

EVP_PKEY_encapsulate_init encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate encapsulate

EVP_PKEY_encapsulate encapsulate

EVP_PKEY_decapsulate_init decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate decapsulate

EVP_PKEY_decapsulate decapsulate

EVP_PKEY_paramgen_init parameter parameter parameter parameter parameter parameter parameter parameter parameter parameter parameter

generation generation generation generation generation generation generation generation generation generation generation

EVP_PKEY_paramgen parameter

generation

EVP_PKEY_keygen_init key key key key key key key key key key key

generation generation generation generation generation generation generation generation generation generation generation

EVP_PKEY_keygen key

generation

EVP_PKEY_gen parameter key

generation generation

EVP_PKEY_CTX_get_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key

sign recover generation generation

EVP_PKEY_CTX_set_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key

sign recover generation generation

EVP_PKEY_CTX_gettable_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key

sign recover generation generation

EVP_PKEY_CTX_settable_params newed digest verify verify encrypt decrypt derive encapsulate decapsulate parameter key

sign recover generation generation

EVP_PKEY_CTX_free freed freed freed freed freed freed freed freed freed freed freed freed

## NOTES
At some point the EVP layer will begin enforcing the transitions described herein.

## SEE ALSO
EVP_PKEY_new(3), EVP_PKEY_decapsulate(3), EVP_PKEY_decrypt(3), EVP_PKEY_encapsulate(3), EVP_PKEY_encrypt(3), EVP_PKEY_derive(3), EVP_PKEY_keygen(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), EVP_PKEY_verify_recover(3)

## HISTORY
The provider PKEY interface was introduced in OpenSSL 3.0.

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


title: life_cycle-rand(7ossl)

summary: The RAND algorithm life\-cycle

text:
# life_cycle-rand(7ossl)

## NAME
life_cycle-rand - The RAND algorithm life-cycle

## DESCRIPTION
All random number generator (RANDs) go through a number of stages in their life-cycle:

start

This state represents the RAND before it has been allocated. It is the starting state for any life-cycle transitions.

newed

This state represents the RAND after it has been allocated but unable to generate any output.

instantiated

This state represents the RAND when it is set up and capable of generating output.

uninstantiated

This state represents the RAND when it has been shutdown and it is no longer capable of generating output.

freed

This state is entered when the RAND is freed. It is the terminal state for all life-cycle transitions.

### State Transition Diagram
The usual life-cycle of a RAND is illustrated:

+-------------------------+

| start |

+-------------------------+

|

| EVP_RAND_CTX_new

v

+-------------------------+

| newed |

+-------------------------+

|

| EVP_RAND_instantiate

v

EVP_RAND_generate +-------------------------+

+-------------------- | |

| | instantiated |

+-------------------> | | <+

+-------------------------+ '

| '

| EVP_RAND_uninstantiate ' EVP_RAND_instantiate

v '

+-------------------------+ '

| uninstantiated | -+

+-------------------------+

|

| EVP_RAND_CTX_free

v

+-------------------------+

| freed |

+-------------------------+

### Formal State Transitions
This section defines all of the legal state transitions. This is the canonical list.

Function Call ------------------ Current State ------------------

start newed instantiated uninstantiated freed

EVP_RAND_CTX_new newed

EVP_RAND_instantiate instantiated

EVP_RAND_generate instantiated

EVP_RAND_uninstantiate uninstantiated

EVP_RAND_CTX_free freed freed freed freed

EVP_RAND_CTX_get_params newed instantiated uninstantiated freed

EVP_RAND_CTX_set_params newed instantiated uninstantiated freed

EVP_RAND_CTX_gettable_params newed instantiated uninstantiated freed

EVP_RAND_CTX_settable_params newed instantiated uninstantiated freed

## NOTES
At some point the EVP layer will begin enforcing the transitions described herein.

## SEE ALSO
provider-rand(7), EVP_RAND(3).

## HISTORY
The provider RAND interface was introduced in OpenSSL 3.0.

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


openssl-core.h

title: openssl-core.h(7ossl)

summary: OpenSSL Core types

text:
# openssl-core.h(7ossl)

## NAME
openssl/core.h - OpenSSL Core types

## SYNOPSIS

```
 #include <openssl/core.h>
```

## DESCRIPTION
The <openssl/core.h> header defines a number of public types that are used to communicate between the OpenSSL libraries and implementation providers. These types are designed to minimise the need for intimate knowledge of internal structures between the OpenSSL libraries and the providers.

The types are:

OSSL_DISPATCH(3)

OSSL_ITEM(3)

OSSL_ALGORITHM(3)

OSSL_PARAM(3)

OSSL_CALLBACK(3)

OSSL_PASSPHRASE_CALLBACK(3)

## SEE ALSO
openssl-core_dispatch.h(7)

## HISTORY
The types described here were added in OpenSSL 3.0.

## COPYRIGHT
Copyright 2019-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-core_dispatch.h(7ossl)

text:
# openssl-core_dispatch.h(7ossl)

## NAME
openssl/core_dispatch.h - OpenSSL provider dispatch numbers and function types

## SYNOPSIS

```
 #include <openssl/core_dispatch.h>
```

## DESCRIPTION
The <openssl/core_dispatch.h> header defines all the operation numbers, dispatch numbers and provider interface function types currently available.

The operation and dispatch numbers are represented with macros, which are named as follows:

operation numbers

These macros have the form "OSSL_OP_opname".

dipatch numbers

These macros have the form "OSSL_FUNC_opname_funcname", where "opname" is the same as in the macro for the operation this function belongs to.

With every dispatch number, there is an associated function type.

For further information, please see the provider(7)

## SEE ALSO
provider(7)

## HISTORY
The types and macros described here were added in OpenSSL 3.0.

## COPYRIGHT
Copyright 2020 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-core_names.h(7ossl)

summary: OpenSSL provider parameter names

text:
# openssl-core_names.h(7ossl)

## NAME
openssl/core_names.h - OpenSSL provider parameter names

## SYNOPSIS

```
 #include <openssl/core_names.h>
```

## DESCRIPTION
The <openssl/core_names.h> header defines a multitude of macros for OSSL_PARAM(3) names, algorithm names and other known names used with OpenSSL's providers, made available for practical purposes only.

Existing names are further described in the manuals for OpenSSL's providers (see "SEE ALSO") and the manuals for each algorithm they provide (listed in those provider manuals).

## SEE ALSO
OSSL_PROVIDER-default(7), OSSL_PROVIDER-FIPS(7), OSSL_PROVIDER-legacy(7)

## HISTORY
The macros described here were added in OpenSSL 3.0.

## CAVEATS
This header file does not constitute a general registry of names. Providers that implement new algorithms are to be responsible for their own parameter names.

However, authors of provider that implement their own variants of algorithms that OpenSSL providers support will want to pay attention to the names provided in this header to work in a compatible manner.

## COPYRIGHT
Copyright 2020 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-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) and OPENSSL_riscvcap(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).

SSLKEYLOGFILE

Used to produce the standard format output file for SSL key logging. Optionally set this variable to a filename to log all secrets produced by SSL connections. Note, use of the environment variable is predicated on configuring OpenSSL at build time with the enable-sslkeylog feature. The file format standard can be found at <https://datatracker.ietf.org/doc/draft-ietf-tls-keylogfile/>. Note: the use of SSLKEYLOGFILE poses an explicit security risk. By recording the exchanged keys during an SSL session, it allows any available party with read access to the file to decrypt application traffic sent over that session. Use of this feature should be restricted to test and debug environments only.

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

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