Sortix cross-volatile manual

This manual documents Sortix cross-volatile. You can instead view this document in the latest official manual.

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:

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

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.