Sortix nightly manual
This manual documents Sortix nightly, a development build that has not been officially released. You can instead view this document in the latest official manual.
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
#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 functionEVP_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.
DSA parameters
The macroEVP_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 macroEVP_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
TheEVP_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
TheEVP_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
TheEVP_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.
Other parameters
TheEVP_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_meth_set_ctrl(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), EVP_PKEY_verify_recover(3), RSA_pkey_ctx_ctrl(3)HISTORY
The functionsEVP_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 1, 2019 | Debian |