EVP_PKEY_CTX_CTRL(3) | Library Functions Manual | EVP_PKEY_CTX_CTRL(3)

# NAME

`EVP_PKEY_CTX_ctrl`, `EVP_PKEY_CTX_ctrl_str`, `EVP_PKEY_CTX_set_signature_md`, `EVP_PKEY_CTX_get_signature_md`, `EVP_PKEY_CTX_set_dsa_paramgen_bits`, `EVP_PKEY_CTX_set_dh_paramgen_prime_len`, `EVP_PKEY_CTX_set_dh_paramgen_generator`, `EVP_PKEY_CTX_set_ec_paramgen_curve_nid`, `EVP_PKEY_CTX_set_ec_param_enc`, `EVP_PKEY_CTX_set_ecdh_cofactor_mode`, `EVP_PKEY_CTX_get_ecdh_cofactor_mode`, `EVP_PKEY_CTX_set_ecdh_kdf_type`, `EVP_PKEY_CTX_get_ecdh_kdf_type`, `EVP_PKEY_CTX_set_ecdh_kdf_md`, `EVP_PKEY_CTX_get_ecdh_kdf_md`, `EVP_PKEY_CTX_set_ecdh_kdf_outlen`, `EVP_PKEY_CTX_get_ecdh_kdf_outlen`, `EVP_PKEY_CTX_set0_ecdh_kdf_ukm`, `EVP_PKEY_CTX_get0_ecdh_kdf_ukm`, `EVP_PKEY_CTX_set1_id`, `EVP_PKEY_CTX_get1_id`, `EVP_PKEY_CTX_get1_id_len` — algorithm specific control operations

# SYNOPSIS

library “libcrypto”
`#include <openssl/evp.h>`

int
`EVP_PKEY_CTX_ctrl`(EVP_PKEY_CTX *ctx, int keytype, int optype, int cmd, int p1, void *p2);

int
`EVP_PKEY_CTX_ctrl_str`(EVP_PKEY_CTX *ctx, const char *type, const char *value);

int
`EVP_PKEY_CTX_set_signature_md`(EVP_PKEY_CTX *ctx, const EVP_MD *md);

int
`EVP_PKEY_CTX_get_signature_md`(EVP_PKEY_CTX *ctx, const EVP_MD **pmd);

`#include <openssl/dsa.h>`

int
`EVP_PKEY_CTX_set_dsa_paramgen_bits`(EVP_PKEY_CTX *ctx, int nbits);

`#include <openssl/dh.h>`

int
`EVP_PKEY_CTX_set_dh_paramgen_prime_len`(EVP_PKEY_CTX *ctx, int len);

int
`EVP_PKEY_CTX_set_dh_paramgen_generator`(EVP_PKEY_CTX *ctx, int gen);

`#include <openssl/ec.h>`

int
`EVP_PKEY_CTX_set_ec_paramgen_curve_nid`(EVP_PKEY_CTX *ctx, int nid); int
`EVP_PKEY_CTX_set_ec_param_enc`(EVP_PKEY_CTX *ctx, int param_enc);

int
`EVP_PKEY_CTX_set_ecdh_cofactor_mode`(EVP_PKEY_CTX *ctx, int cofactor_mode);

int
`EVP_PKEY_CTX_get_ecdh_cofactor_mode`(EVP_PKEY_CTX *ctx);

int
`EVP_PKEY_CTX_set_ecdh_kdf_type`(EVP_PKEY_CTX *ctx, int kdf);

int
`EVP_PKEY_CTX_get_ecdh_kdf_type`(EVP_PKEY_CTX *ctx);

int
`EVP_PKEY_CTX_set_ecdh_kdf_md`(EVP_PKEY_CTX *ctx, const EVP_MD *md);

int
`EVP_PKEY_CTX_get_ecdh_kdf_md`(EVP_PKEY_CTX *ctx, const EVP_MD **pmd);

int
`EVP_PKEY_CTX_set_ecdh_kdf_outlen`(EVP_PKEY_CTX *ctx, int len);

int
`EVP_PKEY_CTX_get_ecdh_kdf_outlen`(EVP_PKEY_CTX *ctx, int *plen);

int
`EVP_PKEY_CTX_set0_ecdh_kdf_ukm`(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len);

int
`EVP_PKEY_CTX_get0_ecdh_kdf_ukm`(EVP_PKEY_CTX *ctx, unsigned char **pukm);

int
`EVP_PKEY_CTX_set1_id`(EVP_PKEY_CTX *ctx, void *id, size_t id_len);

int
`EVP_PKEY_CTX_get1_id`(EVP_PKEY_CTX *ctx, void *id);

int
`EVP_PKEY_CTX_get1_id_len`(EVP_PKEY_CTX *ctx, size_t *pid_len);

# DESCRIPTION

The function `EVP_PKEY_CTX_ctrl`() sends a control operation to the context ctx. The key type used must match keytype if it is not -1. The parameter optype is a mask indicating which operations the control can be applied to. The control command is indicated in cmd and any additional arguments in p1 and p2.

Applications will not normally call `EVP_PKEY_CTX_ctrl`() directly but will instead call one of the algorithm specific macros described below and in RSA_pkey_ctx_ctrl(3).

The function `EVP_PKEY_CTX_ctrl_str`() allows an application to send an algorithm specific control operation to a context ctx in string form. This is intended to be used for options specified on the command line or in text files. The commands supported are documented in the openssl(1) utility command line pages for the option `-pkeyopt` which is supported by the `pkeyutl`, `genpkey`, and `req` commands.

All the remaining "functions" are implemented as macros.

The `EVP_PKEY_CTX_set_signature_md`() and `EVP_PKEY_CTX_get_signature_md`() macros set and get the message digest type used in a signature. They can be used with the RSA, DSA, and ECDSA algorithms. If the key is of the type `EVP_PKEY_RSA_PSS` and has usage restrictions, an error occurs if an attempt is made to set the digest to anything other than the restricted value.

These two macros expand to `EVP_PKEY_CTX_ctrl`() with an optype of `EVP_PKEY_OP_TYPE_SIG` and the following command arguments:

cmd constant | corresponding macro
`EVP_PKEY_CTRL_MD` | `EVP_PKEY_CTX_set_signature_md`()
`EVP_PKEY_CTRL_GET_MD` | `EVP_PKEY_CTX_get_signature_md`()

## DSA parameters

The macro `EVP_PKEY_CTX_set_dsa_paramgen_bits`() sets the number of bits used for DSA parameter generation to nbits. If not specified, 1024 is used.

## DH parameters

The macro `EVP_PKEY_CTX_set_dh_paramgen_prime_len`() sets the length of the DH prime parameter len for DH parameter generation. It only accepts lengths greater than or equal to 256. If this macro is not called, then 1024 is used.

The `EVP_PKEY_CTX_set_dh_paramgen_generator`() macro sets DH generator to gen for DH parameter generation. If not specified, 2 is used.

## EC parameters

The `EVP_PKEY_CTX_set_ec_paramgen_curve_nid`() macro sets the EC curve for EC parameter generation to nid. For EC parameter generation, this macro must be called or an error occurs because there is no default curve.

The `EVP_PKEY_CTX_set_ec_param_enc`() macro sets the EC parameter encoding to param_enc when generating EC parameters or an EC key. The encoding can be set to 0 for explicit parameters or to `OPENSSL_EC_NAMED_CURVE` to use named curve form.

## ECDH parameters

The `EVP_PKEY_CTX_set_ecdh_cofactor_mode`() macro sets the cofactor mode to cofactor_mode for ECDH key derivation. Possible values are 1 to enable cofactor key derivation, 0 to disable it, or -1 to clear the stored cofactor mode and fall back to the private key cofactor mode.

The `EVP_PKEY_CTX_get_ecdh_cofactor_mode`() macro returns the cofactor mode for ctx used for ECDH key derivation. Possible return values are 1 when cofactor key derivation is enabled or 0 otherwise.

## ECDH key derivation function parameters

The `EVP_PKEY_CTX_set_ecdh_kdf_type`() macro sets the key derivation function type to kdf for ECDH key derivation. Possible values are `EVP_PKEY_ECDH_KDF_NONE` or `EVP_PKEY_ECDH_KDF_X9_63` which uses the key derivation specified in X9.63. When using key derivation, the kdf_md and kdf_outlen parameters must also be specified.

The `EVP_PKEY_CTX_get_ecdh_kdf_type`() macro returns the key derivation function type for ctx used for ECDH key derivation. Possible return values are `EVP_PKEY_ECDH_KDF_NONE` or `EVP_PKEY_ECDH_KDF_X9_63`.

The `EVP_PKEY_CTX_set_ecdh_kdf_md`() macro sets the key derivation function message digest to md for ECDH key derivation. Note that X9.63 specifies that this digest should be SHA-1, but OpenSSL tolerates other digests.

The `EVP_PKEY_CTX_get_ecdh_kdf_md`() macro gets the key derivation function message digest for ctx used for ECDH key derivation.

The `EVP_PKEY_CTX_set_ecdh_kdf_outlen`() macro sets the key derivation function output length to len for ECDH key derivation.

The `EVP_PKEY_CTX_get_ecdh_kdf_outlen`() macro gets the key derivation function output length for ctx used for ECDH key derivation.

The `EVP_PKEY_CTX_set0_ecdh_kdf_ukm`() macro sets the user key material to ukm for ECDH key derivation. This parameter is optional and corresponds to the shared info in X9.63 terms. The library takes ownership of the user key material, so the caller should not free the original memory pointed to by ukm.

The `EVP_PKEY_CTX_get0_ecdh_kdf_ukm`() macro gets the user key material for ctx. The return value is the user key material length. The resulting pointer is owned by the library and should not be freed by the caller.

## CMAC parameters

Application programs normally implement CMAC as described in EVP_PKEY_new_CMAC_key(3) and do not need the control commands documented here.

Alternatively, the call to EVP_PKEY_new_CMAC_key(3) can be replaced as follows, leaving the rest of the example code given there unchanged:

1. Create an empty EVP_PKEY_CTX object by passing the `EVP_PKEY_CMAC` constant to EVP_PKEY_CTX_new_id(3).
2. Initialize it with EVP_PKEY_keygen_init(3).
3. Select the block cipher by calling `EVP_PKEY_CTX_ctrl`() with an optype of `EVP_PKEY_OP_KEYGEN`, a cmd of `EVP_PKEY_CTRL_CIPHER`, and p2 pointing to an EVP_CIPHER object, which can be obtained from the functions in the CIPHER LISTING in EVP_EncryptInit(3). The p1 argument is ignored; passing 0 is recommended.
4. Call `EVP_PKEY_CTX_ctrl`() again with an optype of `EVP_PKEY_OP_KEYGEN`, a cmd of `EVP_PKEY_CTRL_SET_MAC_KEY`, p2 pointing to the symmetric key, and p1 specifying the length of the symmetric key in bytes.
5. Extract the desired EVP_PKEY object using EVP_PKEY_keygen(3), making sure the ppkey argument points to a storage location containing a `NULL` pointer.
6. Proceed with EVP_MD_CTX_new(3), EVP_DigestSignInit(3), and EVP_DigestSign(3) as usual.

## HMAC parameters

Application programs normally implement HMAC as described in EVP_PKEY_new_raw_private_key(3). While it is possible to instead use `EVP_PKEY_CTRL_SET_MAC_KEY` directly, similar to the above description for CMAC, that is strongly discouraged. It's essentially what the deprecated function EVP_PKEY_new_mac_key(3) does internally, and compared to the direct approach with EVP_PKEY_new_raw_private_key(3), it requires a lot of cumbersome and unnecessary work.

## Other parameters

The `EVP_PKEY_CTX_set1_id`(), `EVP_PKEY_CTX_get1_id`(), and `EVP_PKEY_CTX_get1_id_len`() macros manipulate a special identifier field used for some specific signature algorithms such as SM2. The `EVP_PKEY_set1_id`() macro sets the ID to a copy of id with the length id_len. The caller can safely free the original memory pointed to by id. The `EVP_PKEY_CTX_get1_id_len`() macro returns the length of the ID set via a previous call to `EVP_PKEY_set1_id`(). That length is typically used to allocate memory for a subsequent call to `EVP_PKEY_CTX_get1_id`(), which copies the previously set ID into *id. The caller is responsible for allocating sufficient memory for id before calling `EVP_PKEY_CTX_get1_id`().

# RETURN VALUES

`EVP_PKEY_CTX_ctrl`() and its macros return a positive value for success and 0 or a negative value for failure. In particular, a return value of -2 indicates the operation is not supported by the public key algorithm.

# SEE ALSO

DH_new(3), EVP_DigestInit(3), EVP_PKEY_CTX_new(3), EVP_PKEY_decrypt(3), EVP_PKEY_derive(3), EVP_PKEY_encrypt(3), EVP_PKEY_get_default_digest_nid(3), EVP_PKEY_keygen(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), EVP_PKEY_verify_recover(3), RSA_pkey_ctx_ctrl(3)

# HISTORY

The functions `EVP_PKEY_CTX_ctrl`(), `EVP_PKEY_CTX_ctrl_str`(), `EVP_PKEY_CTX_set_signature_md`(), `EVP_PKEY_CTX_set_dsa_paramgen_bits`(), `EVP_PKEY_CTX_set_dh_paramgen_prime_len`(), `EVP_PKEY_CTX_set_dh_paramgen_generator`(), and `EVP_PKEY_CTX_set_ec_paramgen_curve_nid`() first appeared in OpenSSL 1.0.0 and have been available since OpenBSD 4.9.

The functions `EVP_PKEY_CTX_get_signature_md`(), `EVP_PKEY_CTX_set_ec_param_enc`(), `EVP_PKEY_CTX_set_ecdh_cofactor_mode`(), `EVP_PKEY_CTX_get_ecdh_cofactor_mode`(), `EVP_PKEY_CTX_set_ecdh_kdf_type`(), `EVP_PKEY_CTX_get_ecdh_kdf_type`(), `EVP_PKEY_CTX_set_ecdh_kdf_md`(), `EVP_PKEY_CTX_get_ecdh_kdf_md`(), `EVP_PKEY_CTX_set_ecdh_kdf_outlen`(), `EVP_PKEY_CTX_get_ecdh_kdf_outlen`(), `EVP_PKEY_CTX_set0_ecdh_kdf_ukm`(), and `EVP_PKEY_CTX_get0_ecdh_kdf_ukm`() first appeared in OpenSSL 1.0.2 and have been available since OpenBSD 6.6.

The functions `EVP_PKEY_CTX_set1_id`(), `EVP_PKEY_CTX_get1_id`(), and `EVP_PKEY_CTX_get1_id_len`() first appeared in OpenSSL 1.1.1 and have been available since OpenBSD 6.6.

June 8, 2025 | Debian