title: EVP_MD-BLAKE2(7ossl)

summary: The BLAKE2 EVP_MD implementation

text:
# EVP_MD-BLAKE2(7ossl)

## NAME
EVP_MD-BLAKE2 - The BLAKE2 EVP_MD implementation

## DESCRIPTION
Support for computing BLAKE2 digests through the EVP_MD API.

### Identities
This implementation is only available with the default provider, and includes the following varieties:

BLAKE2S-256

Known names are "BLAKE2S-256" and "BLAKE2s256".

BLAKE2B-512

Known names are "BLAKE2B-512" and "BLAKE2b512".

### Settable Parameters
"BLAKE2B-512" supports the following EVP_MD_CTX_set_params() key described in "PARAMETERS" in EVP_DigestInit(3).

"size" (OSSL_DIGEST_PARAM_SIZE) <unsigned integer>

### Gettable Parameters
This implementation supports the common gettable parameters described in EVP_MD-common(7).

### Settable Context Parameters
The implementation supports the following OSSL_PARAM(3) entries which are settable for an EVP_MD_CTX with EVP_DigestInit_ex2(3) or EVP_MD_CTX_set_params(3):

"size" (OSSL_DIGEST_PARAM_SIZE) <unsigned integer>

Sets a different digest length for the EVP_DigestFinal(3) output. The value of the "size" parameter must not exceed the default digest length of the respective BLAKE2 algorithm variants, 64 for BLAKE2B-512 and 32 for BLAKE2S-256. The parameter must be set with the EVP_DigestInit_ex2(3) call to have an immediate effect. When set with EVP_MD_CTX_set_params(3) it will have an effect only if the EVP_MD_CTX context is reinitialized.

## SEE ALSO
provider-digest(7), OSSL_PROVIDER-default(7)

## HISTORY
This functionality was added in OpenSSL 3.0.

The variable size support was added in OpenSSL 3.2 for BLAKE2B-512 and in OpenSSL 3.3 for BLAKE2S-256.

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


package: openssl

title: EVP_MD-KECCAK(7ossl)

summary: The KECCAK EVP_MD implementations

text:
# EVP_MD-KECCAK(7ossl)

## NAME
EVP_MD-KECCAK - The KECCAK EVP_MD implementations

## DESCRIPTION
Support for computing KECCAK digests through the EVP_MD API.

### Identities
This implementation is available in the default provider and includes the following varieties:

"KECCAK-224"

"KECCAK-256"

"KECCAK-384"

"KECCAK-512"

### Gettable Parameters
This implementation supports the common gettable parameters described in EVP_MD-common(7).

## SEE ALSO
provider-digest(7), OSSL_PROVIDER-default(7)

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

branch: sisyphus


title: EVP_MD-MD2(7ossl)

summary: The MD2 EVP_MD implementation

text:
# EVP_MD-MD2(7ossl)

## NAME
EVP_MD-MD2 - The MD2 EVP_MD implementation

## DESCRIPTION
Support for computing MD2 digests through the EVP_MD API.

### Identity
This implementation is only available with the legacy provider, and is identified with the name "MD2".

### Gettable Parameters
This implementation supports the common gettable parameters described in EVP_MD-common(7).

## SEE ALSO
provider-digest(7), OSSL_PROVIDER-default(7)

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

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


title: EVP_MD-MD4(7ossl)

summary: The MD4 EVP_MD implementation

text:
# EVP_MD-MD4(7ossl)

## NAME
EVP_MD-MD4 - The MD4 EVP_MD implementation

## DESCRIPTION
Support for computing MD4 digests through the EVP_MD API.

### Identity
This implementation is only available with the legacy provider, and is identified with the name "MD4".

### Gettable Parameters
This implementation supports the common gettable parameters described in EVP_MD-common(7).

## SEE ALSO
provider-digest(7), OSSL_PROVIDER-default(7)

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

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


title: EVP_MD-MD5(7ossl)

summary: The MD5 EVP_MD implementation

text:
# EVP_MD-MD5(7ossl)

## NAME
EVP_MD-MD5 - The MD5 EVP_MD implementation

## DESCRIPTION
Support for computing MD5 digests through the EVP_MD API.

### Identity
This implementation is only available with the default provider, and is identified with the name "MD5".

### Gettable Parameters
This implementation supports the common gettable parameters described in EVP_MD-common(7).

## SEE ALSO
provider-digest(7), OSSL_PROVIDER-default(7)

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

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


title: EVP_MD-MD5-SHA1(7ossl)

summary: The MD5\-SHA1 EVP_MD implementation

text:
# EVP_MD-MD5-SHA1(7ossl)

## NAME
EVP_MD-MD5-SHA1 - The MD5-SHA1 EVP_MD implementation

## DESCRIPTION
Support for computing MD5-SHA1 digests through the EVP_MD API.

MD5-SHA1 is a rather special digest that's used with SSLv3.

### Identity
This implementation is only available with the default provider, and is identified with the name "MD5-SHA1".

### Gettable Parameters
This implementation supports the common gettable parameters described in EVP_MD-common(7).

### Settable Context Parameters
This implementation supports the following OSSL_PARAM(3) entries, settable for an EVP_MD_CTX with EVP_MD_CTX_set_params(3):

"ssl3-ms" (OSSL_DIGEST_PARAM_SSL3_MS) <octet string>

This parameter is set by libssl in order to calculate a signature hash for an SSLv3 CertificateVerify message as per RFC6101. It is only set after all handshake messages have already been digested via OP_digest_update() calls. The parameter provides the master secret value to be added to the digest. The digest implementation should calculate the complete digest as per RFC6101 section 5.6.8. The next call after setting this parameter should be OP_digest_final().

## SEE ALSO
EVP_MD_CTX_set_params(3), provider-digest(7), OSSL_PROVIDER-default(7)

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

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


title: EVP_MD-MDC2(7ossl)

summary: The MDC2 EVP_MD implementation

text:
# EVP_MD-MDC2(7ossl)

## NAME
EVP_MD-MDC2 - The MDC2 EVP_MD implementation

## DESCRIPTION
Support for computing MDC2 digests through the EVP_MD API.

### Identity
This implementation is only available with the legacy provider, and is identified with the name "MDC2".

### Gettable Parameters
This implementation supports the common gettable parameters described in EVP_MD-common(7).

### Settable Context Parameters
This implementation supports the following OSSL_PARAM(3) entries, settable for an EVP_MD_CTX with EVP_MD_CTX_set_params(3):

"pad-type" (OSSL_DIGEST_PARAM_PAD_TYPE) <unsigned integer>

Sets the padding type to be used. Normally the final MDC2 block is padded with zeros. If the pad type is set to 2 then the final block is padded with 0x80 followed by zeros.

## SEE ALSO
EVP_MD_CTX_set_params(3), provider-digest(7), OSSL_PROVIDER-legacy(7)

## 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_MD-NULL(7ossl)

summary: The NULL EVP_MD implementation

text:
# EVP_MD-NULL(7ossl)

## NAME
EVP_MD-NULL - The NULL EVP_MD implementation

## DESCRIPTION
Support for a NULL digest through the EVP_MD API. This algorithm does nothing and returns 1 for its init, update and final methods.

### Algorithm Name
The following algorithm is available in the default provider:

"NULL"

### Gettable Parameters
This implementation supports the common gettable parameters described in EVP_MD-common(7).

## SEE ALSO
EVP_MD_CTX_set_params(3), provider-digest(7), OSSL_PROVIDER-default(7)

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

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


title: EVP_MD-RIPEMD160(7ossl)

summary: The RIPEMD160 EVP_MD implementation

text:
# EVP_MD-RIPEMD160(7ossl)

## NAME
EVP_MD-RIPEMD160 - The RIPEMD160 EVP_MD implementation

## DESCRIPTION
Support for computing RIPEMD160 digests through the EVP_MD API.

### Identities
This implementation is available in both the default and legacy providers, and is identified with any of the names "RIPEMD-160", "RIPEMD160", "RIPEMD" and "RMD160".

### Gettable Parameters
This implementation supports the common gettable parameters described in EVP_MD-common(7).

## SEE ALSO
provider-digest(7), OSSL_PROVIDER-default(7)

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

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

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


title: EVP_MD-SHA1(7ossl)

summary: The SHA1 EVP_MD implementation

text:
# EVP_MD-SHA1(7ossl)

## NAME
EVP_MD-SHA1 - The SHA1 EVP_MD implementation

## DESCRIPTION
Support for computing SHA1 digests through the EVP_MD API.

### Identities
This implementation is available with the FIPS provider as well as the default provider, and is identified with the names "SHA1" and "SHA-1".

### Gettable Parameters
This implementation supports the common gettable parameters described in EVP_MD-common(7).

### Settable Context Parameters
This implementation supports the following OSSL_PARAM(3) entries, settable for an EVP_MD_CTX with EVP_MD_CTX_set_params(3):

"ssl3-ms" (OSSL_DIGEST_PARAM_SSL3_MS) <octet string>

This parameter is set by libssl in order to calculate a signature hash for an SSLv3 CertificateVerify message as per RFC6101. It is only set after all handshake messages have already been digested via OP_digest_update() calls. The parameter provides the master secret value to be added to the digest. The digest implementation should calculate the complete digest as per RFC6101 section 5.6.8. The next call after setting this parameter should be OP_digest_final().

## SEE ALSO
EVP_MD_CTX_set_params(3), provider-digest(7), OSSL_PROVIDER-FIPS(7), OSSL_PROVIDER-default(7)

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

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


title: EVP_MD-SHA2(7ossl)

summary: The SHA2 EVP_MD implementation

text:
# EVP_MD-SHA2(7ossl)

## NAME
EVP_MD-SHA2 - The SHA2 EVP_MD implementation

## DESCRIPTION
Support for computing SHA2 digests through the EVP_MD API.

### Identities
This implementation includes the following varieties:

•

Available with the FIPS provider as well as the default provider:

SHA2-224

Known names are "SHA2-224", "SHA-224" and "SHA224".

SHA2-256

Known names are "SHA2-256", "SHA-256" and "SHA256".

SHA2-384

Known names are "SHA2-384", "SHA-384" and "SHA384".

SHA2-512

Known names are "SHA2-512", "SHA-512" and "SHA512".

•

Available with the default provider:

SHA2-256/192

Known names are "SHA2-256/192", "SHA-256/192" and "SHA256-192".

SHA2-512/224

Known names are "SHA2-512/224", "SHA-512/224" and "SHA512-224".

SHA2-512/256

Known names are "SHA2-512/256", "SHA-512/256" and "SHA512-256".

### Gettable Parameters
This implementation supports the common gettable parameters described in EVP_MD-common(7).

## SEE ALSO
provider-digest(7), OSSL_PROVIDER-FIPS(7), OSSL_PROVIDER-default(7)

## 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_MD-SHA3(7ossl)

summary: The SHA3 EVP_MD implementations

text:
# EVP_MD-SHA3(7ossl)

## NAME
EVP_MD-SHA3 - The SHA3 EVP_MD implementations

## DESCRIPTION
Support for computing SHA3 digests through the EVP_MD API.

### Identities
This implementation is available with the FIPS provider as well as the default provider, and includes the following varieties:

"SHA3-224"

"SHA3-256"

"SHA3-384"

"SHA3-512"

### Gettable Parameters
This implementation supports the common gettable parameters described in EVP_MD-common(7).

## SEE ALSO
provider-digest(7), OSSL_PROVIDER-FIPS(7), OSSL_PROVIDER-default(7)

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

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


title: EVP_MD-SHAKE(7ossl)

summary: SHAKE, EVP_MD\-KECCAK\-KMAC

text:
# EVP_MD-SHAKE(7ossl)

## NAME
EVP_MD-SHAKE, EVP_MD-KECCAK-KMAC - The SHAKE / KECCAK family EVP_MD implementations

## DESCRIPTION
Support for computing SHAKE or KECCAK-KMAC digests through the EVP_MD API.

KECCAK-KMAC is an Extendable Output Function (XOF), with a definition similar to SHAKE, used by the KMAC EVP_MAC implementation (see EVP_MAC-KMAC(7)).

### Identities
This implementation is available in the FIPS provider as well as the default provider, and includes the following varieties:

KECCAK-KMAC-128

Known names are "KECCAK-KMAC-128" and "KECCAK-KMAC128". This is used by EVP_MAC-KMAC128(7). Using the notation from NIST FIPS 202 (Section 6.2), we have KECCAK-KMAC-128(M, d) = KECCAK[256](M || 00, d) (see the description of KMAC128 in Appendix A of NIST SP 800-185).

KECCAK-KMAC-256

Known names are "KECCAK-KMAC-256" and "KECCAK-KMAC256". This is used by EVP_MAC-KMAC256(7). Using the notation from NIST FIPS 202 (Section 6.2), we have KECCAK-KMAC-256(M, d) = KECCAK[512](M || 00, d) (see the description of KMAC256 in Appendix A of NIST SP 800-185).

SHAKE-128

Known names are "SHAKE-128" and "SHAKE128".

SHAKE-256

Known names are "SHAKE-256" and "SHAKE256".

### Parameters
This implementation supports the following OSSL_PARAM(3) entries:

"xoflen" (OSSL_DIGEST_PARAM_XOFLEN) <unsigned integer>

Sets or Gets the digest length for extendable output functions. The length of the "xoflen" parameter should not exceed that of a size_t. The SHAKE-128 and SHAKE-256 implementations do not have any default digest length.

This parameter must be set before calling either EVP_DigestFinal_ex() or EVP_DigestFinal(), since these functions were not designed to handle variable length output. It is recommended to either use EVP_DigestSqueeze() or EVP_DigestFinalXOF() instead.

"size" (OSSL_DIGEST_PARAM_SIZE) <unsigned integer>

An alias of "xoflen".

See "PARAMETERS" in EVP_DigestInit(3) for further information related to parameters

## NOTES
For SHAKE-128, to ensure the maximum security strength of 128 bits, the output length passed to EVP_DigestFinalXOF() should be at least 32.

For SHAKE-256, to ensure the maximum security strength of 256 bits, the output length passed to EVP_DigestFinalXOF() should be at least 64.

## SEE ALSO
EVP_MD_CTX_set_params(3), provider-digest(7), OSSL_PROVIDER-default(7)

## HISTORY
Since OpenSSL 3.4 the SHAKE-128 and SHAKE-256 implementations have no default digest length.

## 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_MD-SM3(7ossl)

summary: The SM3 EVP_MD implementations

text:
# EVP_MD-SM3(7ossl)

## NAME
EVP_MD-SM3 - The SM3 EVP_MD implementations

## DESCRIPTION
Support for computing SM3 digests through the EVP_MD API.

### Identity
This implementation is only available with the default provider, and is identified with the name "SM3".

### Gettable Parameters
This implementation supports the common gettable parameters described in EVP_MD-common(7).

## SEE ALSO
provider-digest(7), OSSL_PROVIDER-default(7)

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

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


title: EVP_MD-WHIRLPOOL(7ossl)

summary: The WHIRLPOOL EVP_MD implementation

text:
# EVP_MD-WHIRLPOOL(7ossl)

## NAME
EVP_MD-WHIRLPOOL - The WHIRLPOOL EVP_MD implementation

## DESCRIPTION
Support for computing WHIRLPOOL digests through the EVP_MD API.

### Identity
This implementation is only available with the legacy provider, and is identified with the name "WHIRLPOOL".

### Gettable Parameters
This implementation supports the common gettable parameters described in EVP_MD-common(7).

## SEE ALSO
provider-digest(7), OSSL_PROVIDER-default(7)

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

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


title: EVP_MD-common(7ossl)

text:
# EVP_MD-common(7ossl)

## NAME
EVP_MD-common - The OpenSSL EVP_MD implementations, common things

## DESCRIPTION
All the OpenSSL EVP_MD implementations understand the following OSSL_PARAM(3) entries that are gettable with EVP_MD_get_params(3), as well as these:

"blocksize" (OSSL_DIGEST_PARAM_BLOCK_SIZE) <unsigned integer>

The digest block size. The length of the "blocksize" parameter should not exceed that of a size_t. This value can also be retrieved with EVP_MD_get_block_size(3).

"size" (OSSL_DIGEST_PARAM_SIZE) <unsigned integer>

The digest output size. The length of the "size" parameter should not exceed that of a size_t. This value can also be retrieved with EVP_MD_get_size(3).

"flags" (OSSL_DIGEST_PARAM_FLAGS) <unsigned integer>

Diverse flags that describe exceptional behaviour for the digest. These flags are described in "DESCRIPTION" in EVP_MD_meth_set_flags(3). The length of the "flags" parameter should equal that of an unsigned long int.

This value can also be retrieved with EVP_MD_get_flags(3).

## SEE ALSO
"PARAMETERS" in EVP_DigestInit(3), EVP_MD_get_params(3), provider-digest(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_PKEY-DH(7ossl)

summary: DH, EVP_PKEY\-DHX, EVP_KEYMGMT\-DH, EVP_KEYMGMT\-DHX

text:
# EVP_PKEY-DH(7ossl)

## NAME
EVP_PKEY-DH, EVP_PKEY-DHX, EVP_KEYMGMT-DH, EVP_KEYMGMT-DHX - EVP_PKEY DH and DHX keytype and algorithm support

## DESCRIPTION
For finite field Diffie-Hellman key agreement, two classes of domain parameters can be used: "safe" domain parameters that are associated with approved named safe-prime groups, and a class of "FIPS186-type" domain parameters. FIPS186-type domain parameters should only be used for backward compatibility with existing applications that cannot be upgraded to use the approved safe-prime groups.

See EVP_PKEY-FFC(7) for more information about FFC keys.

The DH key type uses PKCS#3 format which saves p and g, but not the q value. The DHX key type uses X9.42 format which saves the value of q and this must be used for FIPS186-4. If key validation is required, users should be aware of the nuances associated with FIPS186-4 style parameters as discussed in "DH and DHX key validation".

### DH and DHX domain parameters
In addition to the common FFC parameters that all FFC keytypes should support (see "FFC parameters" in EVP_PKEY-FFC(7)) the DHX and DH keytype implementations support the following:

"group" (OSSL_PKEY_PARAM_GROUP_NAME) <UTF8 string>

Sets or gets a string that associates a DH or DHX named safe prime group with known values for p, q and g. The following values can be used by the OpenSSL's default and FIPS providers: "ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144", "ffdhe8192", "modp_2048", "modp_3072", "modp_4096", "modp_6144", "modp_8192".

The following additional values can also be used by OpenSSL's default provider: "modp_1536", "dh_1024_160", "dh_2048_224", "dh_2048_256".

DH/DHX named groups can be easily validated since the parameters are well known. For protocols that only transfer p and g the value of q can also be retrieved.

### DH and DHX additional parameters
"encoded-pub-key" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) <octet string>

Used for getting and setting the encoding of the DH public key used in a key exchange message for the TLS protocol. See EVP_PKEY_set1_encoded_public_key() and EVP_PKEY_get1_encoded_public_key().

### DH additional domain parameters
"safeprime-generator" (OSSL_PKEY_PARAM_DH_GENERATOR) <integer>

Used for DH generation of safe primes using the old safe prime generator code. The default value is 2. It is recommended to use a named safe prime group instead, if domain parameter validation is required. Randomly generated safe primes are not allowed by FIPS, so setting this value for the OpenSSL FIPS provider will instead choose a named safe prime group based on the size of p.

### DH and DHX domain parameter / key generation parameters
In addition to the common FFC key generation parameters that all FFC key types should support (see "FFC key generation parameters" in EVP_PKEY-FFC(7)) the DH and DHX keytype implementation supports the following:

"type" (OSSL_PKEY_PARAM_FFC_TYPE) <UTF8 string>

Sets the type of parameter generation. For DH valid values are:

"fips186_4"

"default"

"fips186_2"

These are described in "FFC key generation parameters" in EVP_PKEY-FFC(7)

"group"

This specifies that a named safe prime name will be chosen using the "pbits" type.

"generator"

A safe prime generator. See the "safeprime-generator" type above. This is only valid for DH keys.

"pbits" (OSSL_PKEY_PARAM_FFC_PBITS) <unsigned integer>

Sets the size (in bits) of the prime 'p'. For "fips186_4" this must be 2048. For "fips186_2" this must be 1024. For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192.

"priv_len" (OSSL_PKEY_PARAM_DH_PRIV_LEN) <integer>

An optional value to set the maximum length of the generated private key. The default value used if this is not set is the maximum value of BN_num_bits(q)). The minimum value that this can be set to is 2 * s. Where s is the security strength of the key which has values of 112, 128, 152, 176 and 200 for key sizes of 2048, 3072, 4096, 6144 and 8192.

### DH and DHX key validation
For keys that are not a named group the FIPS186-4 standard specifies that the values used for FFC parameter generation are also required for parameter validation. This means that optional FFC domain parameter values for seed, pcounter and gindex or hindex may need to be stored for validation purposes. For DHX the seed and pcounter can be stored in ASN1 data (but the gindex or hindex cannot be stored). It is recommended to use a DH parameters with named safe prime group instead.

With the OpenSSL FIPS provider, EVP_PKEY_param_check(3) and EVP_PKEY_param_check_quick(3) behave in the following way: the parameters are tested if they are either an approved safe prime group OR that the FFC parameters conform to FIPS186-4 as defined in SP800-56Ar3 Assurances of Domain-Parameter Validity.

The OpenSSL default provider uses simpler checks that allows there to be no q value for backwards compatibility, however the EVP_PKEY_param_check(3) will test the p value for being a prime (and a safe prime if q is missing) which can take significant time. The EVP_PKEY_param_check_quick(3) avoids the prime tests.

EVP_PKEY_public_check(3) conforms to SP800-56Ar3 FFC Full Public-Key Validation.

EVP_PKEY_public_check_quick(3) conforms to SP800-56Ar3 FFC Partial Public-Key Validation when the key is an approved named safe prime group, otherwise it is the same as EVP_PKEY_public_check(3).

EVP_PKEY_private_check(3) tests that the private key is in the correct range according to SP800-56Ar3. The OpenSSL FIPS provider requires the value of q to be set (note that this is implicitly set for named safe prime groups). For backwards compatibility the OpenSSL default provider only requires p to be set.

EVP_PKEY_pairwise_check(3) conforms to SP800-56Ar3 Owner Assurance of Pair-wise Consistency.

## EXAMPLES
An EVP_PKEY context can be obtained by calling:

```
    EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
```

A DH key can be generated with a named safe prime group by calling:

```
    int priv_len = 2 * 112;
    OSSL_PARAM params[3];
    EVP_PKEY *pkey = NULL;
    EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
    params[0] = OSSL_PARAM_construct_utf8_string("group", "ffdhe2048", 0);
    /* "priv_len" is optional */
    params[1] = OSSL_PARAM_construct_int("priv_len", &priv_len);
    params[2] = OSSL_PARAM_construct_end();
    EVP_PKEY_keygen_init(pctx);
    EVP_PKEY_CTX_set_params(pctx, params);
    EVP_PKEY_generate(pctx, &pkey);
    ...
    EVP_PKEY_free(pkey);
    EVP_PKEY_CTX_free(pctx);
```

DHX domain parameters can be generated according to FIPS186-4 by calling:

```
    int gindex = 2;
    unsigned int pbits = 2048;
    unsigned int qbits = 256;
    OSSL_PARAM params[6];
    EVP_PKEY *param_key = NULL;
    EVP_PKEY_CTX *pctx = NULL;
    pctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL);
    EVP_PKEY_paramgen_init(pctx);
    params[0] = OSSL_PARAM_construct_uint("pbits", &pbits);
    params[1] = OSSL_PARAM_construct_uint("qbits", &qbits);
    params[2] = OSSL_PARAM_construct_int("gindex", &gindex);
    params[3] = OSSL_PARAM_construct_utf8_string("type", "fips186_4", 0);
    params[4] = OSSL_PARAM_construct_utf8_string("digest", "SHA256", 0);
    params[5] = OSSL_PARAM_construct_end();
    EVP_PKEY_CTX_set_params(pctx, params);
    EVP_PKEY_generate(pctx, &param_key);
    EVP_PKEY_print_params(bio_out, param_key, 0, NULL);
    ...
    EVP_PKEY_free(param_key);
    EVP_PKEY_CTX_free(pctx);
```

A DH key can be generated using domain parameters by calling:

```
    EVP_PKEY *key = NULL;
    EVP_PKEY_CTX *gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL);
    EVP_PKEY_keygen_init(gctx);
    EVP_PKEY_generate(gctx, &key);
    EVP_PKEY_print_private(bio_out, key, 0, NULL);
    ...
    EVP_PKEY_free(key);
    EVP_PKEY_CTX_free(gctx);
```

To validate FIPS186-4 DHX domain parameters decoded from PEM or DER data, additional values used during generation may be required to be set into the key.

EVP_PKEY_todata(), OSSL_PARAM_merge(), and EVP_PKEY_fromdata() are useful to add these parameters to the original key or domain parameters before the actual validation. In production code the return values should be checked.

```
    EVP_PKEY *received_domp = ...; /* parameters received and decoded */
    unsigned char *seed = ...;     /* and additional parameters received */
    size_t seedlen = ...;          /* by other means, required */
    int gindex = ...;              /* for the validation */
    int pcounter = ...;
    int hindex = ...;
    OSSL_PARAM extra_params[4];
    OSSL_PARAM *domain_params = NULL;
    OSSL_PARAM *merged_params = NULL;
    EVP_PKEY_CTX *ctx = NULL, *validate_ctx = NULL;
    EVP_PKEY *complete_domp = NULL;
    EVP_PKEY_todata(received_domp, OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS,
                    &domain_params);
    extra_params[0] = OSSL_PARAM_construct_octet_string("seed", seed, seedlen);
    /*
     * NOTE: For unverifiable g use "hindex" instead of "gindex"
     * extra_params[1] = OSSL_PARAM_construct_int("hindex", &hindex);
     */
    extra_params[1] = OSSL_PARAM_construct_int("gindex", &gindex);
    extra_params[2] = OSSL_PARAM_construct_int("pcounter", &pcounter);
    extra_params[3] = OSSL_PARAM_construct_end();
    merged_params = OSSL_PARAM_merge(domain_params, extra_params);
    ctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL);
    EVP_PKEY_fromdata_init(ctx);
    EVP_PKEY_fromdata(ctx, &complete_domp, OSSL_KEYMGMT_SELECT_ALL,
                      merged_params);
    validate_ctx = EVP_PKEY_CTX_new_from_pkey(NULL, complete_domp, NULL);
    if (EVP_PKEY_param_check(validate_ctx) > 0)
        /* validation_passed(); */
    else
        /* validation_failed(); */
    OSSL_PARAM_free(domain_params);
    OSSL_PARAM_free(merged_params);
    EVP_PKEY_CTX_free(ctx);
    EVP_PKEY_CTX_free(validate_ctx);
    EVP_PKEY_free(complete_domp);
```

## CONFORMING TO
RFC 7919 (TLS ffdhe named safe prime groups)

RFC 3526 (IKE modp named safe prime groups)

RFC 5114 (Additional DH named groups for dh_1024_160", "dh_2048_224" and "dh_2048_256").

The following sections of SP800-56Ar3:

5.5.1.1 FFC Domain Parameter Selection/Generation

Appendix D: FFC Safe-prime Groups

The following sections of FIPS186-4:

A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function.

A.2.3 Generation of canonical generator g.

A.2.1 Unverifiable Generation of the Generator g.

## SEE ALSO
EVP_PKEY-FFC(7), EVP_KEYEXCH-DH(7) EVP_PKEY(3), provider-keymgmt(7), EVP_KEYMGMT(3), 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_PKEY-DSA(7ossl)

text:
# EVP_PKEY-DSA(7ossl)

## NAME
EVP_PKEY-DSA, EVP_KEYMGMT-DSA - EVP_PKEY DSA keytype and algorithm support

## DESCRIPTION
For DSA the FIPS 186-4 standard specifies that the values used for FFC parameter generation are also required for parameter validation. This means that optional FFC domain parameter values for seed, pcounter and gindex may need to be stored for validation purposes. For DSA these fields are not stored in the ASN1 data so they need to be stored externally if validation is required.

As part of FIPS 140-3 DSA is not longer FIPS approved for key generation and signature validation, but is still allowed for signature verification.

### DSA parameters
The DSA key type supports the FFC parameters (see "FFC parameters" in EVP_PKEY-FFC(7)).

It also supports the following parameters:

"sign-check" (OSSL_PKEY_PARAM_FIPS_SIGN_CHECK) <integer

"fips-indicator" (OSSL_PKEY_PARAM_FIPS_APPROVED_INDICATOR) <integer>

See "Common Information Parameters" in provider-keymgmt(7) for more information.

### DSA key generation parameters
The DSA key type supports the FFC key generation parameters (see "FFC key generation parameters" in EVP_PKEY-FFC(7)

The following restrictions apply to the "pbits" field:

For "fips186_4" this must be either 2048 or 3072. For "fips186_2" this must be 1024. For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192.

### DSA key validation
For DSA keys, EVP_PKEY_param_check(3) behaves in the following way: The OpenSSL FIPS provider conforms to the rules within the FIPS186-4 standard for FFC parameter validation. For backwards compatibility the OpenSSL default provider uses a much simpler check (see below) for parameter validation, unless the seed parameter is set.

For DSA keys, EVP_PKEY_param_check_quick(3) behaves in the following way: A simple check of L and N and partial g is performed. The default provider also supports validation of legacy "fips186_2" keys.

For DSA keys, EVP_PKEY_public_check(3), EVP_PKEY_private_check(3) and EVP_PKEY_pairwise_check(3) the OpenSSL default and FIPS providers conform to the rules within SP800-56Ar3 for public, private and pairwise tests respectively.

## EXAMPLES
An EVP_PKEY context can be obtained by calling:

```
    EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DSA", NULL);
```

The DSA domain parameters can be generated by calling:

```
    unsigned int pbits = 2048;
    unsigned int qbits = 256;
    int gindex = 1;
    OSSL_PARAM params[5];
    EVP_PKEY *param_key = NULL;
    EVP_PKEY_CTX *pctx = NULL;
    pctx = EVP_PKEY_CTX_new_from_name(NULL, "DSA", NULL);
    EVP_PKEY_paramgen_init(pctx);
    params[0] = OSSL_PARAM_construct_uint("pbits", &pbits);
    params[1] = OSSL_PARAM_construct_uint("qbits", &qbits);
    params[2] = OSSL_PARAM_construct_int("gindex", &gindex);
    params[3] = OSSL_PARAM_construct_utf8_string("digest", "SHA384", 0);
    params[4] = OSSL_PARAM_construct_end();
    EVP_PKEY_CTX_set_params(pctx, params);
    EVP_PKEY_generate(pctx, &param_key);
    EVP_PKEY_CTX_free(pctx);
    EVP_PKEY_print_params(bio_out, param_key, 0, NULL);
```

A DSA key can be generated using domain parameters by calling:

```
    EVP_PKEY *key = NULL;
    EVP_PKEY_CTX *gctx = NULL;
    gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL);
    EVP_PKEY_keygen_init(gctx);
    EVP_PKEY_generate(gctx, &key);
    EVP_PKEY_CTX_free(gctx);
    EVP_PKEY_print_private(bio_out, key, 0, NULL);
```

## CONFORMING TO
The following sections of FIPS186-4:

A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function.

A.2.3 Generation of canonical generator g.

A.2.1 Unverifiable Generation of the Generator g.

## SEE ALSO
EVP_PKEY-FFC(7), EVP_SIGNATURE-DSA(7), EVP_PKEY(3), provider-keymgmt(7), EVP_KEYMGMT(3), OSSL_PROVIDER-default(7), OSSL_PROVIDER-FIPS(7)

## HISTORY
DSA Key generation and signature generation are no longer FIPS approved in OpenSSL 3.4. See "FIPS indicators" in fips_module(7) for more information.

## 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_PKEY-EC(7ossl)

summary: EC,

text:
# EVP_PKEY-EC(7ossl)

## NAME
EVP_PKEY-EC, EVP_KEYMGMT-EC - EVP_PKEY EC keytype and algorithm support

## DESCRIPTION
The EC keytype is implemented in OpenSSL's default provider.

### Common EC parameters
The normal way of specifying domain parameters for an EC curve is via the curve name "group". For curves with no curve name, explicit parameters can be used that specify "field-type", "p", "a", "b", "generator" and "order". Explicit parameters are supported for backwards compatibility reasons, but they are not compliant with multiple standards (including RFC5915) which only allow named curves.

The following Key generation/Gettable/Import/Export types are available for the built-in EC algorithm:

"group" (OSSL_PKEY_PARAM_GROUP_NAME) <UTF8 string>

The curve name.

"field-type" (OSSL_PKEY_PARAM_EC_FIELD_TYPE) <UTF8 string>

The value should be either "prime-field" or "characteristic-two-field", which correspond to prime field Fp and binary field F2^m.

"p" (OSSL_PKEY_PARAM_EC_P) <unsigned integer>

For a curve over Fp p is the prime for the field. For a curve over F2^m p represents the irreducible polynomial - each bit represents a term in the polynomial. Therefore, there will either be three or five bits set dependent on whether the polynomial is a trinomial or a pentanomial.

"a" (OSSL_PKEY_PARAM_EC_A) <unsigned integer>

"b" (OSSL_PKEY_PARAM_EC_B) <unsigned integer>

"seed" (OSSL_PKEY_PARAM_EC_SEED) <octet string>

a and b represents the coefficients of the curve For Fp: y^2 mod p = x^3 +ax + b mod p OR For F2^m: y^2 + xy = x^3 + ax^2 + b seed is an optional value that is for information purposes only. It represents the random number seed used to generate the coefficient b from a random number.

"generator" (OSSL_PKEY_PARAM_EC_GENERATOR) <octet string>

"order" (OSSL_PKEY_PARAM_EC_ORDER) <unsigned integer>

"cofactor" (OSSL_PKEY_PARAM_EC_COFACTOR) <unsigned integer>

The generator is a well defined point on the curve chosen for cryptographic operations. The encoding conforms with Sec. 2.3.3 of the SECG SEC 1 ("Elliptic Curve Cryptography") standard. See EC_POINT_oct2point(). Integers used for point multiplications will be between 0 and order - 1. cofactor is an optional value. order multiplied by the cofactor gives the number of points on the curve.

"decoded-from-explicit" (OSSL_PKEY_PARAM_EC_DECODED_FROM_EXPLICIT_PARAMS) <integer>

Gets a flag indicating whether the key or parameters were decoded from explicit curve parameters. Set to 1 if so or 0 if a named curve was used.

"use-cofactor-flag" (OSSL_PKEY_PARAM_USE_COFACTOR_ECDH) <integer>

Enable Cofactor DH (ECC CDH) if this value is 1, otherwise it uses normal EC DH if the value is zero. The cofactor variant multiplies the shared secret by the EC curve's cofactor (note for some curves the cofactor is 1). See also EVP_KEYEXCH-ECDH(7) for the related OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE parameter that can be set on a per-operation basis.

"encoding" (OSSL_PKEY_PARAM_EC_ENCODING) <UTF8 string>

Set the format used for serializing the EC group parameters. Valid values are "explicit" or "named_curve". The default value is "named_curve".

"point-format" (OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT) <UTF8 string>

Sets or gets the point_conversion_form for the key. For a description of point_conversion_forms please see EC_POINT_new(3). Valid values are "uncompressed" or "compressed". The default value is "uncompressed".

"group-check" (OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE) <UTF8 string>

Sets or Gets the type of group check done when EVP_PKEY_param_check() is called. Valid values are "default", "named" and "named-nist". The "named" type checks that the domain parameters match the inbuilt curve parameters, "named-nist" is similar but also checks that the named curve is a nist curve. The "default" type does domain parameter validation for the OpenSSL default provider, but is equivalent to "named-nist" for the OpenSSL FIPS provider.

"include-public" (OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC) <integer>

Setting this value to 0 indicates that the public key should not be included when encoding the private key. The default value of 1 will include the public key.

"pub" (OSSL_PKEY_PARAM_PUB_KEY) <octet string>

The public key value in encoded EC point format conforming to Sec. 2.3.3 and 2.3.4 of the SECG SEC 1 ("Elliptic Curve Cryptography") standard. This parameter is used when importing or exporting the public key value with the EVP_PKEY_fromdata() and EVP_PKEY_todata() functions. Note, in particular, that the choice of point compression format used for encoding the exported value via EVP_PKEY_todata() depends on the underlying provider implementation. Before OpenSSL 3.0.8, the implementation of providers included with OpenSSL always opted for an encoding in compressed format, unconditionally. Since OpenSSL 3.0.8, the implementation has been changed to honor the OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT parameter, if set, or to default to uncompressed format.

"priv" (OSSL_PKEY_PARAM_PRIV_KEY) <unsigned integer>

The private key value.

"encoded-pub-key" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) <octet string>

Used for getting and setting the encoding of an EC public key. The public key is expected to be a point conforming to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic Curve Cryptography") standard.

"qx" (OSSL_PKEY_PARAM_EC_PUB_X) <unsigned integer>

Used for getting the EC public key X component.

"qy" (OSSL_PKEY_PARAM_EC_PUB_Y) <unsigned integer>

Used for getting the EC public key Y component.

"default-digest" (OSSL_PKEY_PARAM_DEFAULT_DIGEST) <UTF8 string>

Getter that returns the default digest name. (Currently returns "SHA256" as of OpenSSL 3.0).

"dhkem-ikm" (OSSL_PKEY_PARAM_DHKEM_IKM) <octet string>

DHKEM requires the generation of a keypair using an input key material (seed). Use this to specify the key material used for generation of the private 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).

The following Gettable types are also available for the built-in EC algorithm:

"basis-type" (OSSL_PKEY_PARAM_EC_CHAR2_TYPE) <UTF8 string>

Supports the values "tpBasis" for a trinomial or "ppBasis" for a pentanomial. This field is only used for a binary field F2^m.

"m" (OSSL_PKEY_PARAM_EC_CHAR2_M) <integer>

"tp" (OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS) <integer>

"k1" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K1) <integer>

"k2" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K2) <integer>

"k3" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K3) <integer>

These fields are only used for a binary field F2^m. m is the degree of the binary field. tp is the middle bit of a trinomial so its value must be in the range m > tp > 0.

k1, k2 and k3 are used to get the middle bits of a pentanomial such that m > k3 > k2 > k1 > 0

The following key generation settable parameter is also available for the OpenSSL FIPS provider's EC algorithm:

"key-check" (OSSL_PKEY_PARAM_FIPS_KEY_CHECK) <integer>

See "Common Information Parameters" in provider-keymgmt(7) for further information.

The following key generation Gettable parameter is available for the OpenSSL FIPS provider's EC algorithm:

"fips-indicator" (OSSL_PKEY_PARAM_FIPS_APPROVED_INDICATOR) <integer>

See "Common Information Parameters" in provider-keymgmt(7) for further information.

### EC key validation
For EC keys, EVP_PKEY_param_check(3) behaves in the following way: For the OpenSSL default provider it uses either EC_GROUP_check(3) or EC_GROUP_check_named_curve(3) depending on the flag EC_FLAG_CHECK_NAMED_GROUP. The OpenSSL FIPS provider uses EC_GROUP_check_named_curve(3) in order to conform to SP800-56Ar3 Assurances of Domain-Parameter Validity.

For EC keys, EVP_PKEY_param_check_quick(3) is equivalent to EVP_PKEY_param_check(3).

For EC keys, EVP_PKEY_public_check(3) and EVP_PKEY_public_check_quick(3) conform to SP800-56Ar3 ECC Full Public-Key Validation and ECC Partial Public-Key Validation respectively.

For EC Keys, EVP_PKEY_private_check(3) and EVP_PKEY_pairwise_check(3) conform to SP800-56Ar3 Private key validity and Owner Assurance of Pair-wise Consistency respectively.

## EXAMPLES
An EVP_PKEY context can be obtained by calling:

```
    EVP_PKEY_CTX *pctx =
        EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
```

An EVP_PKEY ECDSA or ECDH key can be generated with a "P-256" named group by calling:

```
    pkey = EVP_EC_gen("P-256");
```

or like this:

```
    EVP_PKEY *key = NULL;
    OSSL_PARAM params[2];
    EVP_PKEY_CTX *gctx =
        EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
    EVP_PKEY_keygen_init(gctx);
    params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
                                                 "P-256", 0);
    params[1] = OSSL_PARAM_construct_end();
    EVP_PKEY_CTX_set_params(gctx, params);
    EVP_PKEY_generate(gctx, &key);
    EVP_PKEY_print_private(bio_out, key, 0, NULL);
    ...
    EVP_PKEY_free(key);
    EVP_PKEY_CTX_free(gctx);
```

An EVP_PKEY EC CDH (Cofactor Diffie-Hellman) key can be generated with a "K-571" named group by calling:

```
    int use_cdh = 1;
    EVP_PKEY *key = NULL;
    OSSL_PARAM params[3];
    EVP_PKEY_CTX *gctx =
        EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
    EVP_PKEY_keygen_init(gctx);
    params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
                                                 "K-571", 0);
    /*
     * This curve has a cofactor that is not 1 - so setting CDH mode changes
     * the behaviour. For many curves the cofactor is 1 - so setting this has
     * no effect.
     */
    params[1] = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH,
                                         &use_cdh);
    params[2] = OSSL_PARAM_construct_end();
    EVP_PKEY_CTX_set_params(gctx, params);
    EVP_PKEY_generate(gctx, &key);
    EVP_PKEY_print_private(bio_out, key, 0, NULL);
    ...
    EVP_PKEY_free(key);
    EVP_PKEY_CTX_free(gctx);
```

## SEE ALSO
EVP_EC_gen(3), EVP_KEYMGMT(3), EVP_PKEY(3), provider-keymgmt(7), EVP_SIGNATURE-ECDSA(7), EVP_KEYEXCH-ECDH(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_PKEY-FFC(7ossl)

text:
# EVP_PKEY-FFC(7ossl)

## NAME
EVP_PKEY-FFC - EVP_PKEY DSA and DH/DHX shared FFC parameters.

## DESCRIPTION
Finite field cryptography (FFC) is a method of implementing discrete logarithm cryptography using finite field mathematics. DSA is an example of FFC and Diffie-Hellman key establishment algorithms specified in SP800-56A can also be implemented as FFC.

The DSA, DH and DHX keytypes are implemented in OpenSSL's default and FIPS providers. The implementations support the basic DSA, DH and DHX keys, containing the public and private keys pub and priv as well as the three main domain parameters p, q and g.

For DSA (and DH that is not a named group) the FIPS186-4 standard specifies that the values used for FFC parameter generation are also required for parameter validation. This means that optional FFC domain parameter values for seed, pcounter and gindex may need to be stored for validation purposes. For DH the seed and pcounter can be stored in ASN1 data (but the gindex is not). For DSA however, these fields are not stored in the ASN1 data so they need to be stored externally if validation is required.

The DH key type uses PKCS#3 format which saves p and g, but not the 'q' value. The DHX key type uses X9.42 format which saves the value of 'q' and this must be used for FIPS186-4.

### FFC parameters
In addition to the common parameters that all keytypes should support (see "Common parameters" in provider-keymgmt(7)), the DSA, DH and DHX keytype implementations support the following.

"pub" (OSSL_PKEY_PARAM_PUB_KEY) <unsigned integer>

The public key value.

"priv" (OSSL_PKEY_PARAM_PRIV_KEY) <unsigned integer>

The private key value.

### FFC DSA, DH and DHX domain parameters
"p" (OSSL_PKEY_PARAM_FFC_P) <unsigned integer>

A DSA or Diffie-Hellman prime "p" value.

"g" (OSSL_PKEY_PARAM_FFC_G) <unsigned integer>

A DSA or Diffie-Hellman generator "g" value.

### FFC DSA and DHX domain parameters
"q" (OSSL_PKEY_PARAM_FFC_Q) <unsigned integer>

A DSA or Diffie-Hellman prime "q" value.

"seed" (OSSL_PKEY_PARAM_FFC_SEED) <octet string>

An optional domain parameter seed value used during generation and validation of p, q and canonical g. For validation this needs to set the seed that was produced during generation.

"gindex" (OSSL_PKEY_PARAM_FFC_GINDEX) <integer>

Sets the index to use for canonical generation and verification of the generator g. Set this to a positive value from 0..FF to use this mode. This gindex can then be reused during key validation to verify the value of g. If this value is not set or is -1 then unverifiable generation of the generator g will be used.

"pcounter" (OSSL_PKEY_PARAM_FFC_PCOUNTER) <integer>

An optional domain parameter counter value that is output during generation of p. This value must be saved if domain parameter validation is required.

"hindex" (OSSL_PKEY_PARAM_FFC_H) <integer>

For unverifiable generation of the generator g this value is output during generation of g. Its value is the first integer larger than one that satisfies g = h^j mod p (where g != 1 and "j" is the cofactor).

"j" (OSSL_PKEY_PARAM_FFC_COFACTOR) <unsigned integer>

An optional informational cofactor parameter that should equal to (p - 1) / q.

"validate-pq" (OSSL_PKEY_PARAM_FFC_VALIDATE_PQ) <unsigned integer>

"validate-g" (OSSL_PKEY_PARAM_FFC_VALIDATE_G) <unsigned integer>

These boolean values are used during FIPS186-4 or FIPS186-2 key validation checks (See EVP_PKEY_param_check(3)) to select validation options. By default validate-pq and validate-g are both set to 1 to check that p,q and g are valid. Either of these may be set to 0 to skip a test, which is mainly useful for testing purposes.

"validate-legacy" (OSSL_PKEY_PARAM_FFC_VALIDATE_LEGACY) <unsigned integer>

This boolean value is used during key validation checks (See EVP_PKEY_param_check(3)) to select the validation type. The default value of 0 selects FIPS186-4 validation. Setting this value to 1 selects FIPS186-2 validation.

### FFC key generation parameters
The following key generation types are available for DSA and DHX algorithms:

"type" (OSSL_PKEY_PARAM_FFC_TYPE) <UTF8 string>

Sets the type of parameter generation. The shared valid values are:

"fips186_4"

The current standard.

"fips186_2"

The old standard that should only be used for legacy purposes.

"default"

This can choose one of "fips186_4" or "fips186_2" depending on other parameters set for parameter generation.

"pbits" (OSSL_PKEY_PARAM_FFC_PBITS) <unsigned integer>

Sets the size (in bits) of the prime 'p'.

"qbits" (OSSL_PKEY_PARAM_FFC_QBITS) <unsigned integer>

Sets the size (in bits) of the prime 'q'. For "fips186_4" this can be either 224 or 256. For "fips186_2" this has a size of 160.

"digest" (OSSL_PKEY_PARAM_FFC_DIGEST) <UTF8 string>

Sets the Digest algorithm to be used as part of the Key Generation Function associated with the given Key Generation ctx. This must also be set for key validation.

"properties" (OSSL_PKEY_PARAM_FFC_DIGEST_PROPS) <UTF8 string>

Sets properties to be used upon look up of the implementation for the selected Digest algorithm for the Key Generation Function associated with the given key generation ctx. This may also be set for key validation.

"seed" (OSSL_PKEY_PARAM_FFC_SEED) <octet string>

For "fips186_4" or "fips186_2" generation this sets the seed data to use instead of generating a random seed internally. This should be used for testing purposes only. This will either produce fixed values for the generated parameters OR it will fail if the seed did not generate valid primes.

"gindex" (OSSL_PKEY_PARAM_FFC_GINDEX) <integer>

"pcounter" (OSSL_PKEY_PARAM_FFC_PCOUNTER) <integer>

"hindex" (OSSL_PKEY_PARAM_FFC_H) <integer>

These types are described above.

## CONFORMING TO
The following sections of SP800-56Ar3:

5.5.1.1 FFC Domain Parameter Selection/Generation

The following sections of FIPS186-4:

A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function.

A.2.3 Generation of canonical generator g.

A.2.1 Unverifiable Generation of the Generator g.

## SEE ALSO
EVP_PKEY-DSA(7), EVP_PKEY-DH(7), EVP_SIGNATURE-DSA(7), EVP_KEYEXCH-DH(7), EVP_KEYMGMT(3), EVP_PKEY(3), provider-keymgmt(7), OSSL_PROVIDER-default(7), OSSL_PROVIDER-FIPS(7),

## 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_PKEY-HMAC(7ossl)

summary: HMAC, EVP_KEYMGMT\-HMAC, EVP_PKEY\-Siphash, EVP_KEYMGMT\-Siphash,

text:
# EVP_PKEY-HMAC(7ossl)

## NAME
EVP_PKEY-HMAC, EVP_KEYMGMT-HMAC, EVP_PKEY-Siphash, EVP_KEYMGMT-Siphash, EVP_PKEY-Poly1305, EVP_KEYMGMT-Poly1305, EVP_PKEY-CMAC, EVP_KEYMGMT-CMAC - EVP_PKEY legacy MAC keytypes and algorithm support

## DESCRIPTION
The HMAC and CMAC key types are implemented in OpenSSL's default and FIPS providers. Additionally the Siphash and Poly1305 key types are implemented in the default provider. Performing MAC operations via an EVP_PKEY is considered legacy and are only available for backwards compatibility purposes and for a restricted set of algorithms. The preferred way of performing MAC operations is via the EVP_MAC APIs. See EVP_MAC_init(3).

For further details on using EVP_PKEY based MAC keys see EVP_SIGNATURE-HMAC(7), EVP_SIGNATURE-Siphash(7), EVP_SIGNATURE-Poly1305(7) or EVP_SIGNATURE-CMAC(7).

### Common MAC parameters
All the MAC keytypes support the following parameters.

"priv" (OSSL_PKEY_PARAM_PRIV_KEY) <octet string>

The MAC key value.

"properties" (OSSL_PKEY_PARAM_PROPERTIES) <UTF8 string>

A property query string to be used when any algorithms are fetched.

### CMAC parameters
As well as the parameters described above, the CMAC keytype additionally supports the following parameters.

"cipher" (OSSL_PKEY_PARAM_CIPHER) <UTF8 string>

The name of a cipher to be used when generating the MAC.

"engine" (OSSL_PKEY_PARAM_ENGINE) <UTF8 string>

The name of an engine to be used for the specified cipher (if any).

### Common MAC key generation parameters
MAC key generation is unusual in that no new key is actually generated. Instead a new provider side key object is created with the supplied raw key value. This is done for backwards compatibility with previous versions of OpenSSL.

"priv" (OSSL_PKEY_PARAM_PRIV_KEY) <octet string>

The MAC key value.

### CMAC key generation parameters
In addition to the common MAC key generation parameters, the CMAC key generation additionally recognises the following.

"cipher" (OSSL_PKEY_PARAM_CIPHER) <UTF8 string>

The name of a cipher to be used when generating the MAC.

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

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

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


title: EVP_PKEY-ML-DSA(7ossl)

summary: ML\-DSA, EVP_KEYMGMT\-ML\-DSA,

text:
# EVP_PKEY-ML-DSA(7ossl)

## NAME
EVP_PKEY-ML-DSA, EVP_KEYMGMT-ML-DSA, EVP_PKEY-ML-DSA-44, EVP_PKEY-ML-DSA-65, EVP_PKEY-ML-DSA-87 - EVP_PKEY ML-DSA keytype and algorithm support

## DESCRIPTION
ML-DSA implements the algorithms ML-DSA-44, ML-DSA-65 and ML-DSA-87. The key types EVP_PKEY_ML_DSA_44, EVP_PKEY_ML_DSA_65 and EVP_PKEY_ML_DSA_87 are implemented in OpenSSL's default and FIPS providers. These implementations support the associated key, containing the public key pub and the private key priv.

Each of the different key types has an associated security category. This value is one of 2, 3 or 5 for key types ML-DSA-44, ML-DSA-65 and ML-DSA-87 respectively, which correspond to security strengths of 128, 192 and 256 repsectively.

### Keygen Parameters
"seed" (OSSL_PKEY_PARAM_ML_DSA_SEED) <octet string>

The seed can be used to generate the private and public key components in a deterministic manner. The length of the value supplied must be 32 bytes. When this value is not supplied the seed is generated randomly using a DRBG. Generated keys default to retaining the seed used. The seed is also by default retained when keys are loaded from PKCS#8 files in the seed format. When available, the seed parameter is also used during key export and import, with keys (by default) regenerated from the seed even when also provided on import. See "Provider configuration parameters" below for related controls.

When the seed is retained, it is also available as a gettable parameter, and private key output to PKCS#8 files will by default include the seed. When the seed was not initially known, or was not retained, PKCS#8 private key files will contain only the private key in FIPS 204 "sk" format.

"properties" (OSSL_PKEY_PARAM_PROPERTIES) <UTF8 string>

Sets properties to be used when fetching algorithm implementations used for ML-DSA hashing operations.

Use EVP_PKEY_CTX_set_params(3) after calling EVP_PKEY_keygen_init(3).

### Common ML-DSA parameters
In addition to the common parameters that all keytypes should support (see "Common Information Parameters" in provider-keymgmt(7), the implementation of these key types support the parameters listed below. These are gettable using EVP_PKEY_get_octet_string_param(3) or EVP_PKEY_get_params(3). They can be initialised via EVP_PKEY_fromdata(3), and are returned by EVP_PKEY_todata(3) given a suitable selection. Once a public or private key is configured, it can no longer be modified, nor can another key component be added.

"pub" (OSSL_PKEY_PARAM_PUB_KEY) <octet string>

The encoded public key value of size 1312, 1952 or 2592 bytes depending on the respective key type of ML-DSA-44, ML-DSA-65 or ML-DSA-87.

"priv" (OSSL_PKEY_PARAM_PRIV_KEY) <octet string>

The encoded private key value of size 2560, 4032 or 4896 bytes depending on the respective key type of ML-DSA-44, ML-DSA-65 or ML-DSA-87.

### Provider configuration parameters
See the description of the -provparam option in openssl(1) to learn how to set provider configuration parameters in the command line tools. See OSSL_PROVIDER_add_conf_parameter(3) to learn how to set provider configuration options programmatically.

"ml-dsa.retain_seed" (OSSL_PKEY_PARAM_ML_DSA_RETAIN_SEED) <UTF8 string>

When set to a string representing a false boolean value (see OSSL_PROVIDER_conf_get_bool(3)), the seed will not be retained after key generation or key import from a seed value. If the resulting key is then written to a PKCS#8 object, it will contain only the FIPS 204 "sk" key.

"ml-dsa.prefer_seed" (OSSL_PKEY_PARAM_ML_DSA_PREFER_SEED) <UTF8 string>

When decoding PKCS#8 objects that contain both a seed and the FIPS 204 "sk" private key, the seed is by default used to regenerate the key, and the companion private key is ignored. When this configuration parameter is set to a string representing a false boolean value (see OSSL_PROVIDER_conf_get_bool(3)), the seed is ignored (neither used to regenerate the key, nor retained), and the companion key is used instead.

"ml-dsa.input_formats" (OSSL_PKEY_PARAM_ML_DSA_INPUT_FORMATS) <UTF8 string>

List of enabled private key input formats when parsing PKCS#8 objects. List elements are separated by commas, spaces or tabs. The list of enabled formats can be specified in the configuration file, as seen in the "EXAMPLES" section below, or the via the -provparam command-line option (see also OSSL_PROVIDER_add_conf_parameter(3)). Values specified on the command-line override any configuration file settings. By default all the supported formats are enabled. The supported formats are:

"seed-priv":

This format represents PKCS#8 objects in which both the FIPS 204 32-byte ξ seed and the secret key sk are present in the private key as part of the DER encoding of the ASN.1 sequence:

```
    ML-DSA-PrivateKey ::= CHOICE {
      seed [0] IMPLICIT OCTET STRING (SIZE (32)),
      expandedKey OCTET STRING (SIZE (2560 | 4032 | 4896)),
      both SEQUENCE {
        seed OCTET STRING (SIZE (32)),
        expandedKey OCTET STRING (SIZE (2560 | 4032 | 4896)) } }

```

If the "seed-priv" format is not included in the list, this format will not be recognised on input.

"seed-only":

This format represents PKCS#8 objects in which only the 32-byte FIPS 204 ξ seed is present in the above sequence. If the "seed-only" format is not included in the list, this format will not be recognised on input.

"priv-only":

This format represents PKCS#8 objects in which only the FIPS 204 private key sk is present in the above sequence. If the "priv-only" format is not included in the list, this format will not be recognised on input.

"oqskeypair":

This format represents PKCS#8 objects in which the private key is a DER encoding of an octet string containing the concatenaton of the FIPS 204 private key sk and the public key pk. This encoding is used in some builds of the "oqsprovider". If the "oqskeypair" format is not included in the list, this format will not be recognised on input.

"bare-seed":

This format represents PKCS#8 objects in which the private key contains the 32-byte FIPS 204 seed ξ without any ASN.1 encapsulation. If the "bare-seed" format is not included in the list, this format will not be recognised on input.

"bare-priv":

This format represents PKCS#8 objects in which the private key contains the FIPS 204 secret key sk without any ASN.1 encapsulation. If the "bare-priv" format is not included in the list, this format will not be recognised on input.

"ml-dsa.output_formats" (OSSL_PKEY_PARAM_ML_DSA_OUTPUT_FORMATS) <UTF8 string>

Ordered list of enabled private key output formats when writing PKCS#8 files. List elements are separated by commas, spaces or tabs. The list of enabled formats can be specified in the configuration file, as seen in the "EXAMPLES" section below, or the via the -provparam command-line option. This supports the same set of formats as described under "ml-dsa.input_formats" above. The order in which elements are listed is important, the selected format will be the first one that is possible to output. If the key seed is known, the first listed format will be selected. If the key seed is not known, the first format that omits the seed will be selected. The default order is equivalent to "seed-priv" first and "priv-only" second, with both seed and key output when the seed is available, and just the key otherwise. If "seed-only" is listed first, then the seed will be output without the key when available, otherwise the output will have just the key. If "priv-only" is listed first, then just the key is output regardless of whether the seed is present. The legacy "oqskeypair", "bare-seed" and "bare-priv" formats can also be output, by listing those first.

## CONFORMING TO
FIPS 204

## EXAMPLES
An EVP_PKEY context can be obtained by calling:

```
    EVP_PKEY_CTX *pctx =
        EVP_PKEY_CTX_new_from_name(NULL, "ML-DSA-44", NULL);
```

An ML-DSA-44 key can be generated like this:

```
    pkey = EVP_PKEY_Q_keygen(NULL, NULL, "ML-DSA-44");
```

The key pair components can be extracted from a key by calling:

```
    /* Sizes large enough for ML-DSA-87 */
    uint8_t pub[2592], priv[4896], seed[32]:
    size_t priv_len, pub_len, seed_len;
    EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_ML_DSA_SEED,
                                    seed, sizeof(seed), &seed_len);
    EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_PRIV_KEY,
                                    priv, sizeof(priv), &priv_len);
    EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_PUB_KEY,
                                    pub, sizeof(pub), &pub_len));
```

An ML-DSA private key in seed format can be converted to a key in the FIPS 204 sk format by running:

```
    $ openssl pkey -provparam ml-dsa.retain_seed=no \
        -in seed-only.pem -out priv-only.pem
```

To generate an, e.g., ML-DSA-65 key, in FIPS 204 sk format, you can run:

```
    $ openssl genpkey -provparam ml-dsa.retain_seed=no \
        -algorithm ml-dsa-65 -out priv-only.pem
```

If you have a PKCS#8 file with both a seed and a key, and prefer to import the companion key rather than the seed, you can run:

```
    $ openssl pkey -provparam ml-dsa.prefer_seed=no \
        -in seed-priv.pem -out priv-only.pem
```

In the openssl.cnf file, this looks like:

```
    openssl_conf = openssl_init
    [openssl_init]
    providers = providers_sect
    # Can be referenced in one or more provider sections
    [ml_dsa_sect]
    prefer_seed = yes
    retain_seed = yes
    # OQS legacy formats disabled
    input_formats = seed-priv, seed-only, priv-only
    # Output either the seed alone, or else the key alone
    output_formats = seed-only, priv-only
    [providers_sect]
    default = default_sect
    # Or perhaps just: base = default_sect
    base = base_sect
    [default_sect]
    ml-dsa = ml_dsa_sect
    [base_sect]
    ml-dsa = ml_dsa_sect
```

## SEE ALSO
EVP_KEYMGMT(3), EVP_PKEY(3), provider-keymgmt(7), EVP_PKEY_get_raw_private_key(3), EVP_PKEY_get_raw_public_key(3), EVP_PKEY_get1_encoded_public_key(3), OSSL_PROVIDER_add_conf_parameter(3), provider-keymgmt(7), EVP_SIGNATURE-ML-DSA(7)

## HISTORY
This functionality was added in OpenSSL 3.5.

## COPYRIGHT
Copyright 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_PKEY-ML-KEM(7ossl)

summary: ML\-KEM,

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

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

## DESCRIPTION
The ML-KEM-512, ML-KEM-768, and ML-KEM-1024 keytypes are implemented in OpenSSL's default and FIPS providers.

### Keygen Parameters
No mandatory parameters are required for generating a key pair. To set explicit parameters, use EVP_PKEY_CTX_set_params() after calling EVP_PKEY_keygen_init().

"seed" (OSSL_PKEY_PARAM_ML_KEM_SEED) <octet string>

Internally, ML-KEM generates keys using a 64-byte random value (seed), which is the concatenation of the 32-byte d and z parameters described in FIPS 203. This optional parameter can be used to set a pre-determined seed prior to keypair generation. Generated keys default to retaining the seed used. The seed is also by default retained when keys are loaded from PKCS#8 files in the seed format. When available, the seed parameter is also used during key export and import, with keys (by default) regenerated from the seed even when also provided on import. See "Provider configuration parameters" below for related controls.

When the seed is retained, it is also available as a gettable parameter, and private key output to PKCS#8 files will by default include the seed. When the seed was not initially known, or was not retained, PKCS#8 private key files will contain only the private key in FIPS 203 "dk" format.

"properties" (OSSL_PKEY_PARAM_PROPERTIES) <UTF8 string>

Sets properties to be used when fetching algorithm implementations used for ML-KEM hashing operations. Use EVP_PKEY_CTX_set_params(3) after calling EVP_PKEY_keygen_init(3).

### Common parameters
In addition to the common parameters that all keytypes should support (see "Common Information Parameters" in provider-keymgmt(7)), ML-KEM keys keys support the parameters listed below. These are gettable using EVP_PKEY_get_octet_string_param(3) or EVP_PKEY_get_params(3). They can be initialised via EVP_PKEY_fromdata(3), and are returned by EVP_PKEY_todata(3) given a suitable selection. Once a public or private key is configured, it can no longer be modified, nor can another key component be added.

"pub" (OSSL_PKEY_PARAM_PUB_KEY) <octet string>

The public key value. This parameter is used when importing or exporting the public key value with the EVP_PKEY_fromdata() and EVP_PKEY_todata() functions. The key length and content is that of the FIPS 203 (Algorithm 16: ML-KEM.KeyGen_internal) ek public key for the given ML-KEM variant. Initial import aside, this parameter is otherwise only gettable.

"priv" (OSSL_PKEY_PARAM_PRIV_KEY) <octet string>

The private key value. This parameter is used when importing or exporting the private key value with the EVP_PKEY_fromdata() and EVP_PKEY_todata() functions. The key length and content is that of the FIPS 203 (Algorithm 16: ML-KEM.KeyGen_internal) dk private key for the given ML-KEM variant. Initial import aside, this parameter is otherwise only gettable.

"encoded-pub-key" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) <octet string>

Used for getting and setting the encoding of a public key. The key format is that of ek in FIPS 203, Algorithm 16: ML-KEM.KeyGen_internal. Updates of the public and private key components are only allowed on keys that are empty. Once a public or private key component is set, no further changes are allowed. This parameter is gettable and settable (once only).

### Provider configuration parameters
See the description of the -provparam option in openssl(1) to learn how to set provider configuration parameters in the command line tools. See OSSL_PROVIDER_add_conf_parameter(3) to learn how to set provider configuration options programmatically.

"ml-kem.import_pct_type" (OSSL_PKEY_PARAM_ML_KEM_IMPORT_PCT_TYPE) <UTF8 string>

When an ML-KEM key is imported as an explict FIPS 203 dk decapsulation key, rather than a seed, a pairwise consistency test (PCT) is optionally performed. By default, or when this parameter is set explicitly to "random", the PCT is performed with a random entropy value for the encapsulation step. Setting the parameter to "fixed", still runs the test, but the encapsulation entropy is a fixed 32 byte value. Specifying any other value of the parameter, e.g. "none", skips the test.

"ml-kem.retain_seed" (OSSL_PKEY_PARAM_ML_KEM_RETAIN_SEED) <UTF8 string>

When set to a string representing a false boolean value (see OSSL_PROVIDER_conf_get_bool(3)), the seed will not be retained after key generation or key import from a seed value. If the resulting key is then written to a PKCS#8 object, it will contain only the FIPS 203 "dk" key.

"ml-kem.prefer_seed" (OSSL_PKEY_PARAM_ML_KEM_PREFER_SEED) <UTF8 string>

When decoding PKCS#8 objects that contain both a seed and the FIPS 203 "dk" private key, the seed is by default used to regenerate the key, and the companion key is ignored. When this configuration parameter is set to a string representing a false boolean value (see OSSL_PROVIDER_conf_get_bool(3)), the seed is ignored (neither used to regenerate the key, nor retained), and the companion key is used instead.

"ml-kem.input_formats" (OSSL_PKEY_PARAM_ML_KEM_INPUT_FORMATS) <UTF8 string>

List of enabled private key input formats when parsing PKCS#8 objects. List elements are separated by commas and/or spaces or tabs. The list of enabled formats can be specified in the configuration file, as seen in the "EXAMPLES" section below, or the via the -provparam command-line option (see also OSSL_PROVIDER_add_conf_parameter(3)). Values specified on the command-line override any configuration file settings. By default all the supported formats are enabled. The supported formats are:

"seed-priv":

This format represents PKCS#8 objects in which both the FIPS 203 64-byte (d, z) seed and the decapsulation key dk are present in the private key as part of the DER encoding of the ASN.1 sequence:

```
    ML-KEM-PrivateKey ::= CHOICE {
      seed [0] IMPLICIT OCTET STRING (SIZE (64)),
      expandedKey OCTET STRING (SIZE (1632 | 2400 | 3168)),
      both SEQUENCE {
        seed OCTET STRING (SIZE (64)),
        expandedKey OCTET STRING (SIZE (1632 | 2400 | 3168)) } }

```

If the "seed-priv" format is not included in the list, this format will not be recognised on input.

"seed-only":

This format represents PKCS#8 objects in which only the 64-byte (d, z) seed is present in the above sequence. If the "seed-only" format is not included in the list, this format will not be recognised on input.

"priv-only":

This format represents PKCS#8 objects in which only the FIPS 203 decapsulation key dk is present in the above sequence. If the "priv-only" format is not included in the list, this format will not be recognised on input.

"oqskeypair":

This format represents PKCS#8 objects in which the private key is a DER encoding of an octet string containing the concatenaton of the FIPS 203 decapsulation key dk and the encapsulation key ek. This encoding is used in some builds of the "oqsprovider". If the "oqskeypair" format is not included in the list, this format will not be recognised on input.

"bare-seed":

This format represents PKCS#8 objects in which the private key contains the 64-byte FIPS 204 seed (d, z) without any ASN.1 encapsulation. If the "bare-seed" format is not included in the list, this format will not be recognised on input.

"bare-priv":

This format represents PKCS#8 objects in which the private key contains the FIPS 204 decapsulation key dk without any ASN.1 encapsulation. If the "bare-priv" format is not included in the list, this format will not be recognised on input.

"ml-kem.output_formats" (OSSL_PKEY_PARAM_ML_KEM_OUTPUT_FORMATS) <UTF8 string>

Ordered list of enabled private key output formats when writing PKCS#8 files. List elements are separated by commas, spaces or tabs. The list of enabled formats can be specified in the configuration file, as seen in the "EXAMPLES" section below, or the via the -provparam command-line option. This supports the same set of formats as described under "ml-kem.input_formats" above. The order in which elements are listed is important, the selected format will be the first one that is possible to output. If the key seed is known, the first listed format will be selected. If the key seed is not known, the first format that omits the seed will be selected. The default order is equivalent to "seed-priv" first and "priv-only" second, with both seed and key output when the seed is available, and just the key otherwise. If "seed-only" is listed first, then the seed will be output without the key when available, otherwise the output will have just the key. If "priv-only" is listed first, then just the key is output regardless of whether the seed is present. The legacy "oqskeypair", "bare-seed" and "bare-priv" formats can also be output, by listing those first.

## CONFORMING TO
FIPS 203

## EXAMPLES
An EVP_PKEY context can be obtained by calling:

```
    EVP_PKEY_CTX *pctx =
        EVP_PKEY_CTX_new_from_name(NULL, "ML-KEM-768", NULL);
```

An ML-KEM-768 key can be generated like this:

```
    pkey = EVP_PKEY_Q_keygen(NULL, NULL, "ML-KEM-768");
```

An ML-KEM private key in seed format can be converted to a key in the FIPS 203 dk format by running:

```
    $ openssl pkey -provparam ml-kem.retain_seed=no \
        -in seed-only.pem -out priv-only.pem
```

To generate an, e.g., ML-KEM-768 key, in FIPS 203 dk format, you can run:

```
    $ openssl genpkey -provparam ml-kem.retain_seed=no \
        -algorithm ml-kem-768 -out priv-only.pem
```

If you have a PKCS#8 file with both a seed and a key, and prefer to import the companion key rather than the seed, you can run:

```
    $ openssl pkey -provparam ml-kem.prefer_seed=no \
        -in seed-priv.pem -out priv-only.pem
```

In the openssl.cnf file, this looks like:

```
    openssl_conf = openssl_init
    [openssl_init]
    providers = providers_sect
    # Can be referenced in one or more provider sections
    [ml_kem_sect]
    prefer_seed = yes
    retain_seed = yes
    # OQS legacy formats disabled
    input_formats = seed-priv, seed-only, priv-only
    # Output either the seed alone, or else the key alone
    output_formats = seed-only, priv-only
    [providers_sect]
    default = default_sect
    # Or perhaps just: base = default_sect
    base = base_sect
    [default_sect]
    ml-kem = ml_kem_sect
    [base_sect]
    ml-kem = ml_kem_sect
```

## SEE ALSO
openssl(1), openssl-pkey(1), openssl-genpkey(1), EVP_KEYMGMT(3), EVP_PKEY(3), EVP_PKEY_get_raw_private_key(3), EVP_PKEY_get_raw_public_key(3), EVP_PKEY_get1_encoded_public_key(3), OSSL_PROVIDER_add_conf_parameter(3), provider-keymgmt(7), EVP_KEM-ML-KEM(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_PKEY-RSA(7ossl)

summary: RSA, EVP_KEYMGMT\-RSA, RSA

text:
# EVP_PKEY-RSA(7ossl)

## NAME
EVP_PKEY-RSA, EVP_KEYMGMT-RSA, RSA - EVP_PKEY RSA keytype and algorithm support

## DESCRIPTION
The RSA keytype is implemented in OpenSSL's default and FIPS providers. That implementation supports the basic RSA keys, containing the modulus n, the public exponent e, the private exponent d, and a collection of prime factors, exponents and coefficient for CRT calculations, of which the first few are known as p and q, dP and dQ, and qInv.

### Common RSA parameters
In addition to the common parameters that all keytypes should support (see "Common parameters" in provider-keymgmt(7)), the RSA keytype implementation supports the following.

"n" (OSSL_PKEY_PARAM_RSA_N) <unsigned integer>

The RSA modulus "n" value.

"e" (OSSL_PKEY_PARAM_RSA_E) <unsigned integer>

The RSA public exponent "e" value. This value must always be set when creating a raw key using EVP_PKEY_fromdata(3). Note that when a decryption operation is performed, that this value is used for blinding purposes to prevent timing attacks.

"d" (OSSL_PKEY_PARAM_RSA_D) <unsigned integer>

The RSA private exponent "d" value.

"rsa-factor1" (OSSL_PKEY_PARAM_RSA_FACTOR1) <unsigned integer>

"rsa-factor2" (OSSL_PKEY_PARAM_RSA_FACTOR2) <unsigned integer>

"rsa-factor3" (OSSL_PKEY_PARAM_RSA_FACTOR3) <unsigned integer>

"rsa-factor4" (OSSL_PKEY_PARAM_RSA_FACTOR4) <unsigned integer>

"rsa-factor5" (OSSL_PKEY_PARAM_RSA_FACTOR5) <unsigned integer>

"rsa-factor6" (OSSL_PKEY_PARAM_RSA_FACTOR6) <unsigned integer>

"rsa-factor7" (OSSL_PKEY_PARAM_RSA_FACTOR7) <unsigned integer>

"rsa-factor8" (OSSL_PKEY_PARAM_RSA_FACTOR8) <unsigned integer>

"rsa-factor9" (OSSL_PKEY_PARAM_RSA_FACTOR9) <unsigned integer>

"rsa-factor10" (OSSL_PKEY_PARAM_RSA_FACTOR10) <unsigned integer>

RSA prime factors. The factors are known as "p", "q" and "r_i" in RFC8017. Up to eight additional "r_i" prime factors are supported.

"rsa-exponent1" (OSSL_PKEY_PARAM_RSA_EXPONENT1) <unsigned integer>

"rsa-exponent2" (OSSL_PKEY_PARAM_RSA_EXPONENT2) <unsigned integer>

"rsa-exponent3" (OSSL_PKEY_PARAM_RSA_EXPONENT3) <unsigned integer>

"rsa-exponent4" (OSSL_PKEY_PARAM_RSA_EXPONENT4) <unsigned integer>

"rsa-exponent5" (OSSL_PKEY_PARAM_RSA_EXPONENT5) <unsigned integer>

"rsa-exponent6" (OSSL_PKEY_PARAM_RSA_EXPONENT6) <unsigned integer>

"rsa-exponent7" (OSSL_PKEY_PARAM_RSA_EXPONENT7) <unsigned integer>

"rsa-exponent8" (OSSL_PKEY_PARAM_RSA_EXPONENT8) <unsigned integer>

"rsa-exponent9" (OSSL_PKEY_PARAM_RSA_EXPONENT9) <unsigned integer>

"rsa-exponent10" (OSSL_PKEY_PARAM_RSA_EXPONENT10) <unsigned integer>

RSA CRT (Chinese Remainder Theorem) exponents. The exponents are known as "dP", "dQ" and "d_i" in RFC8017. Up to eight additional "d_i" exponents are supported.

"rsa-coefficient1" (OSSL_PKEY_PARAM_RSA_COEFFICIENT1) <unsigned integer>

"rsa-coefficient2" (OSSL_PKEY_PARAM_RSA_COEFFICIENT2) <unsigned integer>

"rsa-coefficient3" (OSSL_PKEY_PARAM_RSA_COEFFICIENT3) <unsigned integer>

"rsa-coefficient4" (OSSL_PKEY_PARAM_RSA_COEFFICIENT4) <unsigned integer>

"rsa-coefficient5" (OSSL_PKEY_PARAM_RSA_COEFFICIENT5) <unsigned integer>

"rsa-coefficient6" (OSSL_PKEY_PARAM_RSA_COEFFICIENT6) <unsigned integer>

"rsa-coefficient7" (OSSL_PKEY_PARAM_RSA_COEFFICIENT7) <unsigned integer>

"rsa-coefficient8" (OSSL_PKEY_PARAM_RSA_COEFFICIENT8) <unsigned integer>

"rsa-coefficient9" (OSSL_PKEY_PARAM_RSA_COEFFICIENT9) <unsigned integer>

RSA CRT (Chinese Remainder Theorem) coefficients. The coefficients are known as "qInv" and "t_i". Up to eight additional "t_i" exponents are supported.

### RSA key generation parameters
When generating RSA keys, the following key generation parameters may be used.

"bits" (OSSL_PKEY_PARAM_RSA_BITS) <unsigned integer>

The value should be the cryptographic length for the RSA cryptosystem, in bits.

"primes" (OSSL_PKEY_PARAM_RSA_PRIMES) <unsigned integer>

The value should be the number of primes for the generated RSA key. The default is 2. It isn't permitted to specify a larger number of primes than 10. Additionally, the number of primes is limited by the length of the key being generated so the maximum number could be less. Some providers may only support a value of 2.

"e" (OSSL_PKEY_PARAM_RSA_E) <unsigned integer>

The RSA "e" value. The value may be any odd number greater than or equal to 65537. The default value is 65537. For legacy reasons a value of 3 is currently accepted but is deprecated.

"rsa-derive-from-pq" (OSSL_PKEY_PARAM_RSA_DERIVE_FROM_PQ) <unsigned integer>

Indicate that missing parameters not passed in the parameter list should be derived if not provided. Setting a nonzero value will cause all needed exponents and coefficients to be derived if not available. Setting this option requires at least OSSL_PARAM_RSA_FACTOR1, OSSL_PARAM_RSA_FACTOR2, and OSSL_PARAM_RSA_N to be provided. This option is ignored if OSSL_KEYMGMT_SELECT_PRIVATE_KEY is not set in the selection parameter.

### RSA key generation parameters for FIPS module testing
When generating RSA keys, the following additional key generation parameters may be used for algorithm testing purposes only. Do not use these to generate RSA keys for a production environment.

"xp" (OSSL_PKEY_PARAM_RSA_TEST_XP) <unsigned integer>

"xq" (OSSL_PKEY_PARAM_RSA_TEST_XQ) <unsigned integer>

These 2 fields are normally randomly generated and are used to generate "p" and "q".

"xp1" (OSSL_PKEY_PARAM_RSA_TEST_XP1) <unsigned integer>

"xp2" (OSSL_PKEY_PARAM_RSA_TEST_XP2) <unsigned integer>

"xq1" (OSSL_PKEY_PARAM_RSA_TEST_XQ1) <unsigned integer>

"xq2" (OSSL_PKEY_PARAM_RSA_TEST_XQ2) <unsigned integer>

These 4 fields are normally randomly generated. The prime factors "p1", "p2", "q1" and "q2" are determined from these values.

### RSA key parameters for FIPS module testing
The following intermediate values can be retrieved only if the values specified in "RSA key generation parameters for FIPS module testing" are set. These should not be accessed in a production environment.

"p1" (OSSL_PKEY_PARAM_RSA_TEST_P1) <unsigned integer>

"p2" (OSSL_PKEY_PARAM_RSA_TEST_P2) <unsigned integer>

"q1" (OSSL_PKEY_PARAM_RSA_TEST_Q1) <unsigned integer>

"q2" (OSSL_PKEY_PARAM_RSA_TEST_Q2) <unsigned integer>

The auxiliary probable primes.

### RSA key validation
For RSA keys, EVP_PKEY_param_check(3) and EVP_PKEY_param_check_quick(3) both return 1 unconditionally.

For RSA keys, EVP_PKEY_public_check(3) conforms to the SP800-56Br1 public key check when the OpenSSL FIPS provider is used. The OpenSSL default provider performs similar tests but relaxes the keysize restrictions for backwards compatibility.

For RSA keys, EVP_PKEY_public_check_quick(3) is the same as EVP_PKEY_public_check(3).

For RSA keys, EVP_PKEY_private_check(3) conforms to the SP800-56Br1 private key test.

For RSA keys, EVP_PKEY_pairwise_check(3) conforms to the SP800-56Br1 KeyPair Validation check for the OpenSSL FIPS provider. The OpenSSL default provider allows testing of the validity of multi-primes.

## CONFORMING TO
FIPS186-4

Section B.3.6 Generation of Probable Primes with Conditions Based on Auxiliary Probable Primes

RFC 8017, excluding RSA-PSS and RSA-OAEP

## EXAMPLES
An EVP_PKEY context can be obtained by calling:

```
    EVP_PKEY_CTX *pctx =
        EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
```

An RSA key can be generated simply like this:

```
    pkey = EVP_RSA_gen(4096);
```

or like this:

```
    EVP_PKEY *pkey = NULL;
    EVP_PKEY_CTX *pctx =
        EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
    EVP_PKEY_keygen_init(pctx);
    EVP_PKEY_generate(pctx, &pkey);
    EVP_PKEY_CTX_free(pctx);
```

An RSA key can be generated with key generation parameters:

```
    unsigned int primes = 3;
    unsigned int bits = 4096;
    OSSL_PARAM params[3];
    EVP_PKEY *pkey = NULL;
    EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
    EVP_PKEY_keygen_init(pctx);
    params[0] = OSSL_PARAM_construct_uint("bits", &bits);
    params[1] = OSSL_PARAM_construct_uint("primes", &primes);
    params[2] = OSSL_PARAM_construct_end();
    EVP_PKEY_CTX_set_params(pctx, params);
    EVP_PKEY_generate(pctx, &pkey);
    EVP_PKEY_print_private(bio_out, pkey, 0, NULL);
    EVP_PKEY_CTX_free(pctx);
```

## SEE ALSO
EVP_RSA_gen(3), EVP_KEYMGMT(3), EVP_PKEY(3), provider-keymgmt(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_PKEY-SLH-DSA(7ossl)

summary: SLH\-DSA, EVP_KEYMGMT\-SLH\-DSA,

text:
# EVP_PKEY-SLH-DSA(7ossl)

## NAME
EVP_PKEY-SLH-DSA, EVP_KEYMGMT-SLH-DSA, EVP_PKEY-SLH-DSA-SHA2-128s, EVP_PKEY-SLH-DSA-SHA2-128f, EVP_PKEY-SLH-DSA-SHA2-192s, EVP_PKEY-SLH-DSA-SHA2-192f, EVP_PKEY-SLH-DSA-SHA2-256s, EVP_PKEY-SLH-DSA-SHA2-256f, EVP_PKEY-SLH-DSA-SHAKE-128s, EVP_PKEY-SLH-DSA-SHAKE-128f, EVP_PKEY-SLH-DSA-SHAKE-192s, EVP_PKEY-SLH-DSA-SHAKE-192f, EVP_PKEY-SLH-DSA-SHAKE-256s, EVP_PKEY-SLH-DSA-SHAKE-256f - EVP_PKEY SLH-DSA keytype and algorithm support

## DESCRIPTION
The SLH-DSA-SHA2-128s, EVP_PKEY-SLH-DSA-SHA2-128f, SLH-DSA-SHA2-192s, EVP_PKEY-SLH-DSA-SHA2-192f, SLH-DSA-SHA2-256s, EVP_PKEY-SLH-DSA-SHA2-256f, SLH-DSA-SHAKE-128s, EVP_PKEY-SLH-DSA-SHAKE-128f, SLH-DSA-SHAKE-192s, EVP_PKEY-SLH-DSA-SHAKE-192f, SLH-DSA-SHAKE-256s and EVP_PKEY-SLH-DSA-SHAKE-256f key types are implemented in OpenSSL's default and FIPS providers. These implementations support the associated key, containing the public key pub and the private key priv.

SLH-DSA (Stateless Hash-based Digital Signature Standard) uses small keys, but has relatively large signatures and is relatively slow performing all operations compared to ML-DSA. It does however have proven security proofs, since it relies only on hash functions.

Each of the different key types has an associated security parameter n. This value is one of 16, 24 or 32 for key types SLH-DSA*128*, SLH-DSA*192* and SLH-DSA*256*, respectively.

Both the public and private key components contain 2 elements of size n. Key generation generates the private key elements and one of the public key elements randomly, and the final public key element is computed from these values.

The public key has relatively small sizes of 32, 48 or 64 bytes, corresponding to the algorithm names of 128, 192 and 256 respectively.

The algorithms ending with s produce smaller signatures, but are much slower than the faster f variants.

The signature sizes for the s algorithm variants are 7856, 16224 and 29792 which correspond to the algorithm names of 128s, 192s and 256s respectively. The signature sizes for the f algorithm variants are 17088, 35664 and 49856 which correspond to the algorithm names containing 128f, 192f and 256f respectively.

Internally there are 7 hash related functions that are used for each algorithm. For algorithms containing SHAKE in their name SHAKE-256 is used for all functions. For the <SHA2-128> algorithms the functions use <MGF1-SHA-256>, <HMAC-SHA-256> and <SHA-256>. The remaining <SHA2> algorithms use <MGF1-SHA-512>, <HMAC-SHA-512>, <SHA-256> and <SHA-512>. See FIPS 205 Section 11.1 and 11.2 for more information.

### Keygen Parameters
"seed" (OSSL_PKEY_PARAM_SLH_DSA_SEED) <octet string>

Supplies values to use for the private seed, private prf and public seed instead of generating random values. This is used for testing purposes only. The length of the value supplied must be 3 * n.

"properties" (OSSL_PKEY_PARAM_PROPERTIES) <utf8_string>

Sets properties to be used when fetching algorithm implementations used for SLH-DSA hashing operations.

Use EVP_PKEY_CTX_set_params() after calling EVP_PKEY_keygen_init().

### Common SLH-DSA parameters
In addition to the common parameters that all keytypes should support (see "Common Information Parameters" in provider-keymgmt(7)), the implementation of these key types support the following.

The following parameters are gettable using EVP_PKEY_get_octet_string_param(), and settable when using EVP_PKEY_fromdata().

"pub" (OSSL_PKEY_PARAM_PUB_KEY) <octet string>

The public key has a size of 2 * n bytes. i.e. It consists of the concatenation of PK.seed and PK.root as defined by FIPS 205 Figure 16.

"priv" (OSSL_PKEY_PARAM_PRIV_KEY) <octet string>

The private key has a size of 4 * n bytes, which includes the public key components. i.e. It consists of the concatenation of SK.seed, SK.prf, PK.seed and PF.root as defined by FIPS 205 Figure 15.

"mandatory-digest" (OSSL_PKEY_PARAM_MANDATORY_DIGEST) <UTF8 string>

The empty string, signifying that no digest may be specified.

## CONFORMING TO
FIPS 205

## EXAMPLES
An EVP_PKEY context can be obtained by calling:

```
    EVP_PKEY_CTX *pctx =
        EVP_PKEY_CTX_new_from_name(NULL, "SLH-DSA-SHA2-128f", NULL);
```

An SLH-DSA key can be generated like this:

```
    pkey = EVP_PKEY_Q_keygen(NULL, NULL, "SLH-DSA-SHA2-128f");
```

The key pair components can be extracted from a key by calling:

```
    uint8_t priv[64], pub[32];
    size_t priv_len, pub_len;
    EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_PRIV_KEY,
                                    priv, sizeof(priv), &priv_len);
    EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_PUB_KEY,
                                    pub, sizeof(pub), &pub_len));
```

Similar code can be used for the other key types such as "SLH-DSA-SHAKE-256f".

## SEE ALSO
EVP_KEYMGMT(3), EVP_PKEY(3), provider-keymgmt(7), EVP_SIGNATURE-SLH-DSA(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_PKEY-SM2(7ossl)

summary: SM2, EVP_KEYMGMT\-SM2, SM2

text:
# EVP_PKEY-SM2(7ossl)

## NAME
EVP_PKEY-SM2, EVP_KEYMGMT-SM2, SM2 - EVP_PKEY keytype support for the Chinese SM2 signature and encryption algorithms

## DESCRIPTION
The SM2 algorithm was first defined by the Chinese national standard GM/T 0003-2012 and was later standardized by ISO as ISO/IEC 14888. SM2 is actually an elliptic curve based algorithm. The current implementation in OpenSSL supports both signature and encryption schemes via the EVP interface.

When doing the SM2 signature algorithm, it requires a distinguishing identifier to form the message prefix which is hashed before the real message is hashed.

### Common SM2 parameters
SM2 uses the parameters defined in "Common EC parameters" in EVP_PKEY-EC(7). The following parameters are different:

"cofactor" (OSSL_PKEY_PARAM_EC_COFACTOR) <unsigned integer>

This parameter is ignored for SM2.

(OSSL_PKEY_PARAM_DEFAULT_DIGEST) <UTF8 string>

Getter that returns the default digest name. (Currently returns "SM3" as of OpenSSL 3.0).

## NOTES
SM2 signatures can be generated by using the 'DigestSign' series of APIs, for instance, EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal(). Ditto for the verification process by calling the 'DigestVerify' series of APIs. Note that the SM2 algorithm requires the presence of the public key for signatures, as such the OSSL_PKEY_PARAM_PUB_KEY option must be set on any key used in signature generation.

Before computing an SM2 signature, an EVP_PKEY_CTX needs to be created, and an SM2 ID must be set for it, like this:

```
 EVP_PKEY_CTX_set1_id(pctx, id, id_len);
```

Before calling the EVP_DigestSignInit() or EVP_DigestVerifyInit() functions, that EVP_PKEY_CTX should be assigned to the EVP_MD_CTX, like this:

```
 EVP_MD_CTX_set_pkey_ctx(mctx, pctx);
```

There is normally no need to pass a pctx parameter to EVP_DigestSignInit() or EVP_DigestVerifyInit() in such a scenario.

SM2 can be tested with the openssl-speed(1) application since version 3.0. Currently, the only valid algorithm name is sm2.

Since version 3.0, SM2 keys can be generated and loaded only when the domain parameters specify the SM2 elliptic curve.

## EXAMPLES
This example demonstrates the calling sequence for using an EVP_PKEY to verify a message with the SM2 signature algorithm and the SM3 hash algorithm:

```
 #include <openssl/evp.h>
 /* obtain an EVP_PKEY using whatever methods... */
 mctx = EVP_MD_CTX_new();
 pctx = EVP_PKEY_CTX_new(pkey, NULL);
 EVP_PKEY_CTX_set1_id(pctx, id, id_len);
 EVP_MD_CTX_set_pkey_ctx(mctx, pctx);
 EVP_DigestVerifyInit(mctx, NULL, EVP_sm3(), NULL, pkey);
 EVP_DigestVerifyUpdate(mctx, msg, msg_len);
 EVP_DigestVerifyFinal(mctx, sig, sig_len)
```

## SEE ALSO
EVP_PKEY_CTX_new(3), EVP_DigestSignInit(3), EVP_DigestVerifyInit(3), EVP_PKEY_CTX_set1_id(3), EVP_MD_CTX_set_pkey_ctx(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_PKEY-X25519(7ossl)

summary: X25519, EVP_PKEY\-X448, EVP_PKEY\-ED25519, EVP_PKEY\-ED448,

text:
# EVP_PKEY-X25519(7ossl)

## NAME
EVP_PKEY-X25519, EVP_PKEY-X448, EVP_PKEY-ED25519, EVP_PKEY-ED448, EVP_KEYMGMT-X25519, EVP_KEYMGMT-X448, EVP_KEYMGMT-ED25519, EVP_KEYMGMT-ED448 - EVP_PKEY X25519, X448, ED25519 and ED448 keytype and algorithm support

## DESCRIPTION
The X25519, X448, ED25519 and ED448 keytypes are implemented in OpenSSL's default and FIPS providers. These implementations support the associated key, containing the public key pub and the private key priv.

### Keygen Parameters
"dhkem-ikm" (OSSL_PKEY_PARAM_DHKEM_IKM) <octet string>

DHKEM requires the generation of a keypair using an input key material (seed). Use this to specify the key material used for generation of the private 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. This is only supported by X25519 and X448.

"fips-indicator" (OSSL_PKEY_PARAM_FIPS_APPROVED_INDICATOR) <integer>

This getter is only supported by X25519 and X448 for the FIPS provider. Since X25519 and X448 are unapproved in FIPS 140-3 this getter return 0. See "Common Information Parameters" in provider-keymgmt(7) for further information.

Use EVP_PKEY_CTX_set_params() after calling EVP_PKEY_keygen_init().

### Common X25519, X448, ED25519 and ED448 parameters
In addition to the common parameters that all keytypes should support (see "Common parameters" in provider-keymgmt(7)), the implementation of these keytypes support the following.

"group" (OSSL_PKEY_PARAM_GROUP_NAME) <UTF8 string>

This is only supported by X25519 and X448. The group name must be "x25519" or "x448" respectively for those algorithms. This is only present for consistency with other key exchange algorithms and is typically not needed.

"pub" (OSSL_PKEY_PARAM_PUB_KEY) <octet string>

The public key value.

"priv" (OSSL_PKEY_PARAM_PRIV_KEY) <octet string>

The private key value.

"encoded-pub-key" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) <octet string>

Used for getting and setting the encoding of a public key for the X25519 and X448 key types. Public keys are expected be encoded in a format as defined by RFC7748.

### ED25519 and ED448 parameters
"mandatory-digest" (OSSL_PKEY_PARAM_MANDATORY_DIGEST) <UTF8 string>

The empty string, signifying that no digest may be specified.

## CONFORMING TO
RFC 8032

RFC 8410

## EXAMPLES
An EVP_PKEY context can be obtained by calling:

```
    EVP_PKEY_CTX *pctx =
        EVP_PKEY_CTX_new_from_name(NULL, "X25519", NULL);
    EVP_PKEY_CTX *pctx =
        EVP_PKEY_CTX_new_from_name(NULL, "X448", NULL);
    EVP_PKEY_CTX *pctx =
        EVP_PKEY_CTX_new_from_name(NULL, "ED25519", NULL);
    EVP_PKEY_CTX *pctx =
        EVP_PKEY_CTX_new_from_name(NULL, "ED448", NULL);
```

An X25519 key can be generated like this:

```
    pkey = EVP_PKEY_Q_keygen(NULL, NULL, "X25519");
```

An X448, ED25519, or ED448 key can be generated likewise.

## SEE ALSO
EVP_KEYMGMT(3), EVP_PKEY(3), provider-keymgmt(7), EVP_KEYEXCH-X25519(7), EVP_KEYEXCH-X448(7), EVP_SIGNATURE-ED25519(7), EVP_SIGNATURE-ED448(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>.