1=pod 2 3=head1 NAME 4 5EVP_PKEY_CTX_ctrl, 6EVP_PKEY_CTX_ctrl_str, 7EVP_PKEY_CTX_ctrl_uint64, 8EVP_PKEY_CTX_md, 9EVP_PKEY_CTX_set_signature_md, 10EVP_PKEY_CTX_get_signature_md, 11EVP_PKEY_CTX_set_mac_key, 12EVP_PKEY_CTX_set_group_name, 13EVP_PKEY_CTX_get_group_name, 14EVP_PKEY_CTX_set_rsa_padding, 15EVP_PKEY_CTX_get_rsa_padding, 16EVP_PKEY_CTX_set_rsa_pss_saltlen, 17EVP_PKEY_CTX_get_rsa_pss_saltlen, 18EVP_PKEY_CTX_set_rsa_keygen_bits, 19EVP_PKEY_CTX_set_rsa_keygen_pubexp, 20EVP_PKEY_CTX_set1_rsa_keygen_pubexp, 21EVP_PKEY_CTX_set_rsa_keygen_primes, 22EVP_PKEY_CTX_set_rsa_mgf1_md_name, 23EVP_PKEY_CTX_set_rsa_mgf1_md, 24EVP_PKEY_CTX_get_rsa_mgf1_md, 25EVP_PKEY_CTX_get_rsa_mgf1_md_name, 26EVP_PKEY_CTX_set_rsa_oaep_md_name, 27EVP_PKEY_CTX_set_rsa_oaep_md, 28EVP_PKEY_CTX_get_rsa_oaep_md, 29EVP_PKEY_CTX_get_rsa_oaep_md_name, 30EVP_PKEY_CTX_set0_rsa_oaep_label, 31EVP_PKEY_CTX_get0_rsa_oaep_label, 32EVP_PKEY_CTX_set_dsa_paramgen_bits, 33EVP_PKEY_CTX_set_dsa_paramgen_q_bits, 34EVP_PKEY_CTX_set_dsa_paramgen_md, 35EVP_PKEY_CTX_set_dsa_paramgen_md_props, 36EVP_PKEY_CTX_set_dsa_paramgen_gindex, 37EVP_PKEY_CTX_set_dsa_paramgen_type, 38EVP_PKEY_CTX_set_dsa_paramgen_seed, 39EVP_PKEY_CTX_set_dh_paramgen_prime_len, 40EVP_PKEY_CTX_set_dh_paramgen_subprime_len, 41EVP_PKEY_CTX_set_dh_paramgen_generator, 42EVP_PKEY_CTX_set_dh_paramgen_type, 43EVP_PKEY_CTX_set_dh_paramgen_gindex, 44EVP_PKEY_CTX_set_dh_paramgen_seed, 45EVP_PKEY_CTX_set_dh_rfc5114, 46EVP_PKEY_CTX_set_dhx_rfc5114, 47EVP_PKEY_CTX_set_dh_pad, 48EVP_PKEY_CTX_set_dh_nid, 49EVP_PKEY_CTX_set_dh_kdf_type, 50EVP_PKEY_CTX_get_dh_kdf_type, 51EVP_PKEY_CTX_set0_dh_kdf_oid, 52EVP_PKEY_CTX_get0_dh_kdf_oid, 53EVP_PKEY_CTX_set_dh_kdf_md, 54EVP_PKEY_CTX_get_dh_kdf_md, 55EVP_PKEY_CTX_set_dh_kdf_outlen, 56EVP_PKEY_CTX_get_dh_kdf_outlen, 57EVP_PKEY_CTX_set0_dh_kdf_ukm, 58EVP_PKEY_CTX_get0_dh_kdf_ukm, 59EVP_PKEY_CTX_set_ec_paramgen_curve_nid, 60EVP_PKEY_CTX_set_ec_param_enc, 61EVP_PKEY_CTX_set_ecdh_cofactor_mode, 62EVP_PKEY_CTX_get_ecdh_cofactor_mode, 63EVP_PKEY_CTX_set_ecdh_kdf_type, 64EVP_PKEY_CTX_get_ecdh_kdf_type, 65EVP_PKEY_CTX_set_ecdh_kdf_md, 66EVP_PKEY_CTX_get_ecdh_kdf_md, 67EVP_PKEY_CTX_set_ecdh_kdf_outlen, 68EVP_PKEY_CTX_get_ecdh_kdf_outlen, 69EVP_PKEY_CTX_set0_ecdh_kdf_ukm, 70EVP_PKEY_CTX_get0_ecdh_kdf_ukm, 71EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len, 72EVP_PKEY_CTX_set_kem_op 73- algorithm specific control operations 74 75=head1 SYNOPSIS 76 77 #include <openssl/evp.h> 78 79 int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, 80 int cmd, int p1, void *p2); 81 int EVP_PKEY_CTX_ctrl_uint64(EVP_PKEY_CTX *ctx, int keytype, int optype, 82 int cmd, uint64_t value); 83 int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type, 84 const char *value); 85 86 int EVP_PKEY_CTX_md(EVP_PKEY_CTX *ctx, int optype, int cmd, const char *md); 87 88 int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); 89 int EVP_PKEY_CTX_get_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD **pmd); 90 91 int EVP_PKEY_CTX_set_mac_key(EVP_PKEY_CTX *ctx, const unsigned char *key, 92 int len); 93 int EVP_PKEY_CTX_set_group_name(EVP_PKEY_CTX *ctx, const char *name); 94 int EVP_PKEY_CTX_get_group_name(EVP_PKEY_CTX *ctx, char *name, size_t namelen); 95 96 int EVP_PKEY_CTX_set_kem_op(EVP_PKEY_CTX *ctx, const char *op); 97 98 #include <openssl/rsa.h> 99 100 int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad); 101 int EVP_PKEY_CTX_get_rsa_padding(EVP_PKEY_CTX *ctx, int *pad); 102 int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int saltlen); 103 int EVP_PKEY_CTX_get_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int *saltlen); 104 int EVP_PKEY_CTX_set_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits); 105 int EVP_PKEY_CTX_set1_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp); 106 int EVP_PKEY_CTX_set_rsa_keygen_primes(EVP_PKEY_CTX *ctx, int primes); 107 int EVP_PKEY_CTX_set_rsa_mgf1_md_name(EVP_PKEY_CTX *ctx, const char *mdname, 108 const char *mdprops); 109 int EVP_PKEY_CTX_set_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); 110 int EVP_PKEY_CTX_get_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); 111 int EVP_PKEY_CTX_get_rsa_mgf1_md_name(EVP_PKEY_CTX *ctx, char *name, 112 size_t namelen); 113 int EVP_PKEY_CTX_set_rsa_oaep_md_name(EVP_PKEY_CTX *ctx, const char *mdname, 114 const char *mdprops); 115 int EVP_PKEY_CTX_set_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); 116 int EVP_PKEY_CTX_get_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); 117 int EVP_PKEY_CTX_get_rsa_oaep_md_name(EVP_PKEY_CTX *ctx, char *name, 118 size_t namelen); 119 int EVP_PKEY_CTX_set0_rsa_oaep_label(EVP_PKEY_CTX *ctx, void *label, 120 int len); 121 int EVP_PKEY_CTX_get0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char **label); 122 123 #include <openssl/dsa.h> 124 125 int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits); 126 int EVP_PKEY_CTX_set_dsa_paramgen_q_bits(EVP_PKEY_CTX *ctx, int qbits); 127 int EVP_PKEY_CTX_set_dsa_paramgen_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); 128 int EVP_PKEY_CTX_set_dsa_paramgen_md_props(EVP_PKEY_CTX *ctx, 129 const char *md_name, 130 const char *md_properties); 131 int EVP_PKEY_CTX_set_dsa_paramgen_type(EVP_PKEY_CTX *ctx, const char *name); 132 int EVP_PKEY_CTX_set_dsa_paramgen_gindex(EVP_PKEY_CTX *ctx, int gindex); 133 int EVP_PKEY_CTX_set_dsa_paramgen_seed(EVP_PKEY_CTX *ctx, 134 const unsigned char *seed, 135 size_t seedlen); 136 137 #include <openssl/dh.h> 138 139 int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len); 140 int EVP_PKEY_CTX_set_dh_paramgen_subprime_len(EVP_PKEY_CTX *ctx, int len); 141 int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen); 142 int EVP_PKEY_CTX_set_dh_paramgen_type(EVP_PKEY_CTX *ctx, int type); 143 int EVP_PKEY_CTX_set_dh_pad(EVP_PKEY_CTX *ctx, int pad); 144 int EVP_PKEY_CTX_set_dh_nid(EVP_PKEY_CTX *ctx, int nid); 145 int EVP_PKEY_CTX_set_dh_rfc5114(EVP_PKEY_CTX *ctx, int rfc5114); 146 int EVP_PKEY_CTX_set_dhx_rfc5114(EVP_PKEY_CTX *ctx, int rfc5114); 147 int EVP_PKEY_CTX_set_dh_paramgen_gindex(EVP_PKEY_CTX *ctx, int gindex); 148 int EVP_PKEY_CTX_set_dh_paramgen_seed(EVP_PKEY_CTX *ctx, 149 const unsigned char *seed, 150 size_t seedlen); 151 int EVP_PKEY_CTX_set_dh_kdf_type(EVP_PKEY_CTX *ctx, int kdf); 152 int EVP_PKEY_CTX_get_dh_kdf_type(EVP_PKEY_CTX *ctx); 153 int EVP_PKEY_CTX_set0_dh_kdf_oid(EVP_PKEY_CTX *ctx, ASN1_OBJECT *oid); 154 int EVP_PKEY_CTX_get0_dh_kdf_oid(EVP_PKEY_CTX *ctx, ASN1_OBJECT **oid); 155 int EVP_PKEY_CTX_set_dh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); 156 int EVP_PKEY_CTX_get_dh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); 157 int EVP_PKEY_CTX_set_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int len); 158 int EVP_PKEY_CTX_get_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len); 159 int EVP_PKEY_CTX_set0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len); 160 161 #include <openssl/ec.h> 162 163 int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid); 164 int EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, int param_enc); 165 int EVP_PKEY_CTX_set_ecdh_cofactor_mode(EVP_PKEY_CTX *ctx, int cofactor_mode); 166 int EVP_PKEY_CTX_get_ecdh_cofactor_mode(EVP_PKEY_CTX *ctx); 167 int EVP_PKEY_CTX_set_ecdh_kdf_type(EVP_PKEY_CTX *ctx, int kdf); 168 int EVP_PKEY_CTX_get_ecdh_kdf_type(EVP_PKEY_CTX *ctx); 169 int EVP_PKEY_CTX_set_ecdh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); 170 int EVP_PKEY_CTX_get_ecdh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD **md); 171 int EVP_PKEY_CTX_set_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int len); 172 int EVP_PKEY_CTX_get_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len); 173 int EVP_PKEY_CTX_set0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len); 174 175 int EVP_PKEY_CTX_set1_id(EVP_PKEY_CTX *ctx, void *id, size_t id_len); 176 int EVP_PKEY_CTX_get1_id(EVP_PKEY_CTX *ctx, void *id); 177 int EVP_PKEY_CTX_get1_id_len(EVP_PKEY_CTX *ctx, size_t *id_len); 178 179The following functions have been deprecated since OpenSSL 3.0, and can be 180hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, 181see L<openssl_user_macros(7)>: 182 183 #include <openssl/rsa.h> 184 185 int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp); 186 187 #include <openssl/dh.h> 188 189 int EVP_PKEY_CTX_get0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm); 190 191 #include <openssl/ec.h> 192 193 int EVP_PKEY_CTX_get0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm); 194 195=head1 DESCRIPTION 196 197EVP_PKEY_CTX_ctrl() sends a control operation to the context I<ctx>. The key 198type used must match I<keytype> if it is not -1. The parameter I<optype> is a 199mask indicating which operations the control can be applied to. 200The control command is indicated in I<cmd> and any additional arguments in 201I<p1> and I<p2>. 202 203For I<cmd> = B<EVP_PKEY_CTRL_SET_MAC_KEY>, I<p1> is the length of the MAC key, 204and I<p2> is the MAC key. This is used by Poly1305, SipHash, HMAC and CMAC. 205 206Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will 207instead call one of the algorithm specific functions below. 208 209EVP_PKEY_CTX_ctrl_uint64() is a wrapper that directly passes a 210uint64 value as I<p2> to EVP_PKEY_CTX_ctrl(). 211 212EVP_PKEY_CTX_ctrl_str() allows an application to send an algorithm 213specific control operation to a context I<ctx> in string form. This is 214intended to be used for options specified on the command line or in text 215files. The commands supported are documented in the openssl utility 216command line pages for the option I<-pkeyopt> which is supported by the 217I<pkeyutl>, I<genpkey> and I<req> commands. 218 219EVP_PKEY_CTX_md() sends a message digest control operation to the context 220I<ctx>. The message digest is specified by its name I<md>. 221 222EVP_PKEY_CTX_set_signature_md() sets the message digest type used 223in a signature. It can be used in the RSA, DSA and ECDSA algorithms. 224 225EVP_PKEY_CTX_get_signature_md()gets the message digest type used 226in a signature. It can be used in the RSA, DSA and ECDSA algorithms. 227 228Key generation typically involves setting up parameters to be used and 229generating the private and public key data. Some algorithm implementations 230allow private key data to be set explicitly using EVP_PKEY_CTX_set_mac_key(). 231In this case key generation is simply the process of setting up the 232parameters for the key and then setting the raw key data to the value explicitly. 233Normally applications would call L<EVP_PKEY_new_raw_private_key(3)> or similar 234functions instead. 235 236EVP_PKEY_CTX_set_mac_key() can be used with any of the algorithms supported by 237the L<EVP_PKEY_new_raw_private_key(3)> function. 238 239EVP_PKEY_CTX_set_group_name() sets the group name to I<name> for parameter and 240key generation. For example for EC keys this will set the curve name and for 241DH keys it will set the name of the finite field group. 242 243EVP_PKEY_CTX_get_group_name() finds the group name that's currently 244set with I<ctx>, and writes it to the location that I<name> points at, as long 245as its size I<namelen> is large enough to store that name, including a 246terminating NUL byte. 247 248=head2 RSA parameters 249 250EVP_PKEY_CTX_set_rsa_padding() sets the RSA padding mode for I<ctx>. 251The I<pad> parameter can take the value B<RSA_PKCS1_PADDING> for PKCS#1 252padding, B<RSA_NO_PADDING> for 253no padding, B<RSA_PKCS1_OAEP_PADDING> for OAEP padding (encrypt and 254decrypt only), B<RSA_X931_PADDING> for X9.31 padding (signature operations 255only), B<RSA_PKCS1_PSS_PADDING> (sign and verify only) and 256B<RSA_PKCS1_WITH_TLS_PADDING> for TLS RSA ClientKeyExchange message padding 257(decryption only). 258 259Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md() 260is used. If this function is called for PKCS#1 padding the plaintext buffer is 261an actual digest value and is encapsulated in a DigestInfo structure according 262to PKCS#1 when signing and this structure is expected (and stripped off) when 263verifying. If this control is not used with RSA and PKCS#1 padding then the 264supplied data is used directly and not encapsulated. In the case of X9.31 265padding for RSA the algorithm identifier byte is added or checked and removed 266if this control is called. If it is not called then the first byte of the plaintext 267buffer is expected to be the algorithm identifier byte. 268 269EVP_PKEY_CTX_get_rsa_padding() gets the RSA padding mode for I<ctx>. 270 271EVP_PKEY_CTX_set_rsa_pss_saltlen() sets the RSA PSS salt length to I<saltlen>. 272As its name implies it is only supported for PSS padding. If this function is 273not called then the salt length is maximized up to the digest length when 274signing and auto detection when verifying. Four special values are supported: 275 276=over 4 277 278=item B<RSA_PSS_SALTLEN_DIGEST> 279 280sets the salt length to the digest length. 281 282=item B<RSA_PSS_SALTLEN_MAX> 283 284sets the salt length to the maximum permissible value. 285 286=item B<RSA_PSS_SALTLEN_AUTO> 287 288causes the salt length to be automatically determined based on the 289B<PSS> block structure when verifying. When signing, it has the same 290meaning as B<RSA_PSS_SALTLEN_MAX>. 291 292=item B<RSA_PSS_SALTLEN_AUTO_DIGEST_MAX> 293 294causes the salt length to be automatically determined based on the B<PSS> block 295structure when verifying, like B<RSA_PSS_SALTLEN_AUTO>. When signing, the salt 296length is maximized up to a maximum of the digest length to comply with FIPS 297186-4 section 5.5. 298 299=back 300 301EVP_PKEY_CTX_get_rsa_pss_saltlen() gets the RSA PSS salt length for I<ctx>. 302The padding mode must already have been set to B<RSA_PKCS1_PSS_PADDING>. 303 304EVP_PKEY_CTX_set_rsa_keygen_bits() sets the RSA key length for 305RSA key generation to I<bits>. If not specified 2048 bits is used. 306 307EVP_PKEY_CTX_set1_rsa_keygen_pubexp() sets the public exponent value for RSA key 308generation to the value stored in I<pubexp>. Currently it should be an odd 309integer. In accordance with the OpenSSL naming convention, the I<pubexp> pointer 310must be freed independently of the EVP_PKEY_CTX (ie, it is internally copied). 311If not specified 65537 is used. 312 313EVP_PKEY_CTX_set_rsa_keygen_pubexp() does the same as 314EVP_PKEY_CTX_set1_rsa_keygen_pubexp() except that there is no internal copy and 315therefore I<pubexp> should not be modified or freed after the call. 316 317EVP_PKEY_CTX_set_rsa_keygen_primes() sets the number of primes for 318RSA key generation to I<primes>. If not specified 2 is used. 319 320EVP_PKEY_CTX_set_rsa_mgf1_md_name() sets the MGF1 digest for RSA 321padding schemes to the digest named I<mdname>. If the RSA algorithm 322implementation for the selected provider supports it then the digest will be 323fetched using the properties I<mdprops>. If not explicitly set the signing 324digest is used. The padding mode must have been set to B<RSA_PKCS1_OAEP_PADDING> 325or B<RSA_PKCS1_PSS_PADDING>. 326 327EVP_PKEY_CTX_set_rsa_mgf1_md() does the same as 328EVP_PKEY_CTX_set_rsa_mgf1_md_name() except that the name of the digest is 329inferred from the supplied I<md> and it is not possible to specify any 330properties. 331 332EVP_PKEY_CTX_get_rsa_mgf1_md_name() gets the name of the MGF1 333digest algorithm for I<ctx>. If not explicitly set the signing digest is used. 334The padding mode must have been set to B<RSA_PKCS1_OAEP_PADDING> or 335B<RSA_PKCS1_PSS_PADDING>. 336 337EVP_PKEY_CTX_get_rsa_mgf1_md() does the same as 338EVP_PKEY_CTX_get_rsa_mgf1_md_name() except that it returns a pointer to an 339EVP_MD object instead. Note that only known, built-in EVP_MD objects will be 340returned. The EVP_MD object may be NULL if the digest is not one of these (such 341as a digest only implemented in a third party provider). 342 343EVP_PKEY_CTX_set_rsa_oaep_md_name() sets the message digest type 344used in RSA OAEP to the digest named I<mdname>. If the RSA algorithm 345implementation for the selected provider supports it then the digest will be 346fetched using the properties I<mdprops>. The padding mode must have been set to 347B<RSA_PKCS1_OAEP_PADDING>. 348 349EVP_PKEY_CTX_set_rsa_oaep_md() does the same as 350EVP_PKEY_CTX_set_rsa_oaep_md_name() except that the name of the digest is 351inferred from the supplied I<md> and it is not possible to specify any 352properties. 353 354EVP_PKEY_CTX_get_rsa_oaep_md_name() gets the message digest 355algorithm name used in RSA OAEP and stores it in the buffer I<name> which is of 356size I<namelen>. The padding mode must have been set to 357B<RSA_PKCS1_OAEP_PADDING>. The buffer should be sufficiently large for any 358expected digest algorithm names or the function will fail. 359 360EVP_PKEY_CTX_get_rsa_oaep_md() does the same as 361EVP_PKEY_CTX_get_rsa_oaep_md_name() except that it returns a pointer to an 362EVP_MD object instead. Note that only known, built-in EVP_MD objects will be 363returned. The EVP_MD object may be NULL if the digest is not one of these (such 364as a digest only implemented in a third party provider). 365 366EVP_PKEY_CTX_set0_rsa_oaep_label() sets the RSA OAEP label to binary data 367I<label> and its length in bytes to I<len>. If I<label> is NULL or I<len> is 0, 368the label is cleared. The library takes ownership of the label so the 369caller should not free the original memory pointed to by I<label>. 370The padding mode must have been set to B<RSA_PKCS1_OAEP_PADDING>. 371 372EVP_PKEY_CTX_get0_rsa_oaep_label() gets the RSA OAEP label to 373I<label>. The return value is the label length. The padding mode 374must have been set to B<RSA_PKCS1_OAEP_PADDING>. The resulting pointer is owned 375by the library and should not be freed by the caller. 376 377B<RSA_PKCS1_WITH_TLS_PADDING> is used when decrypting an RSA encrypted TLS 378pre-master secret in a TLS ClientKeyExchange message. It is the same as 379RSA_PKCS1_PADDING except that it additionally verifies that the result is the 380correct length and the first two bytes are the protocol version initially 381requested by the client. If the encrypted content is publicly invalid then the 382decryption will fail. However, if the padding checks fail then decryption will 383still appear to succeed but a random TLS premaster secret will be returned 384instead. This padding mode accepts two parameters which can be set using the 385L<EVP_PKEY_CTX_set_params(3)> function. These are 386OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION and 387OSSL_ASYM_CIPHER_PARAM_TLS_NEGOTIATED_VERSION, both of which are expected to be 388unsigned integers. Normally only the first of these will be set and represents 389the TLS protocol version that was first requested by the client (e.g. 0x0303 for 390TLSv1.2, 0x0302 for TLSv1.1 etc). Historically some buggy clients would use the 391negotiated protocol version instead of the protocol version first requested. If 392this behaviour should be tolerated then 393OSSL_ASYM_CIPHER_PARAM_TLS_NEGOTIATED_VERSION should be set to the actual 394negotiated protocol version. Otherwise it should be left unset. 395 396Similarly to the B<RSA_PKCS1_WITH_TLS_PADDING> above, since OpenSSL version 3973.2.0, the use of B<RSA_PKCS1_PADDING> will return a randomly generated message 398instead of padding errors in case padding checks fail. Applications that 399want to remain secure while using earlier versions of OpenSSL, or a provider 400that doesn't implement the implicit rejection mechanism, still need to 401handle both the error code from the RSA decryption operation and the 402returned message in a side channel secure manner. 403This protection against Bleichenbacher attacks can be disabled by setting 404B<OSSL_ASYM_CIPHER_PARAM_IMPLICIT_REJECTION> (an unsigned integer) to 0. 405 406=head2 DSA parameters 407 408EVP_PKEY_CTX_set_dsa_paramgen_bits() sets the number of bits used for DSA 409parameter generation to B<nbits>. If not specified, 2048 is used. 410 411EVP_PKEY_CTX_set_dsa_paramgen_q_bits() sets the number of bits in the subprime 412parameter I<q> for DSA parameter generation to I<qbits>. If not specified, 224 413is used. If a digest function is specified below, this parameter is ignored and 414instead, the number of bits in I<q> matches the size of the digest. 415 416EVP_PKEY_CTX_set_dsa_paramgen_md() sets the digest function used for DSA 417parameter generation to I<md>. If not specified, one of SHA-1, SHA-224, or 418SHA-256 is selected to match the bit length of I<q> above. 419 420EVP_PKEY_CTX_set_dsa_paramgen_md_props() sets the digest function used for DSA 421parameter generation using I<md_name> and I<md_properties> to retrieve the 422digest from a provider. 423If not specified, I<md_name> will be set to one of SHA-1, SHA-224, or 424SHA-256 depending on the bit length of I<q> above. I<md_properties> is a 425property query string that has a default value of '' if not specified. 426 427EVP_PKEY_CTX_set_dsa_paramgen_gindex() sets the I<gindex> used by the generator 428G. The default value is -1 which uses unverifiable g, otherwise a positive value 429uses verifiable g. This value must be saved if key validation of g is required, 430since it is not part of a persisted key. 431 432EVP_PKEY_CTX_set_dsa_paramgen_seed() sets the I<seed> to use for generation 433rather than using a randomly generated value for the seed. This is useful for 434testing purposes only and can fail if the seed does not produce primes for both 435p & q on its first iteration. This value must be saved if key validation of 436p, q, and verifiable g are required, since it is not part of a persisted key. 437 438EVP_PKEY_CTX_set_dsa_paramgen_type() sets the generation type to use FIPS186-4 439generation if I<name> is "fips186_4", or FIPS186-2 generation if I<name> is 440"fips186_2". The default value for the default provider is "fips186_2". The 441default value for the FIPS provider is "fips186_4". 442 443=head2 DH parameters 444 445EVP_PKEY_CTX_set_dh_paramgen_prime_len() sets the length of the DH prime 446parameter I<p> for DH parameter generation. If this function is not called then 4472048 is used. Only accepts lengths greater than or equal to 256. 448 449EVP_PKEY_CTX_set_dh_paramgen_subprime_len() sets the length of the DH 450optional subprime parameter I<q> for DH parameter generation. The default is 451256 if the prime is at least 2048 bits long or 160 otherwise. The DH paramgen 452type must have been set to "fips186_4". 453 454EVP_PKEY_CTX_set_dh_paramgen_generator() sets DH generator to I<gen> for DH 455parameter generation. If not specified 2 is used. 456 457EVP_PKEY_CTX_set_dh_paramgen_type() sets the key type for DH parameter 458generation. The supported parameters are: 459 460=over 4 461 462=item B<DH_PARAMGEN_TYPE_GROUP> 463 464Use a named group. If only the safe prime parameter I<p> is set this can be 465used to select a ffdhe safe prime group of the correct size. 466 467=item B<DH_PARAMGEN_TYPE_FIPS_186_4> 468 469FIPS186-4 FFC parameter generator. 470 471=item B<DH_PARAMGEN_TYPE_FIPS_186_2> 472 473FIPS186-2 FFC parameter generator (X9.42 DH). 474 475=item B<DH_PARAMGEN_TYPE_GENERATOR> 476 477Uses a safe prime generator g (PKCS#3 format). 478 479=back 480 481The default in the default provider is B<DH_PARAMGEN_TYPE_GENERATOR> for the 482"DH" keytype, and B<DH_PARAMGEN_TYPE_FIPS_186_2> for the "DHX" keytype. In the 483FIPS provider the default value is B<DH_PARAMGEN_TYPE_GROUP> for the "DH" 484keytype and <B<DH_PARAMGEN_TYPE_FIPS_186_4> for the "DHX" keytype. 485 486EVP_PKEY_CTX_set_dh_paramgen_gindex() sets the I<gindex> used by the generator G. 487The default value is -1 which uses unverifiable g, otherwise a positive value 488uses verifiable g. This value must be saved if key validation of g is required, 489since it is not part of a persisted key. 490 491EVP_PKEY_CTX_set_dh_paramgen_seed() sets the I<seed> to use for generation 492rather than using a randomly generated value for the seed. This is useful for 493testing purposes only and can fail if the seed does not produce primes for both 494p & q on its first iteration. This value must be saved if key validation of p, q, 495and verifiable g are required, since it is not part of a persisted key. 496 497EVP_PKEY_CTX_set_dh_pad() sets the DH padding mode. 498If I<pad> is 1 the shared secret is padded with zeros up to the size of the DH 499prime I<p>. 500If I<pad> is zero (the default) then no padding is performed. 501 502EVP_PKEY_CTX_set_dh_nid() sets the DH parameters to values corresponding to 503I<nid> as defined in RFC7919 or RFC3526. The I<nid> parameter must be 504B<NID_ffdhe2048>, B<NID_ffdhe3072>, B<NID_ffdhe4096>, B<NID_ffdhe6144>, 505B<NID_ffdhe8192>, B<NID_modp_1536>, B<NID_modp_2048>, B<NID_modp_3072>, 506B<NID_modp_4096>, B<NID_modp_6144>, B<NID_modp_8192> or B<NID_undef> to clear 507the stored value. This function can be called during parameter or key generation. 508The nid parameter and the rfc5114 parameter are mutually exclusive. 509 510EVP_PKEY_CTX_set_dh_rfc5114() and EVP_PKEY_CTX_set_dhx_rfc5114() both set the 511DH parameters to the values defined in RFC5114. The I<rfc5114> parameter must 512be 1, 2 or 3 corresponding to RFC5114 sections 2.1, 2.2 and 2.3. or 0 to clear 513the stored value. This macro can be called during parameter generation. The 514I<ctx> must have a key type of B<EVP_PKEY_DHX>. 515The rfc5114 parameter and the nid parameter are mutually exclusive. 516 517=head2 DH key derivation function parameters 518 519Note that all of the following functions require that the I<ctx> parameter has 520a private key type of B<EVP_PKEY_DHX>. When using key derivation, the output of 521EVP_PKEY_derive() is the output of the KDF instead of the DH shared secret. 522The KDF output is typically used as a Key Encryption Key (KEK) that in turn 523encrypts a Content Encryption Key (CEK). 524 525EVP_PKEY_CTX_set_dh_kdf_type() sets the key derivation function type to I<kdf> 526for DH key derivation. Possible values are B<EVP_PKEY_DH_KDF_NONE> and 527B<EVP_PKEY_DH_KDF_X9_42> which uses the key derivation specified in RFC2631 528(based on the keying algorithm described in X9.42). When using key derivation, 529the I<kdf_oid>, I<kdf_md> and I<kdf_outlen> parameters must also be specified. 530 531EVP_PKEY_CTX_get_dh_kdf_type() gets the key derivation function type for I<ctx> 532used for DH key derivation. Possible values are B<EVP_PKEY_DH_KDF_NONE> and 533B<EVP_PKEY_DH_KDF_X9_42>. 534 535EVP_PKEY_CTX_set0_dh_kdf_oid() sets the key derivation function object 536identifier to I<oid> for DH key derivation. This OID should identify the 537algorithm to be used with the Content Encryption Key. 538The library takes ownership of the object identifier so the caller should not 539free the original memory pointed to by I<oid>. 540 541EVP_PKEY_CTX_get0_dh_kdf_oid() gets the key derivation function oid for I<ctx> 542used for DH key derivation. The resulting pointer is owned by the library and 543should not be freed by the caller. 544 545EVP_PKEY_CTX_set_dh_kdf_md() sets the key derivation function message digest to 546I<md> for DH key derivation. Note that RFC2631 specifies that this digest should 547be SHA1 but OpenSSL tolerates other digests. 548 549EVP_PKEY_CTX_get_dh_kdf_md() gets the key derivation function message digest for 550I<ctx> used for DH key derivation. 551 552EVP_PKEY_CTX_set_dh_kdf_outlen() sets the key derivation function output length 553to I<len> for DH key derivation. 554 555EVP_PKEY_CTX_get_dh_kdf_outlen() gets the key derivation function output length 556for I<ctx> used for DH key derivation. 557 558EVP_PKEY_CTX_set0_dh_kdf_ukm() sets the user key material to I<ukm> and its 559length to I<len> for DH key derivation. This parameter is optional and 560corresponds to the partyAInfo field in RFC2631 terms. The specification 561requires that it is 512 bits long but this is not enforced by OpenSSL. 562The library takes ownership of the user key material so the caller should not 563free the original memory pointed to by I<ukm>. 564 565EVP_PKEY_CTX_get0_dh_kdf_ukm() gets the user key material for I<ctx>. 566The return value is the user key material length. The resulting pointer is owned 567by the library and should not be freed by the caller. 568 569=head2 EC parameters 570 571Use EVP_PKEY_CTX_set_group_name() (described above) to set the curve name to 572I<name> for parameter and key generation. 573 574EVP_PKEY_CTX_set_ec_paramgen_curve_nid() does the same as 575EVP_PKEY_CTX_set_group_name(), but is specific to EC and uses a I<nid> rather 576than a name string. 577 578For EC parameter generation, one of EVP_PKEY_CTX_set_group_name() 579or EVP_PKEY_CTX_set_ec_paramgen_curve_nid() must be called or an error occurs 580because there is no default curve. 581These function can also be called to set the curve explicitly when 582generating an EC key. 583 584EVP_PKEY_CTX_get_group_name() (described above) can be used to obtain the curve 585name that's currently set with I<ctx>. 586 587EVP_PKEY_CTX_set_ec_param_enc() sets the EC parameter encoding to I<param_enc> 588when generating EC parameters or an EC key. The encoding can be 589B<OPENSSL_EC_EXPLICIT_CURVE> for explicit parameters (the default in versions 590of OpenSSL before 1.1.0) or B<OPENSSL_EC_NAMED_CURVE> to use named curve form. 591For maximum compatibility the named curve form should be used. Note: the 592B<OPENSSL_EC_NAMED_CURVE> value was added in OpenSSL 1.1.0; previous 593versions should use 0 instead. 594 595=head2 ECDH parameters 596 597EVP_PKEY_CTX_set_ecdh_cofactor_mode() sets the cofactor mode to I<cofactor_mode> 598for ECDH key derivation. Possible values are 1 to enable cofactor 599key derivation, 0 to disable it and -1 to clear the stored cofactor mode and 600fallback to the private key cofactor mode. 601 602EVP_PKEY_CTX_get_ecdh_cofactor_mode() returns the cofactor mode for I<ctx> used 603for ECDH key derivation. Possible values are 1 when cofactor key derivation is 604enabled and 0 otherwise. 605 606=head2 ECDH key derivation function parameters 607 608EVP_PKEY_CTX_set_ecdh_kdf_type() sets the key derivation function type to 609I<kdf> for ECDH key derivation. Possible values are B<EVP_PKEY_ECDH_KDF_NONE> 610and B<EVP_PKEY_ECDH_KDF_X9_63> which uses the key derivation specified in X9.63. 611When using key derivation, the I<kdf_md> and I<kdf_outlen> parameters must 612also be specified. 613 614EVP_PKEY_CTX_get_ecdh_kdf_type() returns the key derivation function type for 615I<ctx> used for ECDH key derivation. Possible values are 616B<EVP_PKEY_ECDH_KDF_NONE> and B<EVP_PKEY_ECDH_KDF_X9_63>. 617 618EVP_PKEY_CTX_set_ecdh_kdf_md() sets the key derivation function message digest 619to I<md> for ECDH key derivation. Note that X9.63 specifies that this digest 620should be SHA1 but OpenSSL tolerates other digests. 621 622EVP_PKEY_CTX_get_ecdh_kdf_md() gets the key derivation function message digest 623for I<ctx> used for ECDH key derivation. 624 625EVP_PKEY_CTX_set_ecdh_kdf_outlen() sets the key derivation function output 626length to I<len> for ECDH key derivation. 627 628EVP_PKEY_CTX_get_ecdh_kdf_outlen() gets the key derivation function output 629length for I<ctx> used for ECDH key derivation. 630 631EVP_PKEY_CTX_set0_ecdh_kdf_ukm() sets the user key material to I<ukm> for ECDH 632key derivation. This parameter is optional and corresponds to the shared info in 633X9.63 terms. The library takes ownership of the user key material so the caller 634should not free the original memory pointed to by I<ukm>. 635 636EVP_PKEY_CTX_get0_ecdh_kdf_ukm() gets the user key material for I<ctx>. 637The return value is the user key material length. The resulting pointer is owned 638by the library and should not be freed by the caller. 639 640=head2 Other parameters 641 642EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and EVP_PKEY_CTX_get1_id_len() 643are used to manipulate the special identifier field for specific signature 644algorithms such as SM2. The EVP_PKEY_CTX_set1_id() sets an ID pointed by I<id> with 645the length I<id_len> to the library. The library takes a copy of the id so that 646the caller can safely free the original memory pointed to by I<id>. 647EVP_PKEY_CTX_get1_id_len() returns the length of the ID set via a previous call 648to EVP_PKEY_CTX_set1_id(). The length is usually used to allocate adequate 649memory for further calls to EVP_PKEY_CTX_get1_id(). EVP_PKEY_CTX_get1_id() 650returns the previously set ID value to caller in I<id>. The caller should 651allocate adequate memory space for the I<id> before calling EVP_PKEY_CTX_get1_id(). 652 653EVP_PKEY_CTX_set_kem_op() sets the KEM operation to run. This can be set after 654EVP_PKEY_encapsulate_init() or EVP_PKEY_decapsulate_init() to select the kem 655operation. For the key types that support encapsulation and don't have the 656default operation, e.g. RSA, this function must be called before 657EVP_PKEY_encapsulate() or EVP_PKEY_decapsulate(). The supported values for the 658built-in algorithms are enumerated in L<EVP_KEM-RSA(7)>, L<EVP_KEM-EC(7)>, 659L<EVP_KEM-X25519(7)>, and L<EVP_KEM-X448(7)>. 660 661=head1 RETURN VALUES 662 663All other functions described on this page return a positive value for success 664and 0 or a negative value for failure. In particular a return value of -2 665indicates the operation is not supported by the public key algorithm. 666 667=head1 SEE ALSO 668 669L<EVP_PKEY_CTX_set_params(3)>, 670L<EVP_PKEY_CTX_new(3)>, 671L<EVP_PKEY_encrypt(3)>, 672L<EVP_PKEY_decrypt(3)>, 673L<EVP_PKEY_sign(3)>, 674L<EVP_PKEY_verify(3)>, 675L<EVP_PKEY_verify_recover(3)>, 676L<EVP_PKEY_derive(3)>, 677L<EVP_PKEY_keygen(3)> 678L<EVP_PKEY_encapsulate(3)> 679L<EVP_PKEY_decapsulate(3)> 680 681=head1 HISTORY 682 683EVP_PKEY_CTX_get_rsa_oaep_md_name(), EVP_PKEY_CTX_get_rsa_mgf1_md_name(), 684EVP_PKEY_CTX_set_rsa_mgf1_md_name(), EVP_PKEY_CTX_set_rsa_oaep_md_name(), 685EVP_PKEY_CTX_set_dsa_paramgen_md_props(), EVP_PKEY_CTX_set_dsa_paramgen_gindex(), 686EVP_PKEY_CTX_set_dsa_paramgen_type(), EVP_PKEY_CTX_set_dsa_paramgen_seed(), 687EVP_PKEY_CTX_set_group_name() and EVP_PKEY_CTX_get_group_name() 688were added in OpenSSL 3.0. 689 690The EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and 691EVP_PKEY_CTX_get1_id_len() macros were added in 1.1.1, other functions were 692added in OpenSSL 1.0.0. 693 694In OpenSSL 1.1.1 and below the functions were mostly macros. 695From OpenSSL 3.0 they are all functions. 696 697EVP_PKEY_CTX_set_rsa_keygen_pubexp(), EVP_PKEY_CTX_get0_dh_kdf_ukm(), 698and EVP_PKEY_CTX_get0_ecdh_kdf_ukm() were deprecated in OpenSSL 3.0. 699 700=head1 COPYRIGHT 701 702Copyright 2006-2024 The OpenSSL Project Authors. All Rights Reserved. 703 704Licensed under the Apache License 2.0 (the "License"). You may not use 705this file except in compliance with the License. You can obtain a copy 706in the file LICENSE in the source distribution or at 707L<https://www.openssl.org/source/license.html>. 708 709=cut 710
