title: EVP_KDF-HKDF(7ossl)

summary: The HKDF EVP_KDF implementation

text:
# EVP_KDF-HKDF(7ossl)

## NAME
EVP_KDF-HKDF - The HKDF EVP_KDF implementation

## DESCRIPTION
Support for computing the HKDF KDF through the EVP_KDF API.

The EVP_KDF-HKDF algorithm implements the HKDF key derivation function. HKDF follows the "extract-then-expand" paradigm, where the KDF logically consists of two modules. The first stage takes the input keying material and "extracts" from it a fixed-length pseudorandom key K. The second stage "expands" the key K into several additional pseudorandom keys (the output of the KDF).

The output is considered to be keying material.

### Identity
"HKDF" is the name for this implementation; it can be used with the EVP_KDF_fetch() function.

### Supported parameters
The supported parameters are:

"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>

"digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>

"key" (OSSL_KDF_PARAM_KEY) <octet string>

"salt" (OSSL_KDF_PARAM_SALT) <octet string>

These parameters work as described in "PARAMETERS" in EVP_KDF(3).

"info" (OSSL_KDF_PARAM_INFO) <octet string>

This parameter sets the info value. The length of the context info buffer cannot exceed 1024 bytes; this should be more than enough for any normal use of HKDF.

"mode" (OSSL_KDF_PARAM_MODE) <UTF8 string> or <integer>

This parameter sets the mode for the HKDF operation. There are three modes that are currently defined:

"EXTRACT_AND_EXPAND" or EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND

This is the default mode. Calling EVP_KDF_derive(3) on an EVP_KDF_CTX set up for HKDF will perform an extract followed by an expand operation in one go. The derived key returned will be the result after the expand operation. The intermediate fixed-length pseudorandom key K is not returned. In this mode the digest, key, salt and info values must be set before a key is derived otherwise an error will occur.

"EXTRACT_ONLY" or EVP_KDF_HKDF_MODE_EXTRACT_ONLY

In this mode calling EVP_KDF_derive(3) will just perform the extract operation. The value returned will be the intermediate fixed-length pseudorandom key K. The keylen parameter must match the size of K, which can be looked up by calling EVP_KDF_CTX_get_kdf_size() after setting the mode and digest. The digest, key and salt values must be set before a key is derived otherwise an error will occur.

"EXPAND_ONLY" or EVP_KDF_HKDF_MODE_EXPAND_ONLY

In this mode calling EVP_KDF_derive(3) will just perform the expand operation. The input key should be set to the intermediate fixed-length pseudorandom key K returned from a previous extract operation. The digest, key and info values must be set before a key is derived otherwise an error will occur.

The OpenSSL FIPS provider also supports the following parameters:

"fips-indicator" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) <integer>

A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling EVP_KDF_derive. It returns 0 if "key-check" is set to 0 and the check fails.

"key-check" (OSSL_KDF_PARAM_FIPS_KEY_CHECK) <integer>

The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the length of used key-derivation key (OSSL_KDF_PARAM_KEY) is shorter than 112 bits. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. This option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0.

## NOTES
A context for HKDF can be obtained by calling:

```
 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "HKDF", NULL);
 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
```

The output length of an HKDF expand operation is specified via the keylen parameter to the EVP_KDF_derive(3) function. When using EVP_KDF_HKDF_MODE_EXTRACT_ONLY the keylen parameter must equal the size of the intermediate fixed-length pseudorandom key otherwise an error will occur. For that mode, the fixed output size can be looked up by calling EVP_KDF_CTX_get_kdf_size() after setting the mode and digest on the EVP_KDF_CTX.

## EXAMPLES
This example derives 10 bytes using SHA-256 with the secret key "secret", salt value "salt" and info value "label":

```
 EVP_KDF *kdf;
 EVP_KDF_CTX *kctx;
 unsigned char out[10];
 OSSL_PARAM params[5], *p = params;
 kdf = EVP_KDF_fetch(NULL, "HKDF", NULL);
 kctx = EVP_KDF_CTX_new(kdf);
 EVP_KDF_free(kdf);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
                                         SN_sha256, strlen(SN_sha256));
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
                                          "secret", (size_t)6);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
                                          "label", (size_t)5);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
                                          "salt", (size_t)4);
 *p = OSSL_PARAM_construct_end();
 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
     error("EVP_KDF_derive");
 }
 EVP_KDF_CTX_free(kctx);
```

## CONFORMING TO
RFC 5869

## SEE ALSO
EVP_KDF(3), EVP_KDF_CTX_new(3), EVP_KDF_CTX_free(3), EVP_KDF_CTX_get_kdf_size(3), EVP_KDF_CTX_set_params(3), EVP_KDF_derive(3), "PARAMETERS" in EVP_KDF(3), EVP_KDF-TLS13_KDF(7)

## HISTORY
This functionality was added in OpenSSL 3.0.

## COPYRIGHT
Copyright 2016-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: EVP_KDF-HMAC-DRBG(7ossl)

summary: HMAC\-DRBG

text:
# EVP_KDF-HMAC-DRBG(7ossl)

## NAME
EVP_KDF-HMAC-DRBG - The HMAC DRBG DETERMINISTIC EVP_KDF implementation

## DESCRIPTION
Support for a deterministic HMAC DRBG using the EVP_KDF API. This is similar to EVP_RAND-HMAC-DRBG(7), but uses fixed values for its entropy and nonce values. This is used to generate deterministic nonce value required by ECDSA and DSA (as defined in RFC 6979).

### Identity
"HMAC-DRBG-KDF" is the name for this implementation; it can be used with the EVP_KDF_fetch() function.

### Supported parameters
The supported parameters are:

"digest" (OSSL_DRBG_PARAM_DIGEST) <UTF8 string>

"properties" (OSSL_DRBG_PARAM_PROPERTIES) <UTF8 string>

These parameters work as described in "PARAMETERS" in EVP_KDF(3).

"entropy" (OSSL_KDF_PARAM_HMACDRBG_ENTROPY) <octet string>

Sets the entropy bytes supplied to the HMAC-DRBG.

"nonce" (OSSL_KDF_PARAM_HMACDRBG_NONCE) <octet string>

Sets the nonce bytes supplied to the HMAC-DRBG.

## NOTES
A context for KDF HMAC DRBG can be obtained by calling:

```
 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "HMAC-DRBG-KDF", NULL);
 EVP_KDF_CTX *kdf_ctx = EVP_KDF_CTX_new(kdf, NULL);
```

## CONFORMING TO
RFC 6979

## SEE ALSO
EVP_KDF(3), "PARAMETERS" in EVP_KDF(3)

## HISTORY
The EVP_KDF-HMAC-DRBG functionality was added in OpenSSL 3.2.

## COPYRIGHT
Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.

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

branch: sisyphus


title: EVP_KDF-KB(7ossl)

summary: The Key\-Based EVP_KDF implementation

text:
# EVP_KDF-KB(7ossl)

## NAME
EVP_KDF-KB - The Key-Based EVP_KDF implementation

## DESCRIPTION
The EVP_KDF-KB algorithm implements the Key-Based key derivation function (KBKDF). KBKDF derives a key from repeated application of a keyed MAC to an input secret (and other optional values).

The output is considered to be keying material.

### Identity
"KBKDF" is the name for this implementation; it can be used with the EVP_KDF_fetch() function.

### Supported parameters
The supported parameters are:

"mode" (OSSL_KDF_PARAM_MODE) <UTF8 string>

The mode parameter determines which flavor of KBKDF to use - currently the choices are "counter" and "feedback". "counter" is the default, and will be used if unspecified.

"mac" (OSSL_KDF_PARAM_MAC) <UTF8 string>

The value is either CMAC, HMAC, KMAC128 or KMAC256.

"digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>

"cipher" (OSSL_KDF_PARAM_CIPHER) <UTF8 string>

"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>

"key" (OSSL_KDF_PARAM_KEY) <octet string>

"salt" (OSSL_KDF_PARAM_SALT) <octet string>

"info (OSSL_KDF_PARAM_INFO) <octet string>

"seed" (OSSL_KDF_PARAM_SEED) <octet string>

The seed parameter is unused in counter mode.

"use-l" (OSSL_KDF_PARAM_KBKDF_USE_L) <integer>

Set to 0 to disable use of the optional Fixed Input data 'L' (see SP800-108). The default value of 1 will be used if unspecified.

"use-separator" (OSSL_KDF_PARAM_KBKDF_USE_SEPARATOR) <integer>

Set to 0 to disable use of the optional Fixed Input data 'zero separator' (see SP800-108) that is placed between the Label and Context. The default value of 1 will be used if unspecified.

"r" (OSSL_KDF_PARAM_KBKDF_R) <integer>

Set the fixed value 'r', indicating the length of the counter in bits. Supported values are 8, 16, 24, and 32. The default value of 32 will be used if unspecified.

The OpenSSL FIPS provider also supports the following parameters:

"fips-indicator" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) <integer>

A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling EVP_KDF_derive. It returns 0 if "key-check" is set to 0 and the check fails.

"key-check" (OSSL_KDF_PARAM_FIPS_KEY_CHECK) <integer>

The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the length of used key-derivation key (OSSL_KDF_PARAM_KEY) is shorter than 112 bits. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. This option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0.

Depending on whether mac is CMAC or HMAC, either digest or cipher is required (respectively) and the other is unused. They are unused for KMAC128 and KMAC256.

The parameters key, salt, info, and seed correspond to KI, Label, Context, and IV (respectively) in SP800-108. As in that document, salt, info, and seed are optional and may be omitted.

"mac", "digest", cipher" and "properties" are described in "PARAMETERS" in EVP_KDF(3).

## NOTES
A context for KBKDF can be obtained by calling:

```
 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL);
 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
```

The output length of an KBKDF is specified via the "keylen" parameter to the EVP_KDF_derive(3) function.

Note that currently OpenSSL only implements counter and feedback modes. Other variants may be supported in the future.

## EXAMPLES
This example derives 10 bytes using COUNTER-HMAC-SHA256, with KI "secret", Label "label", and Context "context".

```
 EVP_KDF *kdf;
 EVP_KDF_CTX *kctx;
 unsigned char out[10];
 OSSL_PARAM params[6], *p = params;
 kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL);
 kctx = EVP_KDF_CTX_new(kdf);
 EVP_KDF_free(kdf);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
                                         "SHA2-256", 0);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
                                         "HMAC", 0);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
                                          "secret", strlen("secret"));
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
                                          "label", strlen("label"));
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
                                          "context", strlen("context"));
 *p = OSSL_PARAM_construct_end();
 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0)
     error("EVP_KDF_derive");
 EVP_KDF_CTX_free(kctx);
```

This example derives 10 bytes using FEEDBACK-CMAC-AES256, with KI "secret", Label "label", and IV "sixteen bytes iv".

```
 EVP_KDF *kdf;
 EVP_KDF_CTX *kctx;
 unsigned char out[10];
 OSSL_PARAM params[8], *p = params;
 unsigned char *iv = "sixteen bytes iv";
 kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL);
 kctx = EVP_KDF_CTX_new(kdf);
 EVP_KDF_free(kdf);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CIPHER, "AES256", 0);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, "CMAC", 0);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MODE, "FEEDBACK", 0);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
                                          "secret", strlen("secret"));
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
                                          "label", strlen("label"));
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
                                          "context", strlen("context"));
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED,
                                          iv, strlen(iv));
 *p = OSSL_PARAM_construct_end();
 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0)
     error("EVP_KDF_derive");
 EVP_KDF_CTX_free(kctx);
```

## CONFORMING TO
NIST SP800-108, IETF RFC 6803, IETF RFC 8009.

## SEE ALSO
EVP_KDF(3), EVP_KDF_CTX_free(3), EVP_KDF_CTX_get_kdf_size(3), EVP_KDF_derive(3), "PARAMETERS" in EVP_KDF(3)

## HISTORY
This functionality was added in OpenSSL 3.0.

Support for KMAC was added in OpenSSL 3.1.

## COPYRIGHT
Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved. Copyright 2019 Red Hat, Inc.

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: EVP_KDF-KRB5KDF(7ossl)

text:
# EVP_KDF-KRB5KDF(7ossl)

## NAME
EVP_KDF-KRB5KDF - The RFC3961 Krb5 KDF EVP_KDF implementation

## DESCRIPTION
Support for computing the KRB5KDF KDF through the EVP_KDF API.

The EVP_KDF-KRB5KDF algorithm implements the key derivation function defined in RFC 3961, section 5.1 and is used by Krb5 to derive session keys. Three inputs are required to perform key derivation: a cipher, (for example AES-128-CBC), the initial key, and a constant.

### Identity
"KRB5KDF" is the name for this implementation; it can be used with the EVP_KDF_fetch() function.

### Supported parameters
The supported parameters are:

"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>

"cipher" (OSSL_KDF_PARAM_CIPHER) <UTF8 string>

"key" (OSSL_KDF_PARAM_KEY) <octet string>

These parameters work as described in "PARAMETERS" in EVP_KDF(3).

"constant" (OSSL_KDF_PARAM_CONSTANT) <octet string>

This parameter sets the constant value for the KDF. If a value is already set, the contents are replaced.

## NOTES
A context for KRB5KDF can be obtained by calling:

```
 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "KRB5KDF", NULL);
 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
```

The output length of the KRB5KDF derivation is specified via the keylen parameter to the EVP_KDF_derive(3) function, and MUST match the key length for the chosen cipher or an error is returned. Moreover, the constant's length must not exceed the block size of the cipher. Since the KRB5KDF output length depends on the chosen cipher, calling EVP_KDF_CTX_get_kdf_size(3) to obtain the requisite length returns the correct length only after the cipher is set. Prior to that EVP_MAX_KEY_LENGTH is returned. The caller must allocate a buffer of the correct length for the chosen cipher, and pass that buffer to the EVP_KDF_derive(3) function along with that length.

## EXAMPLES
This example derives a key using the AES-128-CBC cipher:

```
 EVP_KDF *kdf;
 EVP_KDF_CTX *kctx;
 unsigned char key[16] = "01234...";
 unsigned char constant[] = "I'm a constant";
 unsigned char out[16];
 size_t outlen = sizeof(out);
 OSSL_PARAM params[4], *p = params;
 kdf = EVP_KDF_fetch(NULL, "KRB5KDF", NULL);
 kctx = EVP_KDF_CTX_new(kdf);
 EVP_KDF_free(kdf);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CIPHER,
                                         SN_aes_128_cbc,
                                         strlen(SN_aes_128_cbc));
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
                                          key, (size_t)16);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_CONSTANT,
                                          constant, strlen(constant));
 *p = OSSL_PARAM_construct_end();
 if (EVP_KDF_derive(kctx, out, outlen, params) <= 0)
     /* Error */
 EVP_KDF_CTX_free(kctx);
```

## CONFORMING TO
RFC 3961

## SEE ALSO
EVP_KDF(3), EVP_KDF_CTX_free(3), EVP_KDF_CTX_get_kdf_size(3), EVP_KDF_derive(3), "PARAMETERS" in EVP_KDF(3)

## HISTORY
This functionality was added in OpenSSL 3.0.

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

summary: The PBKDF1 EVP_KDF implementation

text:
# EVP_KDF-PBKDF1(7ossl)

## NAME
EVP_KDF-PBKDF1 - The PBKDF1 EVP_KDF implementation

## DESCRIPTION
Support for computing the PBKDF1 password-based KDF through the EVP_KDF API.

The EVP_KDF-PBKDF1 algorithm implements the PBKDF1 password-based key derivation function, as described in RFC 8018; it derives a key from a password using a salt and iteration count.

### Identity
"PBKDF1" is the name for this implementation; it can be used with the EVP_KDF_fetch() function.

### Supported parameters
The supported parameters are:

"pass" (OSSL_KDF_PARAM_PASSWORD) <octet string>

"salt" (OSSL_KDF_PARAM_SALT) <octet string>

"iter" (OSSL_KDF_PARAM_ITER) <unsigned integer>

This parameter has a default value of 0 and should be set.

"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>

"digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>

These parameters work as described in "PARAMETERS" in EVP_KDF(3).

## NOTES
A typical application of this algorithm is to derive keying material for an encryption algorithm from a password in the "pass", a salt in "salt", and an iteration count.

Increasing the "iter" parameter slows down the algorithm which makes it harder for an attacker to perform a brute force attack using a large number of candidate passwords.

No assumption is made regarding the given password; it is simply treated as a byte sequence.

The legacy provider needs to be available in order to access this algorithm.

## CONFORMING TO
RFC 8018

## SEE ALSO
EVP_KDF(3), EVP_KDF_CTX_new(3), EVP_KDF_CTX_free(3), EVP_KDF_CTX_set_params(3), EVP_KDF_derive(3), "PARAMETERS" in EVP_KDF(3), OSSL_PROVIDER-legacy(7)

## HISTORY
This functionality was added 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: EVP_KDF-PBKDF2(7ossl)

summary: The PBKDF2 EVP_KDF implementation

text:
# EVP_KDF-PBKDF2(7ossl)

## NAME
EVP_KDF-PBKDF2 - The PBKDF2 EVP_KDF implementation

## DESCRIPTION
Support for computing the PBKDF2 password-based KDF through the EVP_KDF API.

The EVP_KDF-PBKDF2 algorithm implements the PBKDF2 password-based key derivation function, as described in SP800-132; it derives a key from a password using a salt and iteration count.

The output is considered to be a cryptographic key.

### Identity
"PBKDF2" is the name for this implementation; it can be used with the EVP_KDF_fetch() function.

### Supported parameters
The supported parameters are:

"pass" (OSSL_KDF_PARAM_PASSWORD) <octet string>

"salt" (OSSL_KDF_PARAM_SALT) <octet string>

"iter" (OSSL_KDF_PARAM_ITER) <unsigned integer>

This parameter has a default value of 2048.

"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>

"digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>

These parameters work as described in "PARAMETERS" in EVP_KDF(3).

"pkcs5" (OSSL_KDF_PARAM_PKCS5) <integer>

This parameter can be used to enable or disable SP800-132 compliance checks. Setting the mode to 0 enables the compliance checks. The checks performed are:

- the iteration count is at least 1000.

- the salt length is at least 128 bits.

- the derived key length is at least 112 bits.

The default provider uses a default mode of 1 for backwards compatibility, and the FIPS provider uses a default mode of 0. This option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0.

"fips-indicator" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) <integer>

This option is used by the OpenSSL FIPS provider. A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling EVP_KDF_derive. It returns 0 if "pkcs5" is set to 1 and the derived key length, salt length or iteration count test fails.

## NOTES
A typical application of this algorithm is to derive keying material for an encryption algorithm from a password in the "pass", a salt in "salt", and an iteration count.

Increasing the "iter" parameter slows down the algorithm which makes it harder for an attacker to perform a brute force attack using a large number of candidate passwords.

No assumption is made regarding the given password; it is simply treated as a byte sequence.

## CONFORMING TO
SP800-132

## SEE ALSO
EVP_KDF(3), EVP_KDF_CTX_new(3), EVP_KDF_CTX_free(3), EVP_KDF_CTX_set_params(3), EVP_KDF_derive(3), "PARAMETERS" in EVP_KDF(3)

## HISTORY
This functionality was added in OpenSSL 3.0.

## COPYRIGHT
Copyright 2018-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: EVP_KDF-PKCS12KDF(7ossl)

summary: The PKCS#12 EVP_KDF implementation

text:
# EVP_KDF-PKCS12KDF(7ossl)

## NAME
EVP_KDF-PKCS12KDF - The PKCS#12 EVP_KDF implementation

## DESCRIPTION
Support for computing the PKCS#12 password-based KDF through the EVP_KDF API.

The EVP_KDF-PKCS12KDF algorithm implements the PKCS#12 password-based key derivation function, as described in appendix B of RFC 7292 (PKCS #12: Personal Information Exchange Syntax); it derives a key from a password using a salt, iteration count and the intended usage.

### Identity
"PKCS12KDF" is the name for this implementation; it can be used with the EVP_KDF_fetch() function.

### Supported parameters
The supported parameters are:

"pass" (OSSL_KDF_PARAM_PASSWORD) <octet string>

"salt" (OSSL_KDF_PARAM_SALT) <octet string>

"iter" (OSSL_KDF_PARAM_ITER) <unsigned integer>

"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>

"digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>

These parameters work as described in "PARAMETERS" in EVP_KDF(3).

"id" (OSSL_KDF_PARAM_PKCS12_ID) <integer>

This parameter is used to specify the intended usage of the output bits, as per RFC 7292 section B.3.

## NOTES
This algorithm is not available in the FIPS provider as it is not FIPS approvable.

A typical application of this algorithm is to derive keying material for an encryption algorithm from a password in the "pass", a salt in "salt", and an iteration count.

Increasing the "iter" parameter slows down the algorithm which makes it harder for an attacker to perform a brute force attack using a large number of candidate passwords.

No assumption is made regarding the given password; it is simply treated as a byte sequence.

## CONFORMING TO
RFC7292

## SEE ALSO
EVP_KDF(3), EVP_KDF_CTX_new(3), EVP_KDF_CTX_free(3), EVP_KDF_CTX_set_params(3), EVP_KDF_derive(3), "PARAMETERS" in EVP_KDF(3), OSSL_PROVIDER-FIPS(7)

## HISTORY
This functionality was added in OpenSSL 3.0.

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

summary: The PVK EVP_KDF implementation

text:
# EVP_KDF-PVKKDF(7ossl)

## NAME
EVP_KDF-PVKKDF - The PVK EVP_KDF implementation

## DESCRIPTION
Support for computing the PVK KDF PIN-based KDF through the EVP_KDF API.

The EVP_KDF-PVKKDF algorithm implements a PVK PIN-based key derivation function; it derives a key from a password using a salt.

### Identity
"PVKKDF" is the name for this implementation; it can be used with the EVP_KDF_fetch() function.

### Supported parameters
The supported parameters are:

"pass" (OSSL_KDF_PARAM_PASSWORD) <octet string>

"salt" (OSSL_KDF_PARAM_SALT) <octet string>

"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>

"digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>

These parameters work as described in "PARAMETERS" in EVP_KDF(3).

## NOTES
A typical application of this algorithm is to derive keying material for an encryption algorithm from a password in the "pass" and a salt in "salt".

No assumption is made regarding the given password; it is simply treated as a byte sequence.

The legacy provider needs to be available in order to access this algorithm.

## SEE ALSO
EVP_KDF(3), EVP_KDF_CTX_new(3), EVP_KDF_CTX_free(3), EVP_KDF_CTX_set_params(3), EVP_KDF_derive(3), "PARAMETERS" in EVP_KDF(3), OSSL_PROVIDER-legacy(7)

## HISTORY
This functionality was added in OpenSSL 3.2.

## 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: EVP_KDF-SCRYPT(7ossl)

summary: The scrypt EVP_KDF implementation

text:
# EVP_KDF-SCRYPT(7ossl)

## NAME
EVP_KDF-SCRYPT - The scrypt EVP_KDF implementation

## DESCRIPTION
Support for computing the scrypt password-based KDF through the EVP_KDF API.

The EVP_KDF-SCRYPT algorithm implements the scrypt password-based key derivation function, as described in RFC 7914. It is memory-hard in the sense that it deliberately requires a significant amount of RAM for efficient computation. The intention of this is to render brute forcing of passwords on systems that lack large amounts of main memory (such as GPUs or ASICs) computationally infeasible.

scrypt provides three work factors that can be customized: N, r and p. N, which has to be a positive power of two, is the general work factor and scales CPU time in an approximately linear fashion. r is the block size of the internally used hash function and p is the parallelization factor. Both r and p need to be greater than zero. The amount of RAM that scrypt requires for its computation is roughly (128 * N * r * p) bytes.

In the original paper of Colin Percival ("Stronger Key Derivation via Sequential Memory-Hard Functions", 2009), the suggested values that give a computation time of less than 5 seconds on a 2.5 GHz Intel Core 2 Duo are N = 2^20 = 1048576, r = 8, p = 1. Consequently, the required amount of memory for this computation is roughly 1 GiB. On a more recent CPU (Intel i7-5930K at 3.5 GHz), this computation takes about 3 seconds. When N, r or p are not specified, they default to 1048576, 8, and 1, respectively. The maximum amount of RAM that may be used by scrypt defaults to 1025 MiB.

### Identity
"SCRYPT" is the name for this implementation; it can be used with the EVP_KDF_fetch() function.

### Supported parameters
The supported parameters are:

"pass" (OSSL_KDF_PARAM_PASSWORD) <octet string>

"salt" (OSSL_KDF_PARAM_SALT) <octet string>

These parameters work as described in "PARAMETERS" in EVP_KDF(3).

"n" (OSSL_KDF_PARAM_SCRYPT_N) <unsigned integer>

"r" (OSSL_KDF_PARAM_SCRYPT_R) <unsigned integer>

"p" (OSSL_KDF_PARAM_SCRYPT_P) <unsigned integer>

"maxmem_bytes" (OSSL_KDF_PARAM_SCRYPT_MAXMEM) <unsigned integer>

These parameters configure the scrypt work factors N, r, maxmem and p. Both N and maxmem_bytes are parameters of type uint64_t. Both r and p are parameters of type uint32_t.

"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>

This can be used to set the property query string when fetching the fixed digest internally. NULL is used if this value is not set.

## NOTES
A context for scrypt can be obtained by calling:

```
 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL);
 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
```

The output length of an scrypt key derivation is specified via the "keylen" parameter to the EVP_KDF_derive(3) function.

## EXAMPLES
This example derives a 64-byte long test vector using scrypt with the password "password", salt "NaCl" and N = 1024, r = 8, p = 16.

```
 EVP_KDF *kdf;
 EVP_KDF_CTX *kctx;
 unsigned char out[64];
 OSSL_PARAM params[6], *p = params;
 kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL);
 kctx = EVP_KDF_CTX_new(kdf);
 EVP_KDF_free(kdf);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_PASSWORD,
                                          "password", (size_t)8);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
                                          "NaCl", (size_t)4);
 *p++ = OSSL_PARAM_construct_uint64(OSSL_KDF_PARAM_SCRYPT_N, (uint64_t)1024);
 *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_R, (uint32_t)8);
 *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_P, (uint32_t)16);
 *p = OSSL_PARAM_construct_end();
 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
     error("EVP_KDF_derive");
 }
 {
     const unsigned char expected[sizeof(out)] = {
         0xfd, 0xba, 0xbe, 0x1c, 0x9d, 0x34, 0x72, 0x00,
         0x78, 0x56, 0xe7, 0x19, 0x0d, 0x01, 0xe9, 0xfe,
         0x7c, 0x6a, 0xd7, 0xcb, 0xc8, 0x23, 0x78, 0x30,
         0xe7, 0x73, 0x76, 0x63, 0x4b, 0x37, 0x31, 0x62,
         0x2e, 0xaf, 0x30, 0xd9, 0x2e, 0x22, 0xa3, 0x88,
         0x6f, 0xf1, 0x09, 0x27, 0x9d, 0x98, 0x30, 0xda,
         0xc7, 0x27, 0xaf, 0xb9, 0x4a, 0x83, 0xee, 0x6d,
         0x83, 0x60, 0xcb, 0xdf, 0xa2, 0xcc, 0x06, 0x40
     };
     assert(!memcmp(out, expected, sizeof(out)));
 }
 EVP_KDF_CTX_free(kctx);
```

## CONFORMING TO
RFC 7914

## SEE ALSO
EVP_KDF(3), EVP_KDF_CTX_new(3), EVP_KDF_CTX_free(3), EVP_KDF_CTX_set_params(3), EVP_KDF_derive(3), "PARAMETERS" in EVP_KDF(3)

## HISTORY
This functionality was added in OpenSSL 3.0.

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

text:
# EVP_KDF-SS(7ossl)

## NAME
EVP_KDF-SS - The Single Step / One Step EVP_KDF implementation

## DESCRIPTION
The EVP_KDF-SS algorithm implements the Single Step key derivation function (SSKDF). SSKDF derives a key using input such as a shared secret key (that was generated during the execution of a key establishment scheme) and fixedinfo. SSKDF is also informally referred to as 'Concat KDF'.

The output is considered to be keying material.

### Auxiliary function
The implementation uses a selectable auxiliary function H, which can be one of:

H(x) = hash(x, digest=md)

H(x) = HMAC_hash(x, key=salt, digest=md)

H(x) = KMACxxx(x, key=salt, custom="KDF", outlen=mac_size)

Both the HMAC and KMAC implementations set the key using the 'salt' value. The hash and HMAC also require the digest to be set.

### Identity
"SSKDF" is the name for this implementation; it can be used with the EVP_KDF_fetch() function.

### Supported parameters
The supported parameters are:

"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>

"digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>

This parameter is ignored for KMAC.

"mac" (OSSL_KDF_PARAM_MAC) <UTF8 string>

"maclen" (OSSL_KDF_PARAM_MAC_SIZE) <unsigned integer>

"salt" (OSSL_KDF_PARAM_SALT) <octet string>

These parameters work as described in "PARAMETERS" in EVP_KDF(3).

"key" (OSSL_KDF_PARAM_SECRET) <octet string>

This parameter set the shared secret that is used for key derivation.

"info" (OSSL_KDF_PARAM_INFO) <octet string>

This parameter sets an optional value for fixedinfo, also known as otherinfo.

The OpenSSL FIPS provider also supports the following parameters:

"fips-indicator" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) <integer>

A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling EVP_KDF_derive. It returns 0 if "key-check" is set to 0 and the check fails.

"key-check" (OSSL_KDF_PARAM_FIPS_KEY_CHECK) <integer>

The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the length of used key-derivation key (OSSL_KDF_PARAM_KEY) is shorter than 112 bits. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. This option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0.

## NOTES
A context for SSKDF can be obtained by calling:

```
 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
```

The output length of an SSKDF is specified via the keylen parameter to the EVP_KDF_derive(3) function.

## EXAMPLES
This example derives 10 bytes using H(x) = SHA-256, with the secret key "secret" and fixedinfo value "label":

```
 EVP_KDF *kdf;
 EVP_KDF_CTX *kctx;
 unsigned char out[10];
 OSSL_PARAM params[4], *p = params;
 kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
 kctx = EVP_KDF_CTX_new(kdf);
 EVP_KDF_free(kdf);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
                                         SN_sha256, strlen(SN_sha256));
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
                                          "secret", (size_t)6);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
                                          "label", (size_t)5);
 *p = OSSL_PARAM_construct_end();
 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
     error("EVP_KDF_derive");
 }
 EVP_KDF_CTX_free(kctx);
```

This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret", fixedinfo value "label" and salt "salt":

```
 EVP_KDF *kdf;
 EVP_KDF_CTX *kctx;
 unsigned char out[10];
 OSSL_PARAM params[6], *p = params;
 kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
 kctx = EVP_KDF_CTX_new(kdf);
 EVP_KDF_free(kdf);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
                                         SN_hmac, strlen(SN_hmac));
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
                                         SN_sha256, strlen(SN_sha256));
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET,
                                          "secret", (size_t)6);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
                                          "label", (size_t)5);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
                                          "salt", (size_t)4);
 *p = OSSL_PARAM_construct_end();
 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
     error("EVP_KDF_derive");
 }
 EVP_KDF_CTX_free(kctx);
```

This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret" fixedinfo value "label", salt of "salt" and KMAC outlen of 20:

```
 EVP_KDF *kdf;
 EVP_KDF_CTX *kctx;
 unsigned char out[10];
 OSSL_PARAM params[6], *p = params;
 kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
 kctx = EVP_KDF_CTX_new(kdf);
 EVP_KDF_free(kdf);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
                                         SN_kmac128, strlen(SN_kmac128));
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET,
                                          "secret", (size_t)6);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
                                          "label", (size_t)5);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
                                          "salt", (size_t)4);
 *p++ = OSSL_PARAM_construct_size_t(OSSL_KDF_PARAM_MAC_SIZE, (size_t)20);
 *p = OSSL_PARAM_construct_end();
 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
     error("EVP_KDF_derive");
 }
 EVP_KDF_CTX_free(kctx);
```

## CONFORMING TO
NIST SP800-56Cr1.

## SEE ALSO
EVP_KDF(3), EVP_KDF_CTX_new(3), EVP_KDF_CTX_free(3), EVP_KDF_CTX_set_params(3), EVP_KDF_CTX_get_kdf_size(3), EVP_KDF_derive(3), "PARAMETERS" in EVP_KDF(3)

## HISTORY
This functionality was added in OpenSSL 3.0.

## COPYRIGHT
Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved. Copyright (c) 2019, Oracle and/or its affiliates. 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: EVP_KDF-SSHKDF(7ossl)

summary: The SSHKDF EVP_KDF implementation

text:
# EVP_KDF-SSHKDF(7ossl)

## NAME
EVP_KDF-SSHKDF - The SSHKDF EVP_KDF implementation

## DESCRIPTION
Support for computing the SSHKDF KDF through the EVP_KDF API.

The EVP_KDF-SSHKDF algorithm implements the SSHKDF key derivation function. It is defined in RFC 4253, section 7.2 and is used by SSH to derive IVs, encryption keys and integrity keys. Five inputs are required to perform key derivation: The hashing function (for example SHA256), the Initial Key, the Exchange Hash, the Session ID, and the derivation key type.

The output is considered to be keying material.

### Identity
"SSHKDF" is the name for this implementation; it can be used with the EVP_KDF_fetch() function.

### Supported parameters
The supported parameters are:

"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>

"digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>

"key" (OSSL_KDF_PARAM_KEY) <octet string>

These parameters work as described in "PARAMETERS" in EVP_KDF(3).

"xcghash" (OSSL_KDF_PARAM_SSHKDF_XCGHASH) <octet string>

"session_id" (OSSL_KDF_PARAM_SSHKDF_SESSION_ID) <octet string>

These parameters set the respective values for the KDF. If a value is already set, the contents are replaced.

"type" (OSSL_KDF_PARAM_SSHKDF_TYPE) <UTF8 string>

This parameter sets the type for the SSHKDF operation. There are six supported types:

EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV

The Initial IV from client to server. A single char of value 65 (ASCII char 'A').

EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI

The Initial IV from server to client A single char of value 66 (ASCII char 'B').

EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV

The Encryption Key from client to server A single char of value 67 (ASCII char 'C').

EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI

The Encryption Key from server to client A single char of value 68 (ASCII char 'D').

EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV

The Integrity Key from client to server A single char of value 69 (ASCII char 'E').

EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI

The Integrity Key from client to server A single char of value 70 (ASCII char 'F').

The OpenSSL FIPS provider also supports the following parameters:

"fips-indicator" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) <integer>

A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check" related parameter is set to 0 and the check fails.

"digest-check" (OSSL_KDF_PARAM_FIPS_DIGEST_CHECK) <integer>

The default value of 1 causes an error during EVP_KDF_CTX_set_params() if used digest is not approved. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. This option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0. According to SP 800-135r1, the following are approved digest algorithms: SHA-1, SHA2-224, SHA2-256, SHA2-384, SHA2-512.

"key-check" (OSSL_KDF_PARAM_FIPS_KEY_CHECK) <integer>

The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the length of used key-derivation key (OSSL_KDF_PARAM_KEY) is shorter than 112 bits. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. This option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0.

## NOTES
A context for SSHKDF can be obtained by calling:

```
 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL);
 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
```

The output length of the SSHKDF derivation is specified via the keylen parameter to the EVP_KDF_derive(3) function. Since the SSHKDF output length is variable, calling EVP_KDF_CTX_get_kdf_size(3) to obtain the requisite length is not meaningful. The caller must allocate a buffer of the desired length, and pass that buffer to the EVP_KDF_derive(3) function along with the desired length.

## EXAMPLES
This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate "xcghash" and "session_id" values:

```
 EVP_KDF *kdf;
 EVP_KDF_CTX *kctx;
 char type = EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV;
 unsigned char key[1024] = "01234...";
 unsigned char xcghash[32] = "012345...";
 unsigned char session_id[32] = "012345...";
 unsigned char out[8];
 size_t outlen = sizeof(out);
 OSSL_PARAM params[6], *p = params;
 kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL);
 kctx = EVP_KDF_CTX_new(kdf);
 EVP_KDF_free(kdf);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
                                         SN_sha256, strlen(SN_sha256));
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
                                          key, (size_t)1024);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_XCGHASH,
                                          xcghash, (size_t)32);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_SESSION_ID,
                                          session_id, (size_t)32);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_SSHKDF_TYPE,
                                         &type, sizeof(type));
 *p = OSSL_PARAM_construct_end();
 if (EVP_KDF_derive(kctx, out, outlen, params) <= 0)
     /* Error */
```

## CONFORMING TO
RFC 4253

## SEE ALSO
EVP_KDF(3), EVP_KDF_CTX_new(3), EVP_KDF_CTX_free(3), EVP_KDF_CTX_set_params(3), EVP_KDF_CTX_get_kdf_size(3), EVP_KDF_derive(3), "PARAMETERS" in EVP_KDF(3)

## HISTORY
This functionality was added in OpenSSL 3.0.

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

summary: The TLS 1.3 EVP_KDF implementation

text:
# EVP_KDF-TLS13_KDF(7ossl)

## NAME
EVP_KDF-TLS13_KDF - The TLS 1.3 EVP_KDF implementation

## DESCRIPTION
Support for computing the TLS 1.3 version of the HKDF KDF through the EVP_KDF API.

The EVP_KDF-TLS13_KDF algorithm implements the HKDF key derivation function as used by TLS 1.3.

The output is considered to be keying material.

### Identity
"TLS13-KDF" is the name for this implementation; it can be used with the EVP_KDF_fetch() function.

### Supported parameters
The supported parameters are:

"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>

"digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>

"key" (OSSL_KDF_PARAM_KEY) <octet string>

"salt" (OSSL_KDF_PARAM_SALT) <octet string>

These parameters work as described in "PARAMETERS" in EVP_KDF(3).

"prefix" (OSSL_KDF_PARAM_PREFIX) <octet string>

This parameter sets the label prefix on the specified TLS 1.3 KDF context. For TLS 1.3 this should be set to the ASCII string "tls13 " without a trailing zero byte. Refer to RFC 8446 section 7.1 "Key Schedule" for details.

"label" (OSSL_KDF_PARAM_LABEL) <octet string>

This parameter sets the label on the specified TLS 1.3 KDF context. Refer to RFC 8446 section 7.1 "Key Schedule" for details.

"data" (OSSL_KDF_PARAM_DATA) <octet string>

This parameter sets the context data on the specified TLS 1.3 KDF context. Refer to RFC 8446 section 7.1 "Key Schedule" for details.

"mode" (OSSL_KDF_PARAM_MODE) <UTF8 string> or <integer>

This parameter sets the mode for the TLS 1.3 KDF operation. There are two modes that are currently defined:

"EXTRACT_ONLY" or EVP_KDF_HKDF_MODE_EXTRACT_ONLY

In this mode calling EVP_KDF_derive(3) will just perform the extract operation. The value returned will be the intermediate fixed-length pseudorandom key K. The keylen parameter must match the size of K, which can be looked up by calling EVP_KDF_CTX_get_kdf_size() after setting the mode and digest. The digest, key and salt values must be set before a key is derived otherwise an error will occur.

"EXPAND_ONLY" or EVP_KDF_HKDF_MODE_EXPAND_ONLY

In this mode calling EVP_KDF_derive(3) will just perform the expand operation. The input key should be set to the intermediate fixed-length pseudorandom key K returned from a previous extract operation. The digest, key and info values must be set before a key is derived otherwise an error will occur.

The OpenSSL FIPS provider also supports the following parameters:

"fips-indicator" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) <integer>

A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check" related parameter is set to 0 and the check fails.

"digest-check" (OSSL_KDF_PARAM_FIPS_DIGEST_CHECK) <integer>

The default value of 1 causes an error during EVP_KDF_CTX_set_params() if used digest is not approved. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. This option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0. According to RFC 8446, the following are approved digest algorithms: SHA2-256, SHA2-384.

"key-check" (OSSL_KDF_PARAM_FIPS_KEY_CHECK) <integer>

The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the length of used key-derivation key (OSSL_KDF_PARAM_KEY) is shorter than 112 bits. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. This option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0.

## NOTES
This KDF is intended for use by the TLS 1.3 implementation in libssl. It does not support all the options and capabilities that HKDF does.

The OSSL_PARAM array passed to EVP_KDF_derive(3) or EVP_KDF_CTX_set_params(3) must specify all of the parameters required. This KDF does not support a piecemeal approach to providing these.

A context for a TLS 1.3 KDF can be obtained by calling:

```
 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "TLS13-KDF", NULL);
 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
```

The output length of a TLS 1.3 KDF expand operation is specified via the keylen parameter to the EVP_KDF_derive(3) function. When using EVP_KDF_HKDF_MODE_EXTRACT_ONLY the keylen parameter must equal the size of the intermediate fixed-length pseudorandom key otherwise an error will occur. For that mode, the fixed output size can be looked up by calling EVP_KDF_CTX_get_kdf_size() after setting the mode and digest on the EVP_KDF_CTX.

## CONFORMING TO
RFC 8446

## SEE ALSO
EVP_KDF(3), EVP_KDF_CTX_new(3), EVP_KDF_CTX_free(3), EVP_KDF_CTX_get_kdf_size(3), EVP_KDF_CTX_set_params(3), EVP_KDF_derive(3), "PARAMETERS" in EVP_KDF(3), EVP_KDF-HKDF(7)

## HISTORY
This functionality was added in OpenSSL 3.0.

## COPYRIGHT
Copyright 2021-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: EVP_KDF-TLS1_PRF(7ossl)

summary: The TLS1 PRF EVP_KDF implementation

text:
# EVP_KDF-TLS1_PRF(7ossl)

## NAME
EVP_KDF-TLS1_PRF - The TLS1 PRF EVP_KDF implementation

## DESCRIPTION
Support for computing the TLS1 PRF through the EVP_KDF API.

The EVP_KDF-TLS1_PRF algorithm implements the PRF used by TLS versions up to and including TLS 1.2.

The output is considered to be keying material.

### Identity
"TLS1-PRF" is the name for this implementation; it can be used with the EVP_KDF_fetch() function.

### Supported parameters
The supported parameters are:

"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>

"digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>

These parameters work as described in "PARAMETERS" in EVP_KDF(3). The OSSL_KDF_PARAM_DIGEST parameter is used to set the message digest associated with the TLS PRF. EVP_md5_sha1() is treated as a special case which uses the PRF algorithm using both MD5 and SHA1 as used in TLS 1.0 and 1.1.

"secret" (OSSL_KDF_PARAM_SECRET) <octet string>

This parameter sets the secret value of the TLS PRF. Any existing secret value is replaced.

"seed" (OSSL_KDF_PARAM_SEED) <octet string>

This parameter sets the context seed. The length of the context seed cannot exceed 1024 bytes; this should be more than enough for any normal use of the TLS PRF.

The OpenSSL FIPS provider also supports the following parameters:

"fips-indicator" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) <integer>

A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check" related parameter is set to 0 and the check fails.

"ems_check" (OSSL_KDF_PARAM_FIPS_EMS_CHECK) <integer>

The default value of 1 causes an error during EVP_KDF_derive() if "master secret" is used instead of "extended master secret" Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. This option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0.

"digest-check" (OSSL_KDF_PARAM_FIPS_DIGEST_CHECK) <integer>

The default value of 1 causes an error during EVP_KDF_CTX_set_params() if used digest is not approved. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. This option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0. According to SP 800-135r1, the following are approved digest algorithms: SHA2-256, SHA2-384, SHA2-512.

"key-check" (OSSL_KDF_PARAM_FIPS_KEY_CHECK) <integer>

The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the length of used key-derivation key (OSSL_KDF_PARAM_SECRET) is shorter than 112 bits. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. This option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0.

## NOTES
A context for the TLS PRF can be obtained by calling:

```
 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "TLS1-PRF", NULL);
 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
```

The digest, secret value and seed must be set before a key is derived otherwise an error will occur.

The output length of the PRF is specified by the keylen parameter to the EVP_KDF_derive() function.

## EXAMPLES
This example derives 10 bytes using SHA-256 with the secret key "secret" and seed value "seed":

```
 EVP_KDF *kdf;
 EVP_KDF_CTX *kctx;
 unsigned char out[10];
 OSSL_PARAM params[4], *p = params;
 kdf = EVP_KDF_fetch(NULL, "TLS1-PRF", NULL);
 kctx = EVP_KDF_CTX_new(kdf);
 EVP_KDF_free(kdf);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
                                         SN_sha256, strlen(SN_sha256));
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET,
                                          "secret", (size_t)6);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED,
                                          "seed", (size_t)4);
 *p = OSSL_PARAM_construct_end();
 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
     error("EVP_KDF_derive");
 }
 EVP_KDF_CTX_free(kctx);
```

## CONFORMING TO
RFC 2246, RFC 5246 and NIST SP 800-135 r1

## SEE ALSO
EVP_KDF(3), EVP_KDF_CTX_new(3), EVP_KDF_CTX_free(3), EVP_KDF_CTX_set_params(3), EVP_KDF_derive(3), "PARAMETERS" in EVP_KDF(3)

## HISTORY
This functionality was added in OpenSSL 3.0.

## COPYRIGHT
Copyright 2018-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: EVP_KDF-X942-ASN1(7ossl)

summary: The X9.42\-2003 asn1 EVP_KDF implementation

text:
# EVP_KDF-X942-ASN1(7ossl)

## NAME
EVP_KDF-X942-ASN1 - The X9.42-2003 asn1 EVP_KDF implementation

## DESCRIPTION
The EVP_KDF-X942-ASN1 algorithm implements the key derivation function X942KDF-ASN1. It is used by DH KeyAgreement, to derive a key using input such as a shared secret key and other info. The other info is DER encoded data that contains a 32 bit counter as well as optional fields for "partyu-info", "partyv-info", "supp-pubinfo" and "supp-privinfo". This kdf is used by Cryptographic Message Syntax (CMS).

The output is considered to be keying material.

### Identity
"X942KDF-ASN1" or "X942KDF" is the name for this implementation; it can be used with the EVP_KDF_fetch() function.

### Supported parameters
The supported parameters are:

"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>

"digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>

These parameters work as described in "PARAMETERS" in EVP_KDF(3).

"secret" (OSSL_KDF_PARAM_SECRET) <octet string>

The shared secret used for key derivation. This parameter sets the secret.

"acvp-info" (OSSL_KDF_PARAM_X942_ACVPINFO) <octet string>

This value should not be used in production and should only be used for ACVP testing. It is an optional octet string containing a combined DER encoded blob of any of the optional fields related to "partyu-info", "partyv-info", "supp-pubinfo" and "supp-privinfo". If it is specified then none of these other fields should be used.

"partyu-info" (OSSL_KDF_PARAM_X942_PARTYUINFO) <octet string>

An optional octet string containing public info contributed by the initiator.

"ukm" (OSSL_KDF_PARAM_UKM) <octet string>

An alias for "partyu-info". In CMS this is the user keying material.

"partyv-info" (OSSL_KDF_PARAM_X942_PARTYVINFO) <octet string>

An optional octet string containing public info contributed by the responder.

"supp-pubinfo" (OSSL_KDF_PARAM_X942_SUPP_PUBINFO) <octet string>

An optional octet string containing some additional, mutually-known public information. Setting this value also sets "use-keybits" to 0.

"use-keybits" (OSSL_KDF_PARAM_X942_USE_KEYBITS) <integer>

The default value of 1 will use the KEK key length (in bits) as the "supp-pubinfo". A value of 0 disables setting the "supp-pubinfo".

"supp-privinfo" (OSSL_KDF_PARAM_X942_SUPP_PRIVINFO) <octet string>

An optional octet string containing some additional, mutually-known private information.

"cekalg" (OSSL_KDF_PARAM_CEK_ALG) <UTF8 string>

This parameter sets the CEK wrapping algorithm name. Valid values are "AES-128-WRAP", "AES-192-WRAP", "AES-256-WRAP" and "DES3-WRAP".

The OpenSSL FIPS provider also supports the following parameters:

"fips-indicator" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) <integer>

A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling EVP_KDF_derive. It returns 0 if "key-check" parameter is set to 0 and the check fails.

"key-check" (OSSL_KDF_PARAM_FIPS_KEY_CHECK) <integer>

The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the length of used key-derivation key (OSSL_KDF_PARAM_KEY) is shorter than 112 bits. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. This option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0.

## NOTES
A context for X942KDF can be obtained by calling:

```
 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL);
 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
```

The output length of an X942KDF is specified via the keylen parameter to the EVP_KDF_derive(3) function.

## EXAMPLES
This example derives 24 bytes, with the secret key "secret" and random user keying material:

```
  EVP_KDF_CTX *kctx;
  EVP_KDF_CTX *kctx;
  unsigned char out[192/8];
  unsignred char ukm[64];
  OSSL_PARAM params[5], *p = params;
  if (RAND_bytes(ukm, sizeof(ukm)) <= 0)
      error("RAND_bytes");
  kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL);
  if (kctx == NULL)
      error("EVP_KDF_fetch");
  kctx = EVP_KDF_CTX_new(kdf);
  EVP_KDF_free(kdf);
  if (kctx == NULL)
      error("EVP_KDF_CTX_new");
  *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, "SHA256", 0);
  *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET,
                                           "secret", (size_t)6);
  *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_UKM, ukm, sizeof(ukm));
  *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CEK_ALG, "AES-256-WRAP, 0);
  *p = OSSL_PARAM_construct_end();
  if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0)
      error("EVP_KDF_derive");
  EVP_KDF_CTX_free(kctx);
```

## CONFORMING TO
ANS1 X9.42-2003 RFC 2631

## SEE ALSO
EVP_KDF(3), EVP_KDF_CTX_new(3), EVP_KDF_CTX_free(3), EVP_KDF_CTX_set_params(3), EVP_KDF_CTX_get_kdf_size(3), EVP_KDF_derive(3), "PARAMETERS" in EVP_KDF(3)

## HISTORY
This functionality was 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: EVP_KDF-X942-CONCAT(7ossl)

summary: The X942 Concat EVP_KDF implementation

text:
# EVP_KDF-X942-CONCAT(7ossl)

## NAME
EVP_KDF-X942-CONCAT - The X942 Concat EVP_KDF implementation

## DESCRIPTION
The EVP_KDF-X942-CONCAT algorithm is identical to EVP_KDF-X963. It is used for key agreement to derive a key using input such as a shared secret key and shared info.

### Identity
"X942KDF_CONCAT" is the name for this implementation; it can be used with the EVP_KDF_fetch() function.

This is an alias for "X963KDF".

See EVP_KDF-X963(7) for a list of supported parameters and examples.

## 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: EVP_KDF-X963(7ossl)

summary: The X9.63\-2001 EVP_KDF implementation

text:
# EVP_KDF-X963(7ossl)

## NAME
EVP_KDF-X963 - The X9.63-2001 EVP_KDF implementation

## DESCRIPTION
The EVP_KDF-X963 algorithm implements the key derivation function (X963KDF). X963KDF is used by Cryptographic Message Syntax (CMS) for EC KeyAgreement, to derive a key using input such as a shared secret key and shared info.

The output is considered to be keying material.

### Identity
"X963KDF" is the name for this implementation; it can be used with the EVP_KDF_fetch() function.

### Supported parameters
The supported parameters are:

"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>

"digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>

These parameters work as described in "PARAMETERS" in EVP_KDF(3).

"key" (OSSL_KDF_PARAM_KEY) <octet string>

The shared secret used for key derivation. This parameter sets the secret.

"info" (OSSL_KDF_PARAM_INFO) <octet string>

This parameter specifies an optional value for shared info.

The OpenSSL FIPS provider also supports the following parameters:

"fips-indicator" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) <integer>

A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check" related parameter is set to 0 and the check fails.

"digest-check" (OSSL_KDF_PARAM_FIPS_DIGEST_CHECK) <int>

The default value of 1 causes an error during EVP_KDF_CTX_set_params() if used digest is not approved. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. This option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0. According to ANSI X9.63-2001, the following are approved digest algorithms: SHA2-224, SHA2-256, SHA2-384, SHA2-512, SHA2-512/224, SHA2-512/256, SHA3-224, SHA3-256, SHA3-384, SHA3-512.

"key-check" (OSSL_KDF_PARAM_FIPS_KEY_CHECK) <integer>

The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the length of used key-derivation key (OSSL_KDF_PARAM_KEY) is shorter than 112 bits. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. This option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0.

## NOTES
X963KDF is very similar to the SSKDF that uses a digest as the auxiliary function, X963KDF appends the counter to the secret, whereas SSKDF prepends the counter.

A context for X963KDF can be obtained by calling:

```
 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL);
 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
```

The output length of an X963KDF is specified via the keylen parameter to the EVP_KDF_derive(3) function.

## EXAMPLES
This example derives 10 bytes, with the secret key "secret" and sharedinfo value "label":

```
 EVP_KDF *kdf;
 EVP_KDF_CTX *kctx;
 unsigned char out[10];
 OSSL_PARAM params[4], *p = params;
 kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL);
 kctx = EVP_KDF_CTX_new(kdf);
 EVP_KDF_free(kdf);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
                                         SN_sha256, strlen(SN_sha256));
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET,
                                          "secret", (size_t)6);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
                                          "label", (size_t)5);
 *p = OSSL_PARAM_construct_end();
 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
     error("EVP_KDF_derive");
 }
 EVP_KDF_CTX_free(kctx);
```

## CONFORMING TO
"SEC 1: Elliptic Curve Cryptography"

## SEE ALSO
EVP_KDF(3), EVP_KDF_CTX_new(3), EVP_KDF_CTX_free(3), EVP_KDF_CTX_set_params(3), EVP_KDF_CTX_get_kdf_size(3), EVP_KDF_derive(3), "PARAMETERS" in EVP_KDF(3)

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


title: EVP_KEM-EC(7ossl)

summary: EC

text:
# EVP_KEM-EC(7ossl)

## NAME
EVP_KEM-EC - EVP_KEM EC keytype and algorithm support

## DESCRIPTION
The EC keytype and its parameters are described in EVP_PKEY-EC(7). See EVP_PKEY_encapsulate(3) and EVP_PKEY_decapsulate(3) for more info.

### EC KEM parameters
"operation" (OSSL_KEM_PARAM_OPERATION)<UTF8 string>

The OpenSSL EC Key Encapsulation Mechanisms only supports the following default operation (operating mode):

"DHKEM" (OSSL_KEM_PARAM_OPERATION_DHKEM)

The encapsulate function generates an ephemeral keypair. It produces keymaterial by doing an ECDH key exchange using the ephemeral private key and a supplied recipient public key. A HKDF operation using the keymaterial and a kem context then produces a shared secret. The shared secret and the ephemeral public key are returned. The decapsulate function uses the recipient private key and the ephemeral public key to produce the same keymaterial, which can then be used to produce the same shared secret. See <https://www.rfc-editor.org/rfc/rfc9180.html#name-dh-based-kem-dhkem>

This can be set using either EVP_PKEY_CTX_set_kem_op() or EVP_PKEY_CTX_set_params().

"ikme" (OSSL_KEM_PARAM_IKME) <octet string>

Used to specify the key material used for generation of the ephemeral key. This value should not be reused for other purposes. It can only be used for the curves "P-256", "P-384" and "P-521" and should have a length of at least the size of the encoded private key (i.e. 32, 48 and 66 for the listed curves). If this value is not set, then a random ikm is used.

## CONFORMING TO
RFC9180

## SEE ALSO
EVP_PKEY_CTX_set_kem_op(3), EVP_PKEY_encapsulate(3), EVP_PKEY_decapsulate(3) EVP_KEYMGMT(3), EVP_PKEY(3), provider-keymgmt(7)

## HISTORY
This functionality was added in OpenSSL 3.2.

The "operation" (operating mode) was a required parameter prior to OpenSSL 3.5. As of OpenSSL 3.5, "DHKEM" is the default operating mode, and no explicit value need be specified.

## COPYRIGHT
Copyright 2022-2025 The OpenSSL Project Authors. All Rights Reserved.

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


title: EVP_KEM-ML-KEM(7ossl)

summary: ML\-KEM\-512, EVP_KEM\-ML\-KEM\-768, EVP_KEM\-ML\-KEM\-1024, EVP_KEM\-ML\-KEM

text:
# EVP_KEM-ML-KEM(7ossl)

## NAME
EVP_KEM-ML-KEM-512, EVP_KEM-ML-KEM-768, EVP_KEM-ML-KEM-1024, EVP_KEM-ML-KEM - EVP_KEM ML-KEM keytype and algorithm support

## DESCRIPTION
The ML-KEM keytypes and parameters are described in EVP_PKEY-ML-KEM(7). See EVP_PKEY_encapsulate(3) and EVP_PKEY_decapsulate(3) for more details about basic KEM operations.

### ML-KEM KEM parameters
"ikme" (OSSL_KEM_PARAM_IKME) <octet string>

The OpenSSL ML-KEM encapsulation mechanism can only be modified by setting randomness during encapsulation, this enables testing, as per FIPS 203, section 6.2, algorithm 17. This parameter should not be used for purposes other than testing.

When this parameter is not set, encapsulation proceeds as per FIPS 203, section 7.2

This parameter is only settable.

This can be set when using EVP_PKEY_encapsulate_init().

## CONFORMING TO
FIPS203

## SEE ALSO
EVP_PKEY_encapsulate(3), EVP_PKEY_decapsulate(3), EVP_KEYMGMT(3), EVP_PKEY(3), provider-keymgmt(7)

## HISTORY
This functionality was added in OpenSSL 3.5.

## COPYRIGHT
Copyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved.

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


title: EVP_KEM-RSA(7ossl)

summary: RSA

text:
# EVP_KEM-RSA(7ossl)

## NAME
EVP_KEM-RSA - EVP_KEM RSA keytype and algorithm support

## DESCRIPTION
The RSA keytype and its parameters are described in EVP_PKEY-RSA(7). See EVP_PKEY_encapsulate(3) and EVP_PKEY_decapsulate(3) for more info.

### RSA KEM parameters
"operation" (OSSL_KEM_PARAM_OPERATION) <UTF8 string>

The OpenSSL RSA Key Encapsulation Mechanism only currently supports the following default operation (operating mode):

"RSASVE"

The encapsulate function simply generates a secret using random bytes and then encrypts the secret using the RSA public key (with no padding). The decapsulate function recovers the secret using the RSA private key.

This can be set using EVP_PKEY_CTX_set_kem_op().

"fips-indicator" (OSSL_KEM_PARAM_FIPS_APPROVED_INDICATOR) <integer>

"key-check" (OSSL_KEM_PARAM_FIPS_KEY_CHECK) <integer>

These parameters are described in provider-kem(7).

## CONFORMING TO
SP800-56Br2

Section 7.2.1.2 RSASVE Generate Operation (RSASVE.GENERATE). Section 7.2.1.3 RSASVE Recovery Operation (RSASVE.RECOVER).

## SEE ALSO
EVP_PKEY_CTX_set_kem_op(3), EVP_PKEY_encapsulate(3), EVP_PKEY_decapsulate(3) EVP_KEYMGMT(3), EVP_PKEY(3), provider-keymgmt(7)

## HISTORY
This functionality was added in OpenSSL 3.0.

The "operation" (operating mode) was a required parameter prior to OpenSSL 3.5. As of OpenSSL 3.5, "RSASVE" is the default operating mode, and no explicit value need be specified.

## COPYRIGHT
Copyright 2020-2025 The OpenSSL Project Authors. All Rights Reserved.

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


title: EVP_KEM-X25519(7ossl)

summary: X25519, EVP_KEM\-X448

text:
# EVP_KEM-X25519(7ossl)

## NAME
EVP_KEM-X25519, EVP_KEM-X448 - EVP_KEM X25519 and EVP_KEM X448 keytype and algorithm support

## DESCRIPTION
The X25519 and <X448> keytype and its parameters are described in EVP_PKEY-X25519(7). See EVP_PKEY_encapsulate(3) and EVP_PKEY_decapsulate(3) for more info.

### X25519 and X448 KEM parameters
"operation" (OSSL_KEM_PARAM_OPERATION)<UTF8 string>

The OpenSSL X25519 and X448 Key Encapsulation Mechanisms only support the following default operation (operating mode):

"DHKEM" (OSSL_KEM_PARAM_OPERATION_DHKEM)

The encapsulate function generates an ephemeral keypair. It produces keymaterial by doing an X25519 or X448 key exchange using the ephemeral private key and a supplied recipient public key. A HKDF operation using the keymaterial and a kem context then produces a shared secret. The shared secret and the ephemeral public key are returned. The decapsulate function uses the recipient private key and the ephemeral public key to produce the same keymaterial, which can then be used to produce the same shared secret. See <https://www.rfc-editor.org/rfc/rfc9180.html#name-dh-based-kem-dhkem>

This can be set using either EVP_PKEY_CTX_set_kem_op() or EVP_PKEY_CTX_set_params().

"ikme" (OSSL_KEM_PARAM_IKME) <octet string>

Used to specify the key material used for generation of the ephemeral key. This value should not be reused for other purposes. It should have a length of at least 32 for X25519, and 56 for X448. If this value is not set, then a random ikm is used.

## CONFORMING TO
RFC9180

## SEE ALSO
EVP_PKEY_CTX_set_kem_op(3), EVP_PKEY_encapsulate(3), EVP_PKEY_decapsulate(3) EVP_KEYMGMT(3), EVP_PKEY(3), provider-keymgmt(7)

## HISTORY
This functionality was added in OpenSSL 3.2.

The "operation" (operating mode) was a required parameter prior to OpenSSL 3.5. As of OpenSSL 3.5, "DHKEM" is the default operating mode, and no explicit value need be specified.

## COPYRIGHT
Copyright 2022-2025 The OpenSSL Project Authors. All Rights Reserved.

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


title: EVP_KEYEXCH-DH(7ossl)

summary: DH

text:
# EVP_KEYEXCH-DH(7ossl)

## NAME
EVP_KEYEXCH-DH - DH Key Exchange algorithm support

## DESCRIPTION
Key exchange support for the DH and DHX key types.

Please note that although both key types support the same key exchange operations, they cannot be used together in a single key exchange. It is not possible to use a private key of the DH type in key exchange with the public key of DHX type and vice versa.

### DH and DHX key exchange parameters
"pad" (OSSL_EXCHANGE_PARAM_PAD) <unsigned integer>

Sets the padding mode for the associated key exchange ctx. Setting a value of 1 will turn padding on. Setting a value of 0 will turn padding off. If padding is off then the derived shared secret may be smaller than the largest possible secret size. If padding is on then the derived shared secret will have its first bytes filled with zeros where necessary to make the shared secret the same size as the largest possible secret size. The padding mode parameter is ignored (and padding implicitly enabled) when the KDF type is set to "X942KDF-ASN1" (OSSL_KDF_NAME_X942KDF_ASN1).

"kdf-type" (OSSL_EXCHANGE_PARAM_KDF_TYPE) <UTF8 string>

"kdf-digest" (OSSL_EXCHANGE_PARAM_KDF_DIGEST) <UTF8 string>

"kdf-digest-props" (OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS) <UTF8 string>

"kdf-outlen" (OSSL_EXCHANGE_PARAM_KDF_OUTLEN) <unsigned integer>

"kdf-ukm" (OSSL_EXCHANGE_PARAM_KDF_UKM) <octet string>

"fips-indicator" (OSSL_EXCHANGE_PARAM_FIPS_APPROVED_INDICATOR) <integer>

"key-check" (OSSL_EXCHANGE_PARAM_FIPS_KEY_CHECK) <integer>

"digest-check" (OSSL_EXCHANGE_PARAM_FIPS_DIGEST_CHECK) <integer>

See "Common Key Exchange parameters" in provider-keyexch(7).

"cekalg" (OSSL_KDF_PARAM_CEK_ALG) <octet string ptr>

See "KDF Parameters" in provider-kdf(7).

## EXAMPLES
The examples assume a host and peer both generate keys using the same named group (or domain parameters). See "Examples" in EVP_PKEY-DH(7). Both the host and peer transfer their public key to each other.

To convert the peer's generated key pair to a public key in DER format in order to transfer to the host:

```
    EVP_PKEY *peer_key; /* It is assumed this contains the peers generated key */
    unsigned char *peer_pub_der = NULL;
    int peer_pub_der_len;
    peer_pub_der_len = i2d_PUBKEY(peer_key, &peer_pub_der);
    ...
    OPENSSL_free(peer_pub_der);
```

To convert the received peer's public key from DER format on the host:

```
    const unsigned char *pd = peer_pub_der;
    EVP_PKEY *peer_pub_key = d2i_PUBKEY(NULL, &pd, peer_pub_der_len);
    ...
    EVP_PKEY_free(peer_pub_key);
```

To derive a shared secret on the host using the host's key and the peer's public key:

```
    /* It is assumed that the host_key and peer_pub_key are set up */
    void derive_secret(EVP_KEY *host_key, EVP_PKEY *peer_pub_key)
    {
        unsigned int pad = 1;
        OSSL_PARAM params[2];
        unsigned char *secret = NULL;
        size_t secret_len = 0;
        EVP_PKEY_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL);
        EVP_PKEY_derive_init(dctx);
        /* Optionally set the padding */
        params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad);
        params[1] = OSSL_PARAM_construct_end();
        EVP_PKEY_CTX_set_params(dctx, params);
        EVP_PKEY_derive_set_peer(dctx, peer_pub_key);
        /* Get the size by passing NULL as the buffer */
        EVP_PKEY_derive(dctx, NULL, &secret_len);
        secret = OPENSSL_zalloc(secret_len);
        EVP_PKEY_derive(dctx, secret, &secret_len);
        ...
        OPENSSL_clear_free(secret, secret_len);
        EVP_PKEY_CTX_free(dctx);
    }
```

Very similar code can be used by the peer to derive the same shared secret using the host's public key and the peer's generated key pair.

## SEE ALSO
EVP_PKEY-DH(7), EVP_PKEY-FFC(7), EVP_PKEY(3), provider-keyexch(7), provider-keymgmt(7), OSSL_PROVIDER-default(7), OSSL_PROVIDER-FIPS(7),

## 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: EVP_KEYEXCH-ECDH(7ossl)

summary: ECDH Key Exchange algorithm support

text:
# EVP_KEYEXCH-ECDH(7ossl)

## NAME
EVP_KEYEXCH-ECDH - ECDH Key Exchange algorithm support

## DESCRIPTION
Key exchange support for the ECDH key type.

### ECDH Key Exchange parameters
"ecdh-cofactor-mode" (OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE) <integer>

Sets or gets the ECDH mode of operation for the associated key exchange ctx. In the context of an Elliptic Curve Diffie-Hellman key exchange, this parameter can be used to select between the plain Diffie-Hellman (DH) or Cofactor Diffie-Hellman (CDH) variants of the key exchange algorithm.

When setting, the value should be 1, 0 or -1, respectively forcing cofactor mode on, off, or resetting it to the default for the private key associated with the given key exchange ctx.

When getting, the value should be either 1 or 0, respectively signaling if the cofactor mode is on or off.

See also provider-keymgmt(7) for the related OSSL_PKEY_PARAM_USE_COFACTOR_ECDH parameter that can be set on a per-key basis.

"kdf-type" (OSSL_EXCHANGE_PARAM_KDF_TYPE) <UTF8 string>

"kdf-digest" (OSSL_EXCHANGE_PARAM_KDF_DIGEST) <UTF8 string>

"kdf-digest-props" (OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS) <UTF8 string>

"kdf-outlen" (OSSL_EXCHANGE_PARAM_KDF_OUTLEN) <unsigned integer>

"kdf-ukm" (OSSL_EXCHANGE_PARAM_KDF_UKM) <octet string>

The OpenSSL FIPS provider also supports the following parameters:

"fips-indicator" (OSSL_EXCHANGE_PARAM_FIPS_APPROVED_INDICATOR) <integer>

"key-check" (OSSL_EXCHANGE_PARAM_FIPS_KEY_CHECK) <integer>

"digest-check" (OSSL_EXCHANGE_PARAM_FIPS_DIGEST_CHECK) <integer>

See "Common Key Exchange parameters" in provider-keyexch(7).

"ecdh-cofactor-check" (OSSL_EXCHANGE_PARAM_FIPS_ECDH_COFACTOR_CHECK) <integer>

If required this parameter should before OSSL_FUNC_keyexch_derive(). The default value of 1 causes an error during the OSSL_FUNC_keyexch_derive if the EC curve has a cofactor that is not 1, and the cofactor is not used. Setting this to 0 will ignore the error and set the approved "fips-indicator" to 0. This option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0.

## EXAMPLES
Examples of key agreement can be found in demos/keyexch.

Keys for the host and peer must be generated as shown in "Examples" in EVP_PKEY-EC(7) using the same curve name.

The code to generate a shared secret for the normal case is identical to "Examples" in EVP_KEYEXCH-DH(7).

To derive a shared secret on the host using the host's key and the peer's public key but also using X963KDF with a user key material:

```
    /* It is assumed that the host_key, peer_pub_key and ukm are set up */
    void derive_secret(EVP_PKEY *host_key, EVP_PKEY *peer_key,
                       unsigned char *ukm, size_t ukm_len)
    {
        unsigned char secret[64];
        size_t out_len = sizeof(secret);
        size_t secret_len = out_len;
        unsigned int pad = 1;
        OSSL_PARAM params[6];
        EVP_PKEY_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL);
        EVP_PKEY_derive_init(dctx);
        params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad);
        params[1] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_TYPE,
                                                     "X963KDF", 0);
        params[2] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_DIGEST,
                                                     "SHA1", 0);
        params[3] = OSSL_PARAM_construct_size_t(OSSL_EXCHANGE_PARAM_KDF_OUTLEN,
                                                &out_len);
        params[4] = OSSL_PARAM_construct_octet_string(OSSL_EXCHANGE_PARAM_KDF_UKM,
                                                      ukm, ukm_len);
        params[5] = OSSL_PARAM_construct_end();
        EVP_PKEY_CTX_set_params(dctx, params);
        EVP_PKEY_derive_set_peer(dctx, peer_pub_key);
        EVP_PKEY_derive(dctx, secret, &secret_len);
        ...
        OPENSSL_clear_free(secret, secret_len);
        EVP_PKEY_CTX_free(dctx);
    }
```

## SEE ALSO
EVP_PKEY-EC(7) EVP_PKEY(3), provider-keyexch(7), provider-keymgmt(7), OSSL_PROVIDER-default(7), OSSL_PROVIDER-FIPS(7),

## 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: EVP_KEYEXCH-X25519(7ossl)

text:
# EVP_KEYEXCH-X25519(7ossl)

## NAME
EVP_KEYEXCH-X25519, EVP_KEYEXCH-X448 - X25519 and X448 Key Exchange algorithm support

## DESCRIPTION
Key exchange support for the X25519 and X448 key types.

### Key exchange parameters
"pad" (OSSL_EXCHANGE_PARAM_PAD) <unsigned integer>

"fips-indicator" (OSSL_EXCHANGE_PARAM_FIPS_APPROVED_INDICATOR) <integer>

X25519 and X448 are not FIPS approved in FIPS 140-3. So this getter will return 0. See "Common Key Exchange parameters" in provider-keyexch(7).

## EXAMPLES
Keys for the host and peer can be generated as shown in "Examples" in EVP_PKEY-X25519(7).

The code to generate a shared secret is identical to "Examples" in EVP_KEYEXCH-DH(7).

## SEE ALSO
EVP_PKEY-FFC(7), EVP_PKEY-DH(7) EVP_PKEY(3), provider-keyexch(7), provider-keymgmt(7), OSSL_PROVIDER-default(7), OSSL_PROVIDER-FIPS(7),

## 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: EVP_MAC-BLAKE2(7ossl)

summary: BLAKE2, EVP_MAC\-BLAKE2BMAC, EVP_MAC\-BLAKE2SMAC

text:
# EVP_MAC-BLAKE2(7ossl)

## NAME
EVP_MAC-BLAKE2, EVP_MAC-BLAKE2BMAC, EVP_MAC-BLAKE2SMAC - The BLAKE2 EVP_MAC implementations

## DESCRIPTION
Support for computing BLAKE2 MACs through the EVP_MAC API.

### Identity
These implementations are identified with one of these names and properties, to be used with EVP_MAC_fetch():

"BLAKE2BMAC", "provider=default"

"BLAKE2SMAC", "provider=default"

### Supported parameters
The general description of these parameters can be found in "PARAMETERS" in EVP_MAC(3).

All these parameters (except for "block-size") can be set with EVP_MAC_CTX_set_params(). Furthermore, the "size" parameter can be retrieved with EVP_MAC_CTX_get_params(), or with EVP_MAC_CTX_get_mac_size(). The length of the "size" parameter should not exceed that of a size_t. Likewise, the "block-size" parameter can be retrieved with EVP_MAC_CTX_get_params(), or with EVP_MAC_CTX_get_block_size().

"key" (OSSL_MAC_PARAM_KEY) <octet string>

Sets the MAC key. It may be at most 64 bytes for BLAKE2BMAC or 32 for BLAKE2SMAC and at least 1 byte in both cases. Setting this parameter is identical to passing a key to EVP_MAC_init(3).

"custom" (OSSL_MAC_PARAM_CUSTOM) <octet string>

Sets the customization/personalization string. It is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for BLAKE2SMAC, and is empty by default.

"salt" (OSSL_MAC_PARAM_SALT) <octet string>

Sets the salt. It is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for BLAKE2SMAC, and is empty by default.

"size" (OSSL_MAC_PARAM_SIZE) <unsigned integer>

Sets the MAC size. It can be any number between 1 and 32 for EVP_MAC_BLAKE2S or between 1 and 64 for EVP_MAC_BLAKE2B. It is 32 and 64 respectively by default.

"block-size" (OSSL_MAC_PARAM_BLOCK_SIZE) <unsigned integer>

Gets the MAC block size. It is 64 for EVP_MAC_BLAKE2S and 128 for EVP_MAC_BLAKE2B.

## SEE ALSO
EVP_MAC_CTX_get_params(3), EVP_MAC_CTX_set_params(3), "PARAMETERS" in EVP_MAC(3), OSSL_PARAM(3)

## HISTORY
The macros and functions described here were added to OpenSSL 3.0.

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


title: EVP_MAC-CMAC(7ossl)

summary: The CMAC EVP_MAC implementation

text:
# EVP_MAC-CMAC(7ossl)

## NAME
EVP_MAC-CMAC - The CMAC EVP_MAC implementation

## DESCRIPTION
Support for computing CMAC MACs through the EVP_MAC API.

This implementation uses EVP_CIPHER functions to get access to the underlying cipher.

### Identity
This implementation is identified with this name and properties, to be used with EVP_MAC_fetch():

"CMAC", "provider=default" or "provider=fips"

### Supported parameters
The general description of these parameters can be found in "PARAMETERS" in EVP_MAC(3).

The following parameter can be set with EVP_MAC_CTX_set_params():

"key" (OSSL_MAC_PARAM_KEY) <octet string>

Sets the MAC key. Setting this parameter is identical to passing a key to EVP_MAC_init(3).

"cipher" (OSSL_MAC_PARAM_CIPHER) <UTF8 string>

Sets the name of the underlying cipher to be used. The mode of the cipher must be CBC.

"properties" (OSSL_MAC_PARAM_PROPERTIES) <UTF8 string>

Sets the properties to be queried when trying to fetch the underlying cipher. This must be given together with the cipher naming parameter to be considered valid.

"encrypt-check" (OSSL_CIPHER_PARAM_FIPS_ENCRYPT_CHECK) <integer>

This option is used by the OpenSSL FIPS provider. If required this parameter should be set before EVP_MAC_init() The default value of 1 causes an error when a unapproved Triple-DES encryption operation is triggered. Setting this to 0 will ignore the error and set the approved "fips-indicator" to 0. This option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0.

The following parameters can be retrieved with EVP_MAC_CTX_get_params():

"size" (OSSL_MAC_PARAM_SIZE) <unsigned integer>

The "size" parameter can also be retrieved with with EVP_MAC_CTX_get_mac_size(). The length of the "size" parameter is equal to that of an unsigned int.

"block-size" (OSSL_MAC_PARAM_BLOCK_SIZE) <unsigned integer>

Gets the MAC block size. The "block-size" parameter can also be retrieved with EVP_MAC_CTX_get_block_size().

"fips-indicator" (OSSL_CIPHER_PARAM_FIPS_APPROVED_INDICATOR) <integer>

This option is used by the OpenSSL FIPS provider. A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling EVP_MAC_final(). It may return 0 if the "encrypt-check" option is set to 0.

## SEE ALSO
EVP_MAC_CTX_get_params(3), EVP_MAC_CTX_set_params(3), "PARAMETERS" in EVP_MAC(3), OSSL_PARAM(3)

## COPYRIGHT
Copyright 2018-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: EVP_MAC-GMAC(7ossl)

summary: The GMAC EVP_MAC implementation

text:
# EVP_MAC-GMAC(7ossl)

## NAME
EVP_MAC-GMAC - The GMAC EVP_MAC implementation

## DESCRIPTION
Support for computing GMAC MACs through the EVP_MAC API.

This implementation uses EVP_CIPHER functions to get access to the underlying cipher.

### Identity
This implementation is identified with this name and properties, to be used with EVP_MAC_fetch():

"GMAC", "provider=default" or "provider=fips"

### Supported parameters
The general description of these parameters can be found in "PARAMETERS" in EVP_MAC(3).

The following parameter can be set with EVP_MAC_CTX_set_params():

"key" (OSSL_MAC_PARAM_KEY) <octet string>

Sets the MAC key. Setting this parameter is identical to passing a key to EVP_MAC_init(3).

"iv" (OSSL_MAC_PARAM_IV) <octet string>

Sets the IV of the underlying cipher, when applicable.

"cipher" (OSSL_MAC_PARAM_CIPHER) <UTF8 string>

Sets the name of the underlying cipher to be used.

"properties" (OSSL_MAC_PARAM_PROPERTIES) <UTF8 string>

Sets the properties to be queried when trying to fetch the underlying cipher. This must be given together with the cipher naming parameter to be considered valid.

The following parameters can be retrieved with EVP_MAC_CTX_get_params():

"size" (OSSL_MAC_PARAM_SIZE) <unsigned integer>

Gets the MAC size.

The "size" parameter can also be retrieved with EVP_MAC_CTX_get_mac_size(). The length of the "size" parameter is equal to that of an unsigned int.

## SEE ALSO
EVP_MAC_CTX_get_params(3), EVP_MAC_CTX_set_params(3), "PARAMETERS" in EVP_MAC(3), OSSL_PARAM(3)

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


title: EVP_MAC-HMAC(7ossl)

summary: The HMAC EVP_MAC implementation

text:
# EVP_MAC-HMAC(7ossl)

## NAME
EVP_MAC-HMAC - The HMAC EVP_MAC implementation

## DESCRIPTION
Support for computing HMAC MACs through the EVP_MAC API.

This implementation uses EVP_MD functions to get access to the underlying digest.

### Identity
This implementation is identified with this name and properties, to be used with EVP_MAC_fetch():

"HMAC", "provider=default" or "provider=fips"

### Supported parameters
The general description of these parameters can be found in "PARAMETERS" in EVP_MAC(3).

The following parameters can be set with EVP_MAC_CTX_set_params():

"key" (OSSL_MAC_PARAM_KEY) <octet string>

Sets the MAC key. Setting this parameter is identical to passing a key to EVP_MAC_init(3).

"digest" (OSSL_MAC_PARAM_DIGEST) <UTF8 string>

Sets the name of the underlying digest to be used.

"properties" (OSSL_MAC_PARAM_PROPERTIES) <UTF8 string>

Sets the properties to be queried when trying to fetch the underlying digest. This must be given together with the digest naming parameter ("digest", or OSSL_MAC_PARAM_DIGEST) to be considered valid.

"digest-noinit" (OSSL_MAC_PARAM_DIGEST_NOINIT) <integer>

A flag to set the MAC digest to not initialise the implementation specific data. The value 0 or 1 is expected. This option is deprecated and will be removed in a future release. It may be set but is currently ignored

"digest-oneshot" (OSSL_MAC_PARAM_DIGEST_ONESHOT) <integer>

A flag to set the MAC digest to be a one-shot operation. The value 0 or 1 is expected. This option is deprecated and will be removed in a future release. It may be set but is currently ignored.

"tls-data-size" (OSSL_MAC_PARAM_TLS_DATA_SIZE) <unsigned integer>

"key-check" (OSSL_MAC_PARAM_FIPS_KEY_CHECK) <integer>

See "Mac Parameters" in provider-mac(7).

The following parameters can be retrieved with EVP_MAC_CTX_get_params():

"size" (OSSL_MAC_PARAM_SIZE) <unsigned integer>

The "size" parameter can also be retrieved with EVP_MAC_CTX_get_mac_size(). The length of the "size" parameter is equal to that of an unsigned int.

"block-size" (OSSL_MAC_PARAM_BLOCK_SIZE) <unsigned integer>

Gets the MAC block size. The "block-size" parameter can also be retrieved with EVP_MAC_CTX_get_block_size().

"fips-indicator" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) <integer>

See "Mac Parameters" in provider-mac(7).

## SEE ALSO
EVP_MAC_CTX_get_params(3), EVP_MAC_CTX_set_params(3), "PARAMETERS" in EVP_MAC(3), OSSL_PARAM(3), HMAC(3)

## COPYRIGHT
Copyright 2018-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: EVP_MAC-KMAC(7ossl)

summary: KMAC, EVP_MAC\-KMAC128, EVP_MAC\-KMAC256

text:
# EVP_MAC-KMAC(7ossl)

## NAME
EVP_MAC-KMAC, EVP_MAC-KMAC128, EVP_MAC-KMAC256 - The KMAC EVP_MAC implementations

## DESCRIPTION
Support for computing KMAC MACs through the EVP_MAC API.

### Identity
These implementations are identified with one of these names and properties, to be used with EVP_MAC_fetch():

"KMAC-128", "provider=default" or "provider=fips"

"KMAC-256", "provider=default" or "provider=fips"

### Supported parameters
The general description of these parameters can be found in "PARAMETERS" in EVP_MAC(3).

All these parameters (except for "block-size") can be set with EVP_MAC_CTX_set_params(). Furthermore, the "size" parameter can be retrieved with EVP_MAC_CTX_get_params(), or with EVP_MAC_CTX_get_mac_size(). The length of the "size" parameter should not exceed that of a size_t. Likewise, the "block-size" parameter can be retrieved with EVP_MAC_CTX_get_params(), or with EVP_MAC_CTX_get_block_size().

"key" (OSSL_MAC_PARAM_KEY) <octet string>

Sets the MAC key. Setting this parameter is identical to passing a key to EVP_MAC_init(3). The length of the key (in bytes) must be in the range 4...512.

"custom" (OSSL_MAC_PARAM_CUSTOM) <octet string>

Sets the customization string. It is an optional value with a length of at most 512 bytes, and is empty by default.

"size" (OSSL_MAC_PARAM_SIZE) <unsigned integer>

Sets the MAC size. By default, it is 32 for "KMAC-128" and 64 for "KMAC-256".

"block-size" (OSSL_MAC_PARAM_BLOCK_SIZE) <unsigned integer>

Gets the MAC block size. It is 168 for "KMAC-128" and 136 for "KMAC-256".

"xof" (OSSL_MAC_PARAM_XOF) <integer>

The "xof" parameter value is expected to be 1 or 0. Use 1 to enable XOF mode. The default value is 0.

"fips-indicator" (OSSL_MAC_PARAM_FIPS_APPROVED_INDICATOR) <int>

This settable parameter is described in provider-mac(7).

"no-short-mac" (OSSL_MAC_PARAM_FIPS_NO_SHORT_MAC) <integer>

This settable parameter is described in provider-mac(7). It is used by the OpenSSL FIPS provider and the minimum length output for KMAC is defined by NIST's SP 800-185 8.4.2.

"key-check" (OSSL_MAC_PARAM_FIPS_KEY_CHECK) <integer>

This settable parameter is described in provider-mac(7).

The "custom" and "no-short-mac" parameters must be set as part of or before the EVP_MAC_init() call. The "xof" and "size" parameters can be set at any time before EVP_MAC_final(). The "key" parameter is set as part of the EVP_MAC_init() call, but can be set before it instead.

## EXAMPLES

```
  #include <openssl/evp.h>
  #include <openssl/params.h>
  static int do_kmac(const unsigned char *in, size_t in_len,
                     const unsigned char *key, size_t key_len,
                     const unsigned char *custom, size_t custom_len,
                     int xof_enabled, unsigned char *out, int out_len)
  {
      EVP_MAC_CTX *ctx = NULL;
      EVP_MAC *mac = NULL;
      OSSL_PARAM params[4], *p;
      int ret = 0;
      size_t l = 0;
      mac = EVP_MAC_fetch(NULL, "KMAC-128", NULL);
      if (mac == NULL)
          goto err;
      ctx = EVP_MAC_CTX_new(mac);
      /* The mac can be freed after it is used by EVP_MAC_CTX_new */
      EVP_MAC_free(mac);
      if (ctx == NULL)
          goto err;
      /*
       * Setup parameters required before calling EVP_MAC_init()
       * The parameters OSSL_MAC_PARAM_XOF and OSSL_MAC_PARAM_SIZE may also be
       * used at this point.
       */
      p = params;
      *p++ = OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_KEY,
                                               (void *)key, key_len);
      if (custom != NULL && custom_len != 0)
        *p++ = OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_CUSTOM,
                                                 (void *)custom, custom_len);
      *p = OSSL_PARAM_construct_end();
      if (!EVP_MAC_CTX_set_params(ctx, params))
          goto err;
      if (!EVP_MAC_init(ctx))
          goto err;
      /*
       * Note: the following optional parameters can be set any time
       * before EVP_MAC_final().
       */
      p = params;
      *p++ = OSSL_PARAM_construct_int(OSSL_MAC_PARAM_XOF, &xof_enabled);
      *p++ = OSSL_PARAM_construct_int(OSSL_MAC_PARAM_SIZE, &out_len);
      *p = OSSL_PARAM_construct_end();
      if (!EVP_MAC_CTX_set_params(ctx, params))
          goto err;
      /* The update may be called multiple times here for streamed input */
      if (!EVP_MAC_update(ctx, in, in_len))
          goto err;
      if (!EVP_MAC_final(ctx, out, &l, out_len))
          goto err;
      ret = 1;
  err:
      EVP_MAC_CTX_free(ctx);
      return ret;
  }
```

## SEE ALSO
EVP_MAC_CTX_get_params(3), EVP_MAC_CTX_set_params(3), "PARAMETERS" in EVP_MAC(3), OSSL_PARAM(3), SP 800-185 8.4.2 <https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-185.pdf>

## COPYRIGHT
Copyright 2018-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: EVP_MAC-Poly1305(7ossl)

summary: The Poly1305 EVP_MAC implementation

text:
# EVP_MAC-Poly1305(7ossl)

## NAME
EVP_MAC-Poly1305 - The Poly1305 EVP_MAC implementation

## DESCRIPTION
Support for computing Poly1305 MACs through the EVP_MAC API.

### Identity
This implementation is identified with this name and properties, to be used with EVP_MAC_fetch():

"POLY1305", "provider=default"

### Supported parameters
The general description of these parameters can be found in "PARAMETERS" in EVP_MAC(3).

The following parameter can be set with EVP_MAC_CTX_set_params():

"key" (OSSL_MAC_PARAM_KEY) <octet string>

Sets the MAC key. Setting this parameter is identical to passing a key to EVP_MAC_init(3).

The following parameters can be retrieved with EVP_MAC_CTX_get_params():

"size" (OSSL_MAC_PARAM_SIZE) <unsigned integer>

Gets the MAC size.

The "size" parameter can also be retrieved with with EVP_MAC_CTX_get_mac_size(). The length of the "size" parameter should not exceed that of an unsigned int.

## NOTES
The OpenSSL implementation of the Poly 1305 MAC corresponds to RFC 7539.

It is critical to never reuse the key. The security implication noted in RFC 8439 applies equally to the OpenSSL implementation.

## SEE ALSO
EVP_MAC_CTX_get_params(3), EVP_MAC_CTX_set_params(3), "PARAMETERS" in EVP_MAC(3), OSSL_PARAM(3)

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


title: EVP_MAC-Siphash(7ossl)

summary: The Siphash EVP_MAC implementation

text:
# EVP_MAC-Siphash(7ossl)

## NAME
EVP_MAC-Siphash - The Siphash EVP_MAC implementation

## DESCRIPTION
Support for computing Siphash MACs through the EVP_MAC API.

### Identity
This implementation is identified with this name and properties, to be used with EVP_MAC_fetch():

"SIPHASH", "provider=default"

### Supported parameters
The general description of these parameters can be found in "PARAMETERS" in EVP_MAC(3).

All these parameters can be set with EVP_MAC_CTX_set_params(). Furthermore, the "size" parameter can be retrieved with EVP_MAC_CTX_get_params(), or with EVP_MAC_CTX_get_mac_size(). The length of the "size" parameter should not exceed that of a size_t.

"key" (OSSL_MAC_PARAM_KEY) <octet string>

Sets the MAC key. Setting this parameter is identical to passing a key to EVP_MAC_init(3).

"size" (OSSL_MAC_PARAM_SIZE) <unsigned integer>

Sets the MAC size.

"c-rounds" (OSSL_MAC_PARAM_C_ROUNDS) <unsigned integer>

Specifies the number of rounds per message block. By default this is 2.

"d-rounds" (OSSL_MAC_PARAM_D_ROUNDS) <unsigned integer>

Specifies the number of finalisation rounds. By default this is 4.

## SEE ALSO
EVP_MAC_CTX_get_params(3), EVP_MAC_CTX_set_params(3), "PARAMETERS" in EVP_MAC(3), OSSL_PARAM(3)

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