title: OSSL_PROVIDER-FIPS(7ossl)

summary: OpenSSL FIPS provider

text:
# OSSL_PROVIDER-FIPS(7ossl)

## NAME
OSSL_PROVIDER-FIPS - OpenSSL FIPS provider

## DESCRIPTION
The OpenSSL FIPS provider is a special provider that conforms to the Federal Information Processing Standards (FIPS) specified in FIPS 140-3. This 'module' contains an approved set of cryptographic algorithms that is validated by an accredited testing laboratory.

### Properties
The implementations in this provider specifically have these properties defined:

"provider=fips"

"fips=yes"

It may be used in a property query string with fetching functions such as EVP_MD_fetch(3) or EVP_CIPHER_fetch(3), as well as with other functions that take a property query string, such as EVP_PKEY_CTX_new_from_name(3).

To be FIPS compliant, it is mandatory to include "fips=yes" as part of all property queries. This ensures that only FIPS approved implementations are used for cryptographic operations. The "fips=yes" query may also include other non-crypto support operations that are not in the FIPS provider, such as asymmetric key encoders, see "Asymmetric Key Management" in OSSL_PROVIDER-default(7).

It is not mandatory to include "provider=fips" as part of your property query. Including "provider=fips" in your property query guarantees that the OpenSSL FIPS provider is used for cryptographic operations rather than other FIPS capable providers.

### Provider parameters
See "Provider parameters" in provider-base(7) for a list of base parameters. Additionally the OpenSSL FIPS provider also supports the following gettable parameters:

"security-checks" (OSSL_OSSL_PROV_PARAM_SECURITY_CHECKS) <unsigned integer>

For further information refer to the openssl-fipsinstall(1) option -no_security_checks.

## OPERATIONS AND ALGORITHMS
The OpenSSL FIPS provider supports these operations and algorithms:

### Hashing Algorithms / Message Digests
SHA1, see EVP_MD-SHA1(7)

SHA2, see EVP_MD-SHA2(7)

SHA3, see EVP_MD-SHA3(7)

KECCAK-KMAC, see EVP_MD-KECCAK-KMAC(7)

SHAKE, see EVP_MD-SHAKE(7)

### Symmetric Ciphers
AES, see EVP_CIPHER-AES(7)

3DES, see EVP_CIPHER-DES(7)

This is an unapproved algorithm.

### Message Authentication Code (MAC)
CMAC, see EVP_MAC-CMAC(7)

GMAC, see EVP_MAC-GMAC(7)

HMAC, see EVP_MAC-HMAC(7)

KMAC, see EVP_MAC-KMAC(7)

### Key Derivation Function (KDF)
HKDF, see EVP_KDF-HKDF(7)

TLS13-KDF, see EVP_KDF-TLS13_KDF(7)

SSKDF, see EVP_KDF-SS(7)

PBKDF2, see EVP_KDF-PBKDF2(7)

SSHKDF, see EVP_KDF-SSHKDF(7)

TLS1-PRF, see EVP_KDF-TLS1_PRF(7)

KBKDF, see EVP_KDF-KB(7)

X942KDF-ASN1, see EVP_KDF-X942-ASN1(7)

X942KDF-CONCAT, see EVP_KDF-X942-CONCAT(7)

X963KDF, see EVP_KDF-X963(7)

### Key Exchange
DH, see EVP_KEYEXCH-DH(7)

ECDH, see EVP_KEYEXCH-ECDH(7)

X25519, see EVP_KEYEXCH-X25519(7)

X448, see EVP_KEYEXCH-X448(7)

TLS1-PRF

HKDF

### Asymmetric Signature
RSA, see EVP_SIGNATURE-RSA(7)

DSA, see EVP_SIGNATURE-DSA(7)

ED25519, see EVP_SIGNATURE-ED25519(7)

This is an unapproved algorithm.

ED448, see EVP_SIGNATURE-ED448(7)

This is an unapproved algorithm.

ECDSA, see EVP_SIGNATURE-ECDSA(7)

HMAC, see EVP_SIGNATURE-HMAC(7)

CMAC, see EVP_SIGNATURE-CMAC(7)

### Asymmetric Cipher
RSA, see EVP_ASYM_CIPHER-RSA(7)

### Asymmetric Key Encapsulation
RSA, see EVP_KEM-RSA(7)

### Asymmetric Key Management
DH, see EVP_KEYMGMT-DH(7)

DHX, see EVP_KEYMGMT-DHX(7)

DSA, see EVP_KEYMGMT-DSA(7)

RSA, see EVP_KEYMGMT-RSA(7)

RSA-PSS

EC, see EVP_KEYMGMT-EC(7)

X25519, see EVP_KEYMGMT-X25519(7)

X448, see EVP_KEYMGMT-X448(7)

ED25519, see EVP_KEYMGMT-ED25519(7)

This is an unapproved algorithm.

ED448, see EVP_KEYMGMT-ED448(7)

This is an unapproved algorithm.

TLS1-PRF

HKDF

HMAC, see EVP_KEYMGMT-HMAC(7)

CMAC, see EVP_KEYMGMT-CMAC(7)

### Random Number Generation
CTR-DRBG, see EVP_RAND-CTR-DRBG(7)

HASH-DRBG, see EVP_RAND-HASH-DRBG(7)

HMAC-DRBG, see EVP_RAND-HMAC-DRBG(7)

TEST-RAND, see EVP_RAND-TEST-RAND(7)

TEST-RAND is an unapproved algorithm.

## SELF TESTING
One of the requirements for the FIPS module is self testing. An optional callback mechanism is available to return information to the user using OSSL_SELF_TEST_set_callback(3).

The parameters passed to the callback are described in OSSL_SELF_TEST_new(3)

The OpenSSL FIPS module uses the following mechanism to provide information about the self tests as they run. This is useful for debugging if a self test is failing. The callback also allows forcing any self test to fail, in order to check that it operates correctly on failure. Note that all self tests run even if a self test failure occurs.

The FIPS module passes the following type(s) to OSSL_SELF_TEST_onbegin().

"Module_Integrity" (OSSL_SELF_TEST_TYPE_MODULE_INTEGRITY)

Uses HMAC SHA256 on the module file to validate that the module has not been modified. The integrity value is compared to a value written to a configuration file during installation.

"Install_Integrity" (OSSL_SELF_TEST_TYPE_INSTALL_INTEGRITY)

Uses HMAC SHA256 on a fixed string to validate that the installation process has already been performed and the self test KATS have already been tested, The integrity value is compared to a value written to a configuration file after successfully running the self tests during installation.

"KAT_Cipher" (OSSL_SELF_TEST_TYPE_KAT_CIPHER)

Known answer test for a symmetric cipher.

"KAT_AsymmetricCipher" (OSSL_SELF_TEST_TYPE_KAT_ASYM_CIPHER)

Known answer test for a asymmetric cipher.

"KAT_Digest" (OSSL_SELF_TEST_TYPE_KAT_DIGEST)

Known answer test for a digest.

"KAT_Signature" (OSSL_SELF_TEST_TYPE_KAT_SIGNATURE)

Known answer test for a signature.

"PCT_Signature" (OSSL_SELF_TEST_TYPE_PCT_SIGNATURE)

Pairwise Consistency check for a signature.

"KAT_KDF" (OSSL_SELF_TEST_TYPE_KAT_KDF)

Known answer test for a key derivation function.

"KAT_KA" (OSSL_SELF_TEST_TYPE_KAT_KA)

Known answer test for key agreement.

"DRBG" (OSSL_SELF_TEST_TYPE_DRBG)

Known answer test for a Deterministic Random Bit Generator.

"Conditional_PCT" (OSSL_SELF_TEST_TYPE_PCT)

Conditional test that is run during the generation of key pairs.

"Continuous_RNG_Test" (OSSL_SELF_TEST_TYPE_CRNG)

Continuous random number generator test.

The "Module_Integrity" self test is always run at startup. The "Install_Integrity" self test is used to check if the self tests have already been run at installation time. If they have already run then the self tests are not run on subsequent startups. All other self test categories are run once at installation time, except for the "Pairwise_Consistency_Test".

There is only one instance of the "Module_Integrity" and "Install_Integrity" self tests. All other self tests may have multiple instances.

The FIPS module passes the following descriptions(s) to OSSL_SELF_TEST_onbegin().

"HMAC" (OSSL_SELF_TEST_DESC_INTEGRITY_HMAC)

"Module_Integrity" and "Install_Integrity" use this.

"RSA" (OSSL_SELF_TEST_DESC_PCT_RSA_PKCS1)

"ECDSA" (OSSL_SELF_TEST_DESC_PCT_ECDSA)

"EDDSA" (OSSL_SELF_TEST_DESC_PCT_EDDSA)

"DSA" (OSSL_SELF_TEST_DESC_PCT_DSA)

Key generation tests used with the "Pairwise_Consistency_Test" type.

"RSA_Encrypt" (OSSL_SELF_TEST_DESC_ASYM_RSA_ENC)

"RSA_Decrypt" (OSSL_SELF_TEST_DESC_ASYM_RSA_DEC)

"KAT_AsymmetricCipher" uses this to indicate an encrypt or decrypt KAT.

"AES_GCM" (OSSL_SELF_TEST_DESC_CIPHER_AES_GCM)

"AES_ECB_Decrypt" (OSSL_SELF_TEST_DESC_CIPHER_AES_ECB)

"TDES" (OSSL_SELF_TEST_DESC_CIPHER_TDES)

Symmetric cipher tests used with the "KAT_Cipher" type.

"SHA1" (OSSL_SELF_TEST_DESC_MD_SHA1)

"SHA2" (OSSL_SELF_TEST_DESC_MD_SHA2)

"SHA3" (OSSL_SELF_TEST_DESC_MD_SHA3)

Digest tests used with the "KAT_Digest" type.

"DSA" (OSSL_SELF_TEST_DESC_SIGN_DSA)

"RSA" (OSSL_SELF_TEST_DESC_SIGN_RSA)

"ECDSA" (OSSL_SELF_TEST_DESC_SIGN_ECDSA)

Signature tests used with the "KAT_Signature" type.

"ECDH" (OSSL_SELF_TEST_DESC_KA_ECDH)

"DH" (OSSL_SELF_TEST_DESC_KA_DH)

Key agreement tests used with the "KAT_KA" type.

"HKDF" (OSSL_SELF_TEST_DESC_KDF_HKDF)

"TLS13_KDF_EXTRACT" (OSSL_SELF_TEST_DESC_KDF_TLS13_EXTRACT)

"TLS13_KDF_EXPAND" (OSSL_SELF_TEST_DESC_KDF_TLS13_EXPAND)

"SSKDF" (OSSL_SELF_TEST_DESC_KDF_SSKDF)

"X963KDF" (OSSL_SELF_TEST_DESC_KDF_X963KDF)

"X942KDF" (OSSL_SELF_TEST_DESC_KDF_X942KDF)

"PBKDF2" (OSSL_SELF_TEST_DESC_KDF_PBKDF2)

"SSHKDF" (OSSL_SELF_TEST_DESC_KDF_SSHKDF)

"TLS12_PRF" (OSSL_SELF_TEST_DESC_KDF_TLS12_PRF)

"KBKDF" (OSSL_SELF_TEST_DESC_KDF_KBKDF)

Key Derivation Function tests used with the "KAT_KDF" type.

"CTR" (OSSL_SELF_TEST_DESC_DRBG_CTR)

"HASH" (OSSL_SELF_TEST_DESC_DRBG_HASH)

"HMAC" (OSSL_SELF_TEST_DESC_DRBG_HMAC)

DRBG tests used with the "DRBG" type.

"RNG" (OSSL_SELF_TEST_DESC_RNG)

"Continuous_RNG_Test" uses this.

## EXAMPLES
A simple self test callback is shown below for illustrative purposes.

```
  #include <openssl/self_test.h>
  static OSSL_CALLBACK self_test_cb;
  static int self_test_cb(const OSSL_PARAM params[], void *arg)
  {
    int ret = 0;
    const OSSL_PARAM *p = NULL;
    const char *phase = NULL, *type = NULL, *desc = NULL;
    p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_PHASE);
    if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
        goto err;
    phase = (const char *)p->data;
    p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_DESC);
    if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
        goto err;
    desc = (const char *)p->data;
    p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_TYPE);
    if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
        goto err;
    type = (const char *)p->data;
    /* Do some logging */
    if (strcmp(phase, OSSL_SELF_TEST_PHASE_START) == 0)
        BIO_printf(bio_out, "%s : (%s) : ", desc, type);
    if (strcmp(phase, OSSL_SELF_TEST_PHASE_PASS) == 0
            || strcmp(phase, OSSL_SELF_TEST_PHASE_FAIL) == 0)
        BIO_printf(bio_out, "%s\n", phase);
    /* Corrupt the SHA1 self test during the 'corrupt' phase by returning 0 */
    if (strcmp(phase, OSSL_SELF_TEST_PHASE_CORRUPT) == 0
            && strcmp(desc, OSSL_SELF_TEST_DESC_MD_SHA1) == 0) {
        BIO_printf(bio_out, "%s %s", phase, desc);
        return 0;
    }
    ret = 1;
  err:
    return ret;
  }
```

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

The FIPS provider in OpenSSL 3.1 includes some non-FIPS validated algorithms, consequently the property query "fips=yes" is mandatory for applications that want to operate in a FIPS approved manner. The algorithms are:

Triple DES ECB

Triple DES CBC

EdDSA

## SEE ALSO
openssl-fipsinstall(1), fips_config(5), OSSL_SELF_TEST_set_callback(3), OSSL_SELF_TEST_new(3), OSSL_PARAM(3), openssl-core.h(7), openssl-core_dispatch.h(7), provider(7), <https://www.openssl.org/source/>

## HISTORY
This functionality was added in OpenSSL 3.0.

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


package: openssl

title: OSSL_PROVIDER-base(7ossl)

summary: OpenSSL base provider

text:
# OSSL_PROVIDER-base(7ossl)

## NAME
OSSL_PROVIDER-base - OpenSSL base provider

## DESCRIPTION
The OpenSSL base provider supplies the encoding for OpenSSL's asymmetric cryptography.

### Properties
The implementations in this provider specifically have this property defined:

"provider=base"

It may be used in a property query string with fetching functions.

It isn't mandatory to query for this property, except to make sure to get implementations of this provider and none other.

"type=parameters"

"type=private"

"type=public"

These may be used in a property query string with fetching functions to select which data are to be encoded. Either the private key material, the public key material or the domain parameters can be selected.

"format=der"

"format=pem"

"format=text"

These may be used in a property query string with fetching functions to select the encoding output format. Either the DER, PEM and plaintext are currently permitted.

## OPERATIONS AND ALGORITHMS
The OpenSSL base provider supports these operations and algorithms:

### Random Number Generation
SEED-SRC, see EVP_RAND-SEED-SRC(7)

In addition to this provider, the "SEED-SRC" algorithm is also available in the default provider.

### Asymmetric Key Encoder
RSA

RSA-PSS

DH

DHX

DSA

EC

ED25519

ED448

X25519

X448

SM2

In addition to this provider, all of these encoding algorithms are also available in the default provider. Some of these algorithms may be used in combination with the FIPS provider.

### Asymmetric Key Decoder
RSA

RSA-PSS

DH

DHX

DSA

EC

ED25519

ED448

X25519

X448

SM2

DER

In addition to this provider, all of these decoding algorithms are also available in the default provider. Some of these algorithms may be used in combination with the FIPS provider.

### Stores
file

org.openssl.winstore, see OSSL_STORE-winstore(7)

In addition to this provider, all of these store algorithms are also available in the default provider.

## SEE ALSO
OSSL_PROVIDER-default(7), openssl-core.h(7), openssl-core_dispatch.h(7), provider(7)

## HISTORY
This functionality was added in OpenSSL 3.0.

## COPYRIGHT
Copyright 2020-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: OSSL_PROVIDER-default(7ossl)

summary: OpenSSL default provider

text:
# OSSL_PROVIDER-default(7ossl)

## NAME
OSSL_PROVIDER-default - OpenSSL default provider

## DESCRIPTION
The OpenSSL default provider supplies the majority of OpenSSL's diverse algorithm implementations. If an application doesn't specify anything else explicitly (e.g. in the application or via config), then this is the provider that will be used as fallback: It is loaded automatically the first time that an algorithm is fetched from a provider or a function acting on providers is called and no other provider has been loaded yet.

If an attempt to load a provider has already been made (whether successful or not) then the default provider won't be loaded automatically. Therefore if the default provider is to be used in conjunction with other providers then it must be loaded explicitly. Automatic loading of the default provider only occurs a maximum of once; if the default provider is explicitly unloaded then the default provider will not be automatically loaded again.

### Properties
The implementations in this provider specifically have this property defined:

"provider=default"

It may be used in a property query string with fetching functions such as EVP_MD_fetch(3) or EVP_CIPHER_fetch(3), as well as with other functions that take a property query string, such as EVP_PKEY_CTX_new_from_name(3).

It isn't mandatory to query for this property, except to make sure to get implementations of this provider and none other.

Some implementations may define additional properties. Exact information is listed below

## OPERATIONS AND ALGORITHMS
The OpenSSL default provider supports these operations and algorithms:

### Hashing Algorithms / Message Digests
SHA1, see EVP_MD-SHA1(7)

SHA2, see EVP_MD-SHA2(7)

SHA3, see EVP_MD-SHA3(7)

KECCAK, see EVP_MD-KECCAK(7)

KECCAK-KMAC, see EVP_MD-KECCAK-KMAC(7)

SHAKE, see EVP_MD-SHAKE(7)

BLAKE2, see EVP_MD-BLAKE2(7)

SM3, see EVP_MD-SM3(7)

MD5, see EVP_MD-MD5(7)

MD5-SHA1, see EVP_MD-MD5-SHA1(7)

RIPEMD160, see EVP_MD-RIPEMD160(7)

NULL, see EVP_MD-NULL(7)

### Symmetric Ciphers
AES, see EVP_CIPHER-AES(7)

ARIA, see EVP_CIPHER-ARIA(7)

CAMELLIA, see EVP_CIPHER-CAMELLIA(7)

3DES, see EVP_CIPHER-DES(7)

SM4, see EVP_CIPHER-SM4(7)

ChaCha20, see EVP_CIPHER-CHACHA(7)

ChaCha20-Poly1305, see EVP_CIPHER-CHACHA(7)

NULL, see EVP_CIPHER-NULL(7)

### Message Authentication Code (MAC)
BLAKE2, see EVP_MAC-BLAKE2(7)

CMAC, see EVP_MAC-CMAC(7)

GMAC, see EVP_MAC-GMAC(7)

HMAC, see EVP_MAC-HMAC(7)

KMAC, see EVP_MAC-KMAC(7)

SIPHASH, see EVP_MAC-Siphash(7)

POLY1305, see EVP_MAC-Poly1305(7)

### Key Derivation Function (KDF)
HKDF, see EVP_KDF-HKDF(7)

TLS13-KDF, see EVP_KDF-TLS13_KDF(7)

SSKDF, see EVP_KDF-SS(7)

PBKDF2, see EVP_KDF-PBKDF2(7)

PKCS12KDF, see EVP_KDF-PKCS12KDF(7)

SSHKDF, see EVP_KDF-SSHKDF(7)

TLS1-PRF, see EVP_KDF-TLS1_PRF(7)

KBKDF, see EVP_KDF-KB(7)

X942KDF-ASN1, see EVP_KDF-X942-ASN1(7)

X942KDF-CONCAT, see EVP_KDF-X942-CONCAT(7)

X963KDF, see EVP_KDF-X963(7)

SCRYPT, see EVP_KDF-SCRYPT(7)

KRB5KDF, see EVP_KDF-KRB5KDF(7)

HMAC-DRBG, see EVP_KDF-HMAC-DRBG(7)

ARGON2, see EVP_KDF-ARGON2(7)

### Key Exchange
DH, see EVP_KEYEXCH-DH(7)

ECDH, see EVP_KEYEXCH-ECDH(7)

X25519, see EVP_KEYEXCH-X25519(7)

X448, see EVP_KEYEXCH-X448(7)

TLS1-PRF

HKDF

SCRYPT

### Asymmetric Signature
DSA, see EVP_SIGNATURE-DSA(7)

RSA, see EVP_SIGNATURE-RSA(7)

ED25519, see EVP_SIGNATURE-ED25519(7)

ED448, see EVP_SIGNATURE-ED448(7)

ECDSA, see EVP_SIGNATURE-ECDSA(7)

SM2

HMAC, see EVP_SIGNATURE-HMAC(7)

SIPHASH, see EVP_SIGNATURE-Siphash(7)

POLY1305, see EVP_SIGNATURE-Poly1305(7)

CMAC, see EVP_SIGNATURE-CMAC(7)

### Asymmetric Cipher
RSA, see EVP_ASYM_CIPHER-RSA(7)

SM2, see EVP_ASYM_CIPHER-SM2(7)

### Asymmetric Key Encapsulation
RSA, see EVP_KEM-RSA(7)

X25519, see EVP_KEM-X25519(7)

X448, see EVP_KEM-X448(7)

EC, see EVP_KEM-EC(7)

### Asymmetric Key Management
DH, see EVP_KEYMGMT-DH(7)

DHX, see EVP_KEYMGMT-DHX(7)

DSA, see EVP_KEYMGMT-DSA(7)

RSA, see EVP_KEYMGMT-RSA(7)

RSA-PSS

EC, see EVP_KEYMGMT-EC(7)

X25519, see EVP_KEYMGMT-X25519(7)

X448, see EVP_KEYMGMT-X448(7)

ED25519, see EVP_KEYMGMT-ED25519(7)

ED448, see EVP_KEYMGMT-ED448(7)

TLS1-PRF

HKDF

SCRYPT

HMAC, see EVP_KEYMGMT-HMAC(7)

SIPHASH, see EVP_KEYMGMT-Siphash(7)

POLY1305, see EVP_KEYMGMT-Poly1305(7)

CMAC, see EVP_KEYMGMT-CMAC(7)

SM2, see EVP_KEYMGMT-SM2(7)

### Random Number Generation
CTR-DRBG, see EVP_RAND-CTR-DRBG(7)

HASH-DRBG, see EVP_RAND-HASH-DRBG(7)

HMAC-DRBG, see EVP_RAND-HMAC-DRBG(7)

SEED-SRC, see EVP_RAND-SEED-SRC(7)

TEST-RAND, see EVP_RAND-TEST-RAND(7)

In addition to this provider, the "SEED-SRC" algorithm is also available in the base provider.

### Asymmetric Key Encoder
RSA

RSA-PSS

DH

DHX

DSA

EC

ED25519

ED448

X25519

X448

SM2

In addition to this provider, all of these encoding algorithms are also available in the base provider. Some of these algorithms may be used in combination with the FIPS provider.

### Asymmetric Key Decoder
RSA

RSA-PSS

DH

DHX

DSA

EC

ED25519

ED448

X25519

X448

SM2

DER

In addition to this provider, all of these decoding algorithms are also available in the base provider. Some of these algorithms may be used in combination with the FIPS provider.

### Stores
file

org.openssl.winstore, see OSSL_STORE-winstore(7)

In addition to this provider, all of these store algorithms are also available in the base provider.

## SEE ALSO
openssl-core.h(7), openssl-core_dispatch.h(7), provider(7), OSSL_PROVIDER-base(7)

## HISTORY
The RIPEMD160 digest was added to the default provider in OpenSSL 3.0.7.

All other functionality was added in OpenSSL 3.0.

## COPYRIGHT
Copyright 2020-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: OSSL_PROVIDER-legacy(7ossl)

summary: OpenSSL legacy provider

text:
# OSSL_PROVIDER-legacy(7ossl)

## NAME
OSSL_PROVIDER-legacy - OpenSSL legacy provider

## DESCRIPTION
The OpenSSL legacy provider supplies OpenSSL implementations of algorithms that have been deemed legacy. Such algorithms have commonly fallen out of use, have been deemed insecure by the cryptography community, or something similar.

We can consider this the retirement home of cryptographic algorithms.

### Properties
The implementations in this provider specifically has this property defined:

"provider=legacy"

It may be used in a property query string with fetching functions such as EVP_MD_fetch(3) or EVP_CIPHER_fetch(3), as well as with other functions that take a property query string, such as EVP_PKEY_CTX_new_from_name(3).

It isn't mandatory to query for any of these properties, except to make sure to get implementations of this provider and none other.

## OPERATIONS AND ALGORITHMS
The OpenSSL legacy provider supports these operations and algorithms:

### Hashing Algorithms / Message Digests
MD2, see EVP_MD-MD2(7)

Disabled by default. Use enable-md2 config option to enable.

MD4, see EVP_MD-MD4(7)

MDC2, see EVP_MD-MDC2(7)

WHIRLPOOL, see EVP_MD-WHIRLPOOL(7)

RIPEMD160, see EVP_MD-RIPEMD160(7)

### Symmetric Ciphers
Not all of these symmetric cipher algorithms are enabled by default.

Blowfish, see EVP_CIPHER-BLOWFISH(7)

CAST, see EVP_CIPHER-CAST(7)

DES, see EVP_CIPHER-DES(7)

The algorithm names are: DES_ECB, DES_CBC, DES_OFB, DES_CFB, DES_CFB1, DES_CFB8 and DESX_CBC.

IDEA, see EVP_CIPHER-IDEA(7)

RC2, see EVP_CIPHER-RC2(7)

RC4, see EVP_CIPHER-RC4(7)

RC5, see EVP_CIPHER-RC5(7)

Disabled by default. Use enable-rc5 config option to enable.

SEED, see EVP_CIPHER-SEED(7)

### Key Derivation Function (KDF)
PBKDF1

PVKKDF

## SEE ALSO
OSSL_PARAM(3), openssl-core.h(7), openssl-core_dispatch.h(7), provider(7)

## HISTORY
This functionality was added in OpenSSL 3.0.

## COPYRIGHT
Copyright 2020-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: OSSL_PROVIDER-null(7ossl)

summary: OpenSSL null provider

text:
# OSSL_PROVIDER-null(7ossl)

## NAME
OSSL_PROVIDER-null - OpenSSL null provider

## DESCRIPTION
The OpenSSL null provider supplies no algorithms.

It can used to guarantee that the default library context and a fallback provider will not be accidentally accessed.

### Properties
The null provider defines no properties.

## OPERATIONS AND ALGORITHMS
The OpenSSL null provider supports no operations and algorithms.

## SEE ALSO
provider(7)

## HISTORY
This functionality was 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: OSSL_STORE-winstore(7ossl)

summary: OpenSSL built in OSSL_STORE for Windows

text:
# OSSL_STORE-winstore(7ossl)

## NAME
OSSL_STORE-winstore - OpenSSL built in OSSL_STORE for Windows

## DESCRIPTION
The OSSL_STORE implementation for Windows provides access to Windows' system "ROOT" certificate store through URIs, using the URI scheme "org.openssl.winstore".

### Supported URIs
There is only one supported URI:

```
  org.openssl.winstore:
```

No authority (host, etc), no path, no query, no fragment.

### Supported OSSL_STORE_SEARCH operations
OSSL_STORE_SEARCH_by_name(3)

As a matter of fact, this must be used. It is not possible to enumerate all available certificates in the store.

### Windows certificate store features
Apart from diverse constraints present in the certificates themselves, the Windows certificate store also has the ability to associate additional constraining properties alongside a certificate in the store. This includes both documented and undocumented capabilities:

- The documented capability to override EKU

- The undocumented capability to add name constraints

- The undocumented capability to override the certificate expiry date

Such constraints are not checked by this OSSL_STORE implementation, and thereby not honoured.

However, once extracted with OSSL_STORE_load(3), certificates that have constraints in their X.509 extensions will go through the usual constraint checks when used by OpenSSL, and are thereby honoured.

## SEE ALSO
ossl_store(7), OSSL_STORE_open_ex(3), OSSL_STORE_SEARCH(3)

## HISTORY
The winstore ("org.openssl.winstore") implementation was added in OpenSSL 3.2.0.

## NOTES
OpenSSL uses OSSL_DECODER(3) implementations under the hood. To influence what OSSL_DECODER(3) implementations are used, it's advisable to use OSSL_STORE_open_ex(3) and set the propq argument.

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


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.

## 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), EVP_RAND(7)

## COPYRIGHT
Copyright 2018-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


RSA-PSS

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


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 base 64 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-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: 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).

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

The FIPS provider in OpenSSL 3.1 includes some non-FIPS validated algorithms, consequently the property query "fips=yes" is mandatory for applications that want to operate in a FIPS approved manner. The algorithms are:

Triple DES ECB

Triple DES CBC

EdDSA

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

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