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


package: openssl

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

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

### Settable Context Parameters
These implementations support the following OSSL_PARAM(3) entries, settable for an EVP_MD_CTX with EVP_MD_CTX_set_params(3):

"xoflen" (OSSL_DIGEST_PARAM_XOFLEN) <unsigned integer>

Sets the digest length for extendable output functions. The length of the "xoflen" parameter should not exceed that of a size_t. For backwards compatibility reasons the default xoflen length for SHAKE-128 is 16 (bytes) which results in a security strength of only 64 bits. To ensure the maximum security strength of 128 bits, the xoflen should be set to at least 32.

For backwards compatibility reasons the default xoflen length for SHAKE-256 is 32 (bytes) which results in a security strength of only 128 bits. To ensure the maximum security strength of 256 bits, the xoflen should be set to at least 64.

This parameter may be used when 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.

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

## 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-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
EVP_MD_get_params(3), provider-digest(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_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 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 DSA these fields are not stored in the ASN1 data so they need to be stored externally if validation is required.

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

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

## 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_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 KeyGen/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

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

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-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_RAND(7ossl)

summary: the random bit generator

text:
# EVP_RAND(7ossl)

## NAME
EVP_RAND - the random bit generator

## SYNOPSIS

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

## DESCRIPTION
The default OpenSSL RAND method is based on the EVP_RAND classes to provide non-deterministic inputs to other cryptographic algorithms.

While the RAND API is the 'frontend' which is intended to be used by application developers for obtaining random bytes, the EVP_RAND API serves as the 'backend', connecting the former with the operating systems's entropy sources and providing access to deterministic random bit generators (DRBG) and their configuration parameters. A DRBG is a certain type of cryptographically-secure pseudo-random number generator (CSPRNG), which is described in [NIST SP 800-90A Rev. 1].

### Disclaimer
Unless you have very specific requirements for your random generator, it is in general not necessary to utilize the EVP_RAND API directly. The usual way to obtain random bytes is to use RAND_bytes(3) or RAND_priv_bytes(3), see also RAND(7).

### Typical Use Cases
Typical examples for such special use cases are the following:

- You want to use your own private DRBG instances. Multiple DRBG instances which are accessed only by a single thread provide additional security (because their internal states are independent) and better scalability in multithreaded applications (because they don't need to be locked).

- You need to integrate a previously unsupported entropy source. Refer to provider-rand(7) for the implementation details to support adding randomness sources to EVP_RAND.

- You need to change the default settings of the standard OpenSSL RAND implementation to meet specific requirements.

## EVP_RAND CHAINING
An EVP_RAND instance can be used as the entropy source of another EVP_RAND instance, provided it has itself access to a valid entropy source. The EVP_RAND instance which acts as entropy source is called the parent, the other instance the child. Typically, the child will be a DRBG because it does not make sense for the child to be an entropy source.

This is called chaining. A chained EVP_RAND instance is created by passing a pointer to the parent EVP_RAND_CTX as argument to the EVP_RAND_CTX_new() call. It is possible to create chains of more than two DRBG in a row. It is also possible to use any EVP_RAND_CTX class as the parent, however, only a live entropy source may ignore and not use its parent.

## THE THREE SHARED DRBG INSTANCES
Currently, there are three shared DRBG instances, the <primary>, <public>, and <private> DRBG. While the <primary> DRBG is a single global instance, the <public> and <private> DRBG are created per thread and accessed through thread-local storage.

By default, the functions RAND_bytes(3) and RAND_priv_bytes(3) use the thread-local <public> and <private> DRBG instance, respectively.

### The <primary> DRBG instance
The <primary> DRBG is not used directly by the application, only for reseeding the two other two DRBG instances. It reseeds itself by obtaining randomness either from os entropy sources or by consuming randomness which was added previously by RAND_add(3).

### The <public> DRBG instance
This instance is used per default by RAND_bytes(3).

### The <private> DRBG instance
This instance is used per default by RAND_priv_bytes(3)

## LOCKING
The <primary> DRBG is intended to be accessed concurrently for reseeding by its child DRBG instances. The necessary locking is done internally. It is not thread-safe to access the <primary> DRBG directly via the EVP_RAND interface. The <public> and <private> DRBG are thread-local, i.e. there is an instance of each per thread. So they can safely be accessed without locking via the EVP_RAND interface.

Pointers to these DRBG instances can be obtained using RAND_get0_primary(), RAND_get0_public() and RAND_get0_private(), respectively. Note that it is not allowed to store a pointer to one of the thread-local DRBG instances in a variable or other memory location where it will be accessed and used by multiple threads.

All other DRBG instances created by an application don't support locking, because they are intended to be used by a single thread. Instead of accessing a single DRBG instance concurrently from different threads, it is recommended to instantiate a separate DRBG instance per thread. Using the <primary> DRBG as entropy source for multiple DRBG instances on different threads is thread-safe, because the DRBG instance will lock the <primary> DRBG automatically for obtaining random input.

## THE OVERALL PICTURE
The following picture gives an overview over how the DRBG instances work together and are being used.

```
               +--------------------+
               | os entropy sources |
               +--------------------+
                        |
                        v           +-----------------------------+
     RAND_add() ==> <primary>     <-| shared DRBG (with locking)  |
                      /   \         +-----------------------------+
                     /     \              +---------------------------+
              <public>     <private>   <- | per-thread DRBG instances |
                 |             |          +---------------------------+
                 v             v
               RAND_bytes()   RAND_priv_bytes()
                    |               ^
                    |               |
    +------------------+      +------------------------------------+
    | general purpose  |      | used for secrets like session keys |
    | random generator |      | and private keys for certificates  |
    +------------------+      +------------------------------------+
```

The usual way to obtain random bytes is to call RAND_bytes(...) or RAND_priv_bytes(...). These calls are roughly equivalent to calling EVP_RAND_generate(<public>, ...) and EVP_RAND_generate(<private>, ...), respectively.

## RESEEDING
A DRBG instance seeds itself automatically, pulling random input from its entropy source. The entropy source can be either a trusted operating system entropy source, or another DRBG with access to such a source.

Automatic reseeding occurs after a predefined number of generate requests. The selection of the trusted entropy sources is configured at build time using the --with-rand-seed option. The following sections explain the reseeding process in more detail.

### Automatic Reseeding
Before satisfying a generate request (EVP_RAND_generate(3)), the DRBG reseeds itself automatically, if one of the following conditions holds:

- the DRBG was not instantiated (=seeded) yet or has been uninstantiated.

- the number of generate requests since the last reseeding exceeds a certain threshold, the so called reseed_interval. This behaviour can be disabled by setting the reseed_interval to 0.

- the time elapsed since the last reseeding exceeds a certain time interval, the so called reseed_time_interval. This can be disabled by setting the reseed_time_interval to 0.

- the DRBG is in an error state.

Note: An error state is entered if the entropy source fails while the DRBG is seeding or reseeding. The last case ensures that the DRBG automatically recovers from the error as soon as the entropy source is available again.

### Manual Reseeding
In addition to automatic reseeding, the caller can request an immediate reseeding of the DRBG with fresh entropy by setting the prediction resistance parameter to 1 when calling EVP_RAND_generate(3).

The document [NIST SP 800-90C] describes prediction resistance requests in detail and imposes strict conditions on the entropy sources that are approved for providing prediction resistance. A request for prediction resistance can only be satisfied by pulling fresh entropy from a live entropy source (section 5.5.2 of [NIST SP 800-90C]). It is up to the user to ensure that a live entropy source is configured and is being used.

For the three shared DRBGs (and only for these) there is another way to reseed them manually: If RAND_add(3) is called with a positive randomness argument (or RAND_seed(3)), then this will immediately reseed the <primary> DRBG. The <public> and <private> DRBG will detect this on their next generate call and reseed, pulling randomness from <primary>.

The last feature has been added to support the common practice used with previous OpenSSL versions to call RAND_add() before calling RAND_bytes().

### Entropy Input and Additional Data
The DRBG distinguishes two different types of random input: entropy, which comes from a trusted source, and additional input', which can optionally be added by the user and is considered untrusted. It is possible to add additional input not only during reseeding, but also for every generate request.

### Configuring the Random Seed Source
In most cases OpenSSL will automatically choose a suitable seed source for automatically seeding and reseeding its <primary> DRBG. In some cases however, it will be necessary to explicitly specify a seed source during configuration, using the --with-rand-seed option. For more information, see the INSTALL instructions. There are also operating systems where no seed source is available and automatic reseeding is disabled by default.

The following two sections describe the reseeding process of the primary DRBG, depending on whether automatic reseeding is available or not.

### Reseeding the primary DRBG with automatic seeding enabled
Calling RAND_poll() or RAND_add() is not necessary, because the DRBG pulls the necessary entropy from its source automatically. However, both calls are permitted, and do reseed the RNG.

RAND_add() can be used to add both kinds of random input, depending on the value of the randomness argument:

randomness == 0:

The random bytes are mixed as additional input into the current state of the DRBG. Mixing in additional input is not considered a full reseeding, hence the reseed counter is not reset.

randomness > 0:

The random bytes are used as entropy input for a full reseeding (resp. reinstantiation) if the DRBG is instantiated (resp. uninstantiated or in an error state). The number of random bits required for reseeding is determined by the security strength of the DRBG. Currently it defaults to 256 bits (32 bytes). It is possible to provide less randomness than required. In this case the missing randomness will be obtained by pulling random input from the trusted entropy sources.

NOTE: Manual reseeding is *not allowed* in FIPS mode, because [NIST SP-800-90Ar1] mandates that entropy *shall not* be provided by the consuming application for instantiation (Section 9.1) or reseeding (Section 9.2). For that reason, the randomness argument is ignored and the random bytes provided by the RAND_add(3) and RAND_seed(3) calls are treated as additional data.

### Reseeding the primary DRBG with automatic seeding disabled
Calling RAND_poll() will always fail.

RAND_add() needs to be called for initial seeding and periodic reseeding. At least 48 bytes (384 bits) of randomness have to be provided, otherwise the (re-)seeding of the DRBG will fail. This corresponds to one and a half times the security strength of the DRBG. The extra half is used for the nonce during instantiation.

More precisely, the number of bytes needed for seeding depend on the security strength of the DRBG, which is set to 256 by default.

## SEE ALSO
RAND(7), EVP_RAND(3)

## HISTORY
This functionality was added in OpenSSL 3.0.

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

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


title: EVP_RAND-CTR-DRBG(7ossl)

summary: The CTR DRBG EVP_RAND implementation

text:
# EVP_RAND-CTR-DRBG(7ossl)

## NAME
EVP_RAND-CTR-DRBG - The CTR DRBG EVP_RAND implementation

## DESCRIPTION
Support for the counter deterministic random bit generator through the EVP_RAND API.

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

### Supported parameters
The supported parameters are:

"state" (OSSL_RAND_PARAM_STATE) <integer>

"strength" (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>

"max_request" (OSSL_RAND_PARAM_MAX_REQUEST) <unsigned integer>

"reseed_requests" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>

"reseed_time_interval" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>

"min_entropylen" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>

"max_entropylen" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>

"min_noncelen" (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>

"max_noncelen" (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>

"max_perslen" (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>

"max_adinlen" (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>

"reseed_counter" (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>

"properties" (OSSL_DRBG_PARAM_PROPERTIES) <UTF8 string>

"cipher" (OSSL_DRBG_PARAM_CIPHER) <UTF8 string>

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

"use_derivation_function" (OSSL_DRBG_PARAM_USE_DF) <integer>

This Boolean indicates if a derivation function should be used or not. A nonzero value (the default) uses the derivation function. A zero value does not.

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

```
 EVP_RAND *rand = EVP_RAND_fetch(NULL, "CTR-DRBG", NULL);
 EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL);
```

## EXAMPLES

```
 EVP_RAND *rand;
 EVP_RAND_CTX *rctx;
 unsigned char bytes[100];
 OSSL_PARAM params[2], *p = params;
 unsigned int strength = 128;
 rand = EVP_RAND_fetch(NULL, "CTR-DRBG", NULL);
 rctx = EVP_RAND_CTX_new(rand, NULL);
 EVP_RAND_free(rand);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_CIPHER,
                                         SN_aes_256_ctr, 0);
 *p = OSSL_PARAM_construct_end();
 EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params);
 EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
 EVP_RAND_CTX_free(rctx);
```

## CONFORMING TO
NIST SP 800-90A and SP 800-90B

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

## 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_RAND-HASH-DRBG(7ossl)

summary: The HASH DRBG EVP_RAND implementation

text:
# EVP_RAND-HASH-DRBG(7ossl)

## NAME
EVP_RAND-HASH-DRBG - The HASH DRBG EVP_RAND implementation

## DESCRIPTION
Support for the hash deterministic random bit generator through the EVP_RAND API.

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

### Supported parameters
The supported parameters are:

"state" (OSSL_RAND_PARAM_STATE) <integer>

"strength" (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>

"max_request" (OSSL_RAND_PARAM_MAX_REQUEST) <unsigned integer>

"reseed_requests" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>

"reseed_time_interval" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>

"min_entropylen" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>

"max_entropylen" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>

"min_noncelen" (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>

"max_noncelen" (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>

"max_perslen" (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>

"max_adinlen" (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>

"reseed_counter" (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>

"properties" (OSSL_DRBG_PARAM_PROPERTIES) <UTF8 string>

"digest" (OSSL_DRBG_PARAM_DIGEST) <UTF8 string>

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

## NOTES
When the FIPS provider is installed using the -no_drbg_truncated_digests option to fipsinstall, only these digests are permitted (as per FIPS 140-3 IG D.R <https://csrc.nist.gov/CSRC/media/Projects/cryptographic-module-validation-program/documents/fips%20140-3/FIPS%20140-3%20IG.pdf>):

SHA-1

SHA2-256

SHA2-512

SHA3-256

SHA3-512

A context for HASH DRBG can be obtained by calling:

```
 EVP_RAND *rand = EVP_RAND_fetch(NULL, "HASH-DRBG", NULL);
 EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL);
```

## EXAMPLES

```
 EVP_RAND *rand;
 EVP_RAND_CTX *rctx;
 unsigned char bytes[100];
 OSSL_PARAM params[2], *p = params;
 unsigned int strength = 128;
 rand = EVP_RAND_fetch(NULL, "HASH-DRBG", NULL);
 rctx = EVP_RAND_CTX_new(rand, NULL);
 EVP_RAND_free(rand);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_DIGEST, SN_sha512, 0);
 *p = OSSL_PARAM_construct_end();
 EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params);
 EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
 EVP_RAND_CTX_free(rctx);
```

## CONFORMING TO
NIST SP 800-90A and SP 800-90B

## SEE ALSO
EVP_RAND(3), "PARAMETERS" in EVP_RAND(3), openssl-fipsinstall(1)

## HISTORY
OpenSSL 3.1.1 introduced the -no_drbg_truncated_digests option to fipsinstall which restricts the permitted digests when using the FIPS provider in a complaint manner. For details refer to FIPS 140-3 IG D.R <https://csrc.nist.gov/CSRC/media/Projects/cryptographic-module-validation-program/documents/fips%20140-3/FIPS%20140-3%20IG.pdf>.

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

summary: The HMAC DRBG EVP_RAND implementation

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

## NAME
EVP_RAND-HMAC-DRBG - The HMAC DRBG EVP_RAND implementation

## DESCRIPTION
Support for the HMAC deterministic random bit generator through the EVP_RAND API.

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

### Supported parameters
The supported parameters are:

"state" (OSSL_RAND_PARAM_STATE) <integer>

"strength" (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>

"max_request" (OSSL_RAND_PARAM_MAX_REQUEST) <unsigned integer>

"reseed_requests" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>

"reseed_time_interval" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>

"min_entropylen" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>

"max_entropylen" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>

"min_noncelen" (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>

"max_noncelen" (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>

"max_perslen" (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>

"max_adinlen" (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>

"reseed_counter" (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>

"properties" (OSSL_DRBG_PARAM_PROPERTIES) <UTF8 string>

"mac" (OSSL_DRBG_PARAM_MAC) <UTF8 string>

"digest" (OSSL_DRBG_PARAM_DIGEST) <UTF8 string>

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

## NOTES
When using the FIPS provider, only these digests are permitted (as per FIPS 140-3 IG D.R <https://csrc.nist.gov/CSRC/media/Projects/cryptographic-module-validation-program/documents/fips%20140-3/FIPS%20140-3%20IG.pdf>):

SHA-1

SHA2-256

SHA2-512

SHA3-256

SHA3-512

A context for HMAC DRBG can be obtained by calling:

```
 EVP_RAND *rand = EVP_RAND_fetch(NULL, "HMAC-DRBG", NULL);
 EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL);
```

## EXAMPLES

```
 EVP_RAND *rand;
 EVP_RAND_CTX *rctx;
 unsigned char bytes[100];
 OSSL_PARAM params[3], *p = params;
 unsigned int strength = 128;
 rand = EVP_RAND_fetch(NULL, "HMAC-DRBG", NULL);
 rctx = EVP_RAND_CTX_new(rand, NULL);
 EVP_RAND_free(rand);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_MAC, SN_hmac, 0);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_DIGEST, SN_sha256, 0);
 *p = OSSL_PARAM_construct_end();
 EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params);
 EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
 EVP_RAND_CTX_free(rctx);
```

## CONFORMING TO
NIST SP 800-90A and SP 800-90B

## SEE ALSO
EVP_RAND(3), "PARAMETERS" in EVP_RAND(3), openssl-fipsinstall(1)

## HISTORY
OpenSSL 3.1.1 introduced the -no_drbg_truncated_digests option to fipsinstall which restricts the permitted digests when using the FIPS provider in a complaint manner. For details refer to FIPS 140-3 IG D.R <https://csrc.nist.gov/CSRC/media/Projects/cryptographic-module-validation-program/documents/fips%20140-3/FIPS%20140-3%20IG.pdf>).

## 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_RAND-SEED-SRC(7ossl)

text:
# EVP_RAND-SEED-SRC(7ossl)

## NAME
EVP_RAND-SEED-SRC - The randomness seed source EVP_RAND implementation

## DESCRIPTION
Support for deterministic random number generator seeding through the EVP_RAND API.

The seed sources used are specified at the time OpenSSL is configured for building using the --with-rand-seed= option. By default, operating system randomness sources are used.

### Identity
"SEED-SRC" is the name for this implementation; it can be used with the EVP_RAND_fetch() function.

### Supported parameters
The supported parameters are:

"state" (OSSL_RAND_PARAM_STATE) <integer>

"strength" (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>

"max_request" (OSSL_RAND_PARAM_MAX_REQUEST) <unsigned integer>

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

## NOTES
A context for the seed source can be obtained by calling:

```
 EVP_RAND *rand = EVP_RAND_fetch(NULL, "SEED-SRC", NULL);
 EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL);
```

## EXAMPLES

```
 EVP_RAND *rand;
 EVP_RAND_CTX *seed, *rctx;
 unsigned char bytes[100];
 OSSL_PARAM params[2], *p = params;
 unsigned int strength = 128;
 /* Create and instantiate a seed source */
 rand = EVP_RAND_fetch(NULL, "SEED-SRC", NULL);
 seed = EVP_RAND_CTX_new(rand, NULL);
 EVP_RAND_instantiate(seed, strength, 0, NULL, 0, NULL);
 EVP_RAND_free(rand);
 /* Feed this into a DRBG */
 rand = EVP_RAND_fetch(NULL, "CTR-DRBG", NULL);
 rctx = EVP_RAND_CTX_new(rand, seed);
 EVP_RAND_free(rand);
 /* Configure the DRBG */
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_CIPHER,
                                         SN_aes_256_ctr, 0);
 *p = OSSL_PARAM_construct_end();
 EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params);
 EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
 EVP_RAND_CTX_free(rctx);
 EVP_RAND_CTX_free(seed);
```

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

## 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_RAND-TEST-RAND(7ossl)

summary: The test EVP_RAND implementation

text:
# EVP_RAND-TEST-RAND(7ossl)

## NAME
EVP_RAND-TEST-RAND - The test EVP_RAND implementation

## DESCRIPTION
Support for a test generator through the EVP_RAND API. This generator is for test purposes only, it does not generate random numbers.

### Identity
"TEST-RAND" is the name for this implementation; it can be used with the EVP_RAND_fetch() function.

### Supported parameters
The supported parameters are:

"state" (OSSL_RAND_PARAM_STATE) <integer>

These parameter works as described in "PARAMETERS" in EVP_RAND(3).

"strength" (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>

"reseed_requests" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>

"reseed_time_interval" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>

"max_request" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>

"min_entropylen" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>

"max_entropylen" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>

"min_noncelen" (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>

"max_noncelen" (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>

"max_perslen" (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>

"max_adinlen" (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>

"reseed_counter" (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>

These parameters work as described in "PARAMETERS" in EVP_RAND(3), except that they can all be set as well as read.

"test_entropy" (OSSL_RAND_PARAM_TEST_ENTROPY) <octet string>

Sets the bytes returned when the test generator is sent an entropy request. The current position is remembered across generate calls. If there are insufficient data present to satisfy a call, an error is returned.

"test_nonce" (OSSL_RAND_PARAM_TEST_NONCE) <octet string>

Sets the bytes returned when the test generator is sent a nonce request. Each nonce request will return all of the bytes.

"generate" (OSSL_RAND_PARAM_GENERATE) <integer>

If this parameter is zero, it will only emit the nonce and entropy data supplied via the aforementioned parameters. Otherwise, low quality non-cryptographic pseudorandom output is produced. This parameter defaults to zero.

## NOTES
A context for a test generator can be obtained by calling:

```
 EVP_RAND *rand = EVP_RAND_fetch(NULL, "TEST-RAND", NULL);
 EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL);
```

## EXAMPLES

```
 EVP_RAND *rand;
 EVP_RAND_CTX *rctx;
 unsigned char bytes[100];
 OSSL_PARAM params[4], *p = params;
 unsigned char entropy[1000] = { ... };
 unsigned char nonce[20] = { ... };
 unsigned int strength = 48;
 rand = EVP_RAND_fetch(NULL, "TEST-RAND", NULL);
 rctx = EVP_RAND_CTX_new(rand, NULL);
 EVP_RAND_free(rand);
 *p++ = OSSL_PARAM_construct_uint(OSSL_RAND_PARAM_STRENGTH, &strength);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_RAND_PARAM_TEST_ENTROPY,
                                          entropy, sizeof(entropy));
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_RAND_PARAM_TEST_NONCE,
                                          nonce, sizeof(nonce));
 *p = OSSL_PARAM_construct_end();
 EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params);
 EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
 EVP_RAND_CTX_free(rctx);
```

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

## HISTORY
This functionality was added in OpenSSL 3.0.

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

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


title: EVP_SIGNATURE-DSA(7ossl)

summary: DSA

text:
# EVP_SIGNATURE-DSA(7ossl)

## NAME
EVP_SIGNATURE-DSA - The EVP_PKEY DSA signature implementation

## DESCRIPTION
Support for computing DSA signatures. The signature produced with EVP_PKEY_sign(3) is DER encoded ASN.1 in the form described in RFC 3279, section 2.2.2. See EVP_PKEY-DSA(7) for information related to DSA keys.

### Signature Parameters
The following signature parameters can be set using EVP_PKEY_CTX_set_params(). This may be called after EVP_PKEY_sign_init() or EVP_PKEY_verify_init(), and before calling EVP_PKEY_sign() or EVP_PKEY_verify().

"digest" (OSSL_SIGNATURE_PARAM_DIGEST) <UTF8 string>

"properties" (OSSL_SIGNATURE_PARAM_PROPERTIES) <UTF8 string>

"nonce-type" (OSSL_SIGNATURE_PARAM_NONCE_TYPE) <unsigned integer>

The settable parameters are described in provider-signature(7).

The following signature parameters can be retrieved using EVP_PKEY_CTX_get_params().

"algorithm-id" (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) <octet string>

"digest" (OSSL_SIGNATURE_PARAM_DIGEST) <UTF8 string>

"nonce-type" (OSSL_SIGNATURE_PARAM_NONCE_TYPE) <unsigned integer>

The gettable parameters are described in provider-signature(7).

## SEE ALSO
EVP_PKEY_CTX_set_params(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), provider-signature(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_SIGNATURE-ECDSA(7ossl)

text:
# EVP_SIGNATURE-ECDSA(7ossl)

## NAME
EVP_SIGNATURE-ECDSA - The EVP_PKEY ECDSA signature implementation.

## DESCRIPTION
Support for computing ECDSA signatures. See EVP_PKEY-EC(7) for information related to EC keys.

### ECDSA Signature Parameters
The following signature parameters can be set using EVP_PKEY_CTX_set_params(). This may be called after EVP_PKEY_sign_init() or EVP_PKEY_verify_init(), and before calling EVP_PKEY_sign() or EVP_PKEY_verify().

"digest" (OSSL_SIGNATURE_PARAM_DIGEST) <UTF8 string>

"properties" (OSSL_SIGNATURE_PARAM_PROPERTIES) <UTF8 string>

"nonce-type" (OSSL_SIGNATURE_PARAM_NONCE_TYPE) <unsigned integer>

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

The following signature parameters can be retrieved using EVP_PKEY_CTX_get_params().

"algorithm-id" (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) <octet string>

"digest" (OSSL_SIGNATURE_PARAM_DIGEST) <UTF8 string>

"nonce-type" (OSSL_SIGNATURE_PARAM_NONCE_TYPE) <unsigned integer>

The parameters are described in provider-signature(7).

## SEE ALSO
EVP_PKEY_CTX_set_params(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), provider-signature(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_SIGNATURE-ED25519(7ossl)

text:
# EVP_SIGNATURE-ED25519(7ossl)

## NAME
EVP_SIGNATURE-ED25519, EVP_SIGNATURE-ED448, Ed25519, Ed448 - EVP_PKEY Ed25519 and Ed448 support

## DESCRIPTION
The Ed25519 and Ed448 EVP_PKEY implementation supports key generation, one-shot digest-sign and digest-verify using the EdDSA signature scheme described in RFC 8032. It has associated private and public key formats compatible with RFC 8410.

### EdDSA Instances
RFC 8032 describes five EdDSA instances: Ed25519, Ed25519ctx, Ed25519ph, Ed448, Ed448ph.

The instances Ed25519, Ed25519ctx, Ed448 are referred to as PureEdDSA schemes. For these three instances, the sign and verify procedures require access to the complete message (not a digest of the message).

The instances Ed25519ph, Ed448ph are referred to as HashEdDSA schemes. For these two instances, the sign and verify procedures do not require access to the complete message; they operate on a hash of the message. For Ed25519ph, the hash function is SHA512. For Ed448ph, the hash function is SHAKE256 with an output length of 512 bits.

The instances Ed25519ctx, Ed25519ph, Ed448, Ed448ph accept an optional context-string as input to sign and verify operations (and for Ed25519ctx, the context-string must be nonempty). For the Ed25519 instance, a nonempty context-string is not permitted.

### ED25519 and ED448 Signature Parameters
Two parameters can be set during signing or verification: the EdDSA instance name and the context-string value. They can be set by passing an OSSL_PARAM array to EVP_DigestSignInit_ex().

- "instance" (OSSL_SIGNATURE_PARAM_INSTANCE) <utf8 string> One of the five strings "Ed25519", "Ed25519ctx", "Ed25519ph", "Ed448", "Ed448ph".

"Ed25519", "Ed25519ctx", "Ed25519ph" are valid only for an Ed25519 EVP_PKEY.

"Ed448", "Ed448ph" are valid only for an Ed448 EVP_PKEY.

- "context-string" (OSSL_SIGNATURE_PARAM_CONTEXT_STRING) <octet string> A string of octets with length at most 255.

Both of these parameters are optional.

If the instance name is not specified, then the default "Ed25519" or "Ed448" is used.

If a context-string is not specified, then an empty context-string is used.

Note that a message digest name must NOT be specified when signing or verifying.

See EVP_PKEY-X25519(7) for information related to X25519 and X448 keys.

The following signature parameters can be retrieved using EVP_PKEY_CTX_get_params().

- "algorithm-id" (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) <octet string>

- "instance" (OSSL_SIGNATURE_PARAM_INSTANCE) <utf8 string>

- "context-string" (OSSL_SIGNATURE_PARAM_CONTEXT_STRING) <octet string>

The parameters are described in provider-signature(7).

## NOTES
The PureEdDSA instances do not support the streaming mechanism of other signature algorithms using, for example, EVP_DigestUpdate(). The message to sign or verify must be passed using the one-shot EVP_DigestSign() and EVP_DigestVerify() functions.

The HashEdDSA instances do not yet support the streaming mechanisms (so the one-shot functions must be used with HashEdDSA as well).

When calling EVP_DigestSignInit() or EVP_DigestVerifyInit(), the digest type parameter MUST be set to NULL.

Applications wishing to sign certificates (or other structures such as CRLs or certificate requests) using Ed25519 or Ed448 can either use X509_sign() or X509_sign_ctx() in the usual way.

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

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

Ed25519 and Ed448 can be tested with the openssl-speed(1) application since version 1.1.1. Valid algorithm names are ed25519, ed448 and eddsa. If eddsa is specified, then both Ed25519 and Ed448 are benchmarked.

## EXAMPLES
To sign a message using an ED25519 EVP_PKEY structure:

```
    void do_sign(EVP_PKEY *ed_key, unsigned char *msg, size_t msg_len)
    {
        size_t sig_len;
        unsigned char *sig = NULL;
        EVP_MD_CTX *md_ctx = EVP_MD_CTX_new();
        const OSSL_PARAM params[] = {
            OSSL_PARAM_utf8_string ("instance", "Ed25519ctx", 10),
            OSSL_PARAM_octet_string("context-string", (unsigned char *)"A protocol defined context string", 33),
            OSSL_PARAM_END
        };
        /* The input "params" is not needed if default options are acceptable.
           Use NULL in place of "params" in that case. */
        EVP_DigestSignInit_ex(md_ctx, NULL, NULL, NULL, NULL, ed_key, params);
        /* Calculate the required size for the signature by passing a NULL buffer. */
        EVP_DigestSign(md_ctx, NULL, &sig_len, msg, msg_len);
        sig = OPENSSL_zalloc(sig_len);
        EVP_DigestSign(md_ctx, sig, &sig_len, msg, msg_len);
        ...
        OPENSSL_free(sig);
        EVP_MD_CTX_free(md_ctx);
    }
```

## SEE ALSO
EVP_PKEY-X25519(7) provider-signature(7), EVP_DigestSignInit(3), EVP_DigestVerifyInit(3),

## COPYRIGHT
Copyright 2017-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_SIGNATURE-HMAC(7ossl)

summary: HMAC, EVP_SIGNATURE\-Siphash, EVP_SIGNATURE\-Poly1305,

text:
# EVP_SIGNATURE-HMAC(7ossl)

## NAME
EVP_SIGNATURE-HMAC, EVP_SIGNATURE-Siphash, EVP_SIGNATURE-Poly1305, EVP_SIGNATURE-CMAC - The legacy EVP_PKEY MAC signature implementations

## DESCRIPTION
The algorithms described here have legacy support for creating MACs using EVP_DigestSignInit(3) and related functions. This is not the preferred way of creating MACs. Instead you should use the newer EVP_MAC_init(3) functions. This mechanism is provided for backwards compatibility with older versions of OpenSSL.

The same signature parameters can be set using EVP_PKEY_CTX_set_params() as can be set via EVP_MAC_CTX_set_params() for the underlying EVP_MAC. See EVP_MAC-HMAC(7), EVP_MAC-Siphash(7), EVP_MAC-Poly1305(7) and EVP_MAC-CMAC(7) for details.

```
 See L<EVP_PKEY-HMAC(7)>, L<EVP_PKEY-Siphash(7)>, L<EVP_PKEY-Poly1305(7)> or
 L<EVP_PKEY-CMAC(7)> for details about parameters that are supported during the
 creation of an EVP_PKEY.
```

## SEE ALSO
EVP_MAC_init(3), EVP_DigestSignInit(3), EVP_PKEY-HMAC(7), EVP_PKEY-Siphash(7), EVP_PKEY-Poly1305(7), EVP_PKEY-CMAC(7), EVP_MAC-HMAC(7), EVP_MAC-Siphash(7), EVP_MAC-Poly1305(7), EVP_MAC-CMAC(7), provider-signature(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_SIGNATURE-RSA(7ossl)

summary: RSA

text:
# EVP_SIGNATURE-RSA(7ossl)

## NAME
EVP_SIGNATURE-RSA - The EVP_PKEY RSA signature implementation

## DESCRIPTION
Support for computing RSA signatures. See EVP_PKEY-RSA(7) for information related to RSA keys.

### Signature Parameters
The following signature parameters can be set using EVP_PKEY_CTX_set_params(). This may be called after EVP_PKEY_sign_init() or EVP_PKEY_verify_init(), and before calling EVP_PKEY_sign() or EVP_PKEY_verify().

"digest" (OSSL_SIGNATURE_PARAM_DIGEST) <UTF8 string>

"properties" (OSSL_SIGNATURE_PARAM_PROPERTIES) <UTF8 string>

These common parameters are described in provider-signature(7).

"pad-mode" (OSSL_SIGNATURE_PARAM_PAD_MODE) <UTF8 string>

The type of padding to be used. Its value can be one of the following:

"none" (OSSL_PKEY_RSA_PAD_MODE_NONE)

"pkcs1" (OSSL_PKEY_RSA_PAD_MODE_PKCSV15)

"x931" (OSSL_PKEY_RSA_PAD_MODE_X931)

"pss" (OSSL_PKEY_RSA_PAD_MODE_PSS)

"mgf1-digest" (OSSL_SIGNATURE_PARAM_MGF1_DIGEST) <UTF8 string>

The digest algorithm name to use for the maskGenAlgorithm used by "pss" mode.

"mgf1-properties" (OSSL_SIGNATURE_PARAM_MGF1_PROPERTIES) <UTF8 string>

Sets the name of the property query associated with the "mgf1-digest" algorithm. NULL is used if this optional value is not set.

"saltlen" (OSSL_SIGNATURE_PARAM_PSS_SALTLEN) <integer> or <UTF8 string>

The "pss" mode minimum salt length. The value can either be an integer, a string value representing a number or one of the following string values:

"digest" (OSSL_PKEY_RSA_PSS_SALT_LEN_DIGEST)

Use the same length as the digest size.

"max" (OSSL_PKEY_RSA_PSS_SALT_LEN_MAX)

Use the maximum salt length.

"auto" (OSSL_PKEY_RSA_PSS_SALT_LEN_AUTO)

Auto detect the salt length.

"auto-digestmax" (OSSL_PKEY_RSA_PSS_SALT_LEN_AUTO_DIGEST_MAX)

Auto detect the salt length when verifying. Maximize the salt length up to the digest size when signing to comply with FIPS 186-4 section 5.5.

The following signature parameters can be retrieved using EVP_PKEY_CTX_get_params().

"algorithm-id" (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) <octet string>

This common parameter is described in provider-signature(7).

"digest" (OSSL_SIGNATURE_PARAM_DIGEST) <UTF8 string>

"pad-mode" (OSSL_SIGNATURE_PARAM_PAD_MODE) <UTF8 string>

"mgf1-digest" (OSSL_SIGNATURE_PARAM_MGF1_DIGEST) <UTF8 string>

"saltlen" (OSSL_SIGNATURE_PARAM_PSS_SALTLEN) <integer> or <UTF8 string>

These parameters are as described above.

## SEE ALSO
EVP_PKEY_CTX_set_params(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), provider-signature(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>.