OpenBSD manual page server

Manual Page Search Parameters
EVP_PKEY_CTX_CTRL(3) Library Functions Manual EVP_PKEY_CTX_CTRL(3)

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

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

The function () 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 () directly but will instead call one of the algorithm specific macros described below and in RSA_pkey_ctx_ctrl(3).

The function () 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 () and () 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 () with an optype of EVP_PKEY_OP_TYPE_SIG and the following command arguments:

cmd constant corresponding macro
()
()

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

The macro () 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 () macro sets DH generator to gen for DH parameter generation. If not specified, 2 is used.

The () 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 () 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.

The () 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 () 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.

The () 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 () 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 () macro sets the key derivation function message digest to md for ECDH key derivation. Note that X9.63 specifies that this digest should be SHA1, but OpenSSL tolerates other digests.

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

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

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

The () 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 () 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.

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

The (), (), and () macros manipulate a special identifier field used for some specific signature algorithms such as SM2. The () 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().

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.

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_meth_set_ctrl(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), EVP_PKEY_verify_recover(3), RSA_pkey_ctx_ctrl(3)

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.

November 24, 2024 OpenBSD-current