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
#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 SHA1, 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:
- Create an empty EVP_PKEY_CTX object by passing the
EVP_PKEY_CMAC
constant to EVP_PKEY_CTX_new_id(3). - Initialize it with EVP_PKEY_keygen_init(3).
- Select the block cipher by calling
EVP_PKEY_CTX_ctrl
() with an optype ofEVP_PKEY_OP_KEYGEN
, a cmd ofEVP_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. - Call
EVP_PKEY_CTX_ctrl
() again with an optype ofEVP_PKEY_OP_KEYGEN
, a cmd ofEVP_PKEY_CTRL_SET_MAC_KEY
, p2 pointing to the symmetric key, and p1 specifying the length of the symmetric key in bytes. - 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. - 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.