doc/man3/EVP_PKEY_CTX_ctrl.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_PKEY_CTX_ctrl,
   6 EVP_PKEY_CTX_ctrl_str,
   7 EVP_PKEY_CTX_ctrl_uint64,
   8 EVP_PKEY_CTX_md,
   9 EVP_PKEY_CTX_set_signature_md,
  10 EVP_PKEY_CTX_get_signature_md,
  11 EVP_PKEY_CTX_set_mac_key,
  12 EVP_PKEY_CTX_set_rsa_padding,
  13 EVP_PKEY_CTX_get_rsa_padding,
  14 EVP_PKEY_CTX_set_rsa_pss_saltlen,
  15 EVP_PKEY_CTX_get_rsa_pss_saltlen,
  16 EVP_PKEY_CTX_set_rsa_keygen_bits,
  17 EVP_PKEY_CTX_set_rsa_keygen_pubexp,
  18 EVP_PKEY_CTX_set_rsa_keygen_primes,
  19 EVP_PKEY_CTX_set_rsa_mgf1_md,
  20 EVP_PKEY_CTX_get_rsa_mgf1_md,
  21 EVP_PKEY_CTX_set_rsa_oaep_md,
  22 EVP_PKEY_CTX_get_rsa_oaep_md,
  23 EVP_PKEY_CTX_set0_rsa_oaep_label,
  24 EVP_PKEY_CTX_get0_rsa_oaep_label,
  25 EVP_PKEY_CTX_set_dsa_paramgen_bits,
  26 EVP_PKEY_CTX_set_dsa_paramgen_q_bits,
  27 EVP_PKEY_CTX_set_dsa_paramgen_md,
  28 EVP_PKEY_CTX_set_dh_paramgen_prime_len,
  29 EVP_PKEY_CTX_set_dh_paramgen_subprime_len,
  30 EVP_PKEY_CTX_set_dh_paramgen_generator,
  31 EVP_PKEY_CTX_set_dh_paramgen_type,
  32 EVP_PKEY_CTX_set_dh_rfc5114,
  33 EVP_PKEY_CTX_set_dhx_rfc5114,
  34 EVP_PKEY_CTX_set_dh_pad,
  35 EVP_PKEY_CTX_set_dh_nid,
  36 EVP_PKEY_CTX_set_dh_kdf_type,
  37 EVP_PKEY_CTX_get_dh_kdf_type,
  38 EVP_PKEY_CTX_set0_dh_kdf_oid,
  39 EVP_PKEY_CTX_get0_dh_kdf_oid,
  40 EVP_PKEY_CTX_set_dh_kdf_md,
  41 EVP_PKEY_CTX_get_dh_kdf_md,
  42 EVP_PKEY_CTX_set_dh_kdf_outlen,
  43 EVP_PKEY_CTX_get_dh_kdf_outlen,
  44 EVP_PKEY_CTX_set0_dh_kdf_ukm,
  45 EVP_PKEY_CTX_get0_dh_kdf_ukm,
  46 EVP_PKEY_CTX_set_ec_paramgen_curve_nid,
  47 EVP_PKEY_CTX_set_ec_param_enc,
  48 EVP_PKEY_CTX_set_ecdh_cofactor_mode,
  49 EVP_PKEY_CTX_get_ecdh_cofactor_mode,
  50 EVP_PKEY_CTX_set_ecdh_kdf_type,
  51 EVP_PKEY_CTX_get_ecdh_kdf_type,
  52 EVP_PKEY_CTX_set_ecdh_kdf_md,
  53 EVP_PKEY_CTX_get_ecdh_kdf_md,
  54 EVP_PKEY_CTX_set_ecdh_kdf_outlen,
  55 EVP_PKEY_CTX_get_ecdh_kdf_outlen,
  56 EVP_PKEY_CTX_set0_ecdh_kdf_ukm,
  57 EVP_PKEY_CTX_get0_ecdh_kdf_ukm,
  58 EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
  59 - algorithm specific control operations
  60
  61 =head1 SYNOPSIS
  62
  63  #include <openssl/evp.h>
  64
  65  int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype,
  66                        int cmd, int p1, void *p2);
  67  int EVP_PKEY_CTX_ctrl_uint64(EVP_PKEY_CTX *ctx, int keytype, int optype,
  68                               int cmd, uint64_t value);
  69  int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type,
  70                            const char *value);
  71
  72  int EVP_PKEY_CTX_md(EVP_PKEY_CTX *ctx, int optype, int cmd, const char *md);
  73
  74  int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
  75  int EVP_PKEY_CTX_get_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD **pmd);
  76
  77  int EVP_PKEY_CTX_set_mac_key(EVP_PKEY_CTX *ctx, const unsigned char *key,
  78                               int len);
  79
  80  #include <openssl/rsa.h>
  81
  82  int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad);
  83  int EVP_PKEY_CTX_get_rsa_padding(EVP_PKEY_CTX *ctx, int *pad);
  84  int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int len);
  85  int EVP_PKEY_CTX_get_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int *len);
  86  int EVP_PKEY_CTX_set_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits);
  87  int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp);
  88  int EVP_PKEY_CTX_set_rsa_keygen_primes(EVP_PKEY_CTX *ctx, int primes);
  89  int EVP_PKEY_CTX_set_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
  90  int EVP_PKEY_CTX_get_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);
  91  int EVP_PKEY_CTX_set_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
  92  int EVP_PKEY_CTX_get_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);
  93  int EVP_PKEY_CTX_set0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char *label, int len);
  94  int EVP_PKEY_CTX_get0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char **label);
  95
  96  #include <openssl/dsa.h>
  97
  98  int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits);
  99  int EVP_PKEY_CTX_set_dsa_paramgen_q_bits(EVP_PKEY_CTX *ctx, int qbits);
 100  int EVP_PKEY_CTX_set_dsa_paramgen_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
 101
 102  #include <openssl/dh.h>
 103
 104  int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len);
 105  int EVP_PKEY_CTX_set_dh_paramgen_subprime_len(EVP_PKEY_CTX *ctx, int len);
 106  int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen);
 107  int EVP_PKEY_CTX_set_dh_paramgen_type(EVP_PKEY_CTX *ctx, int type);
 108  int EVP_PKEY_CTX_set_dh_pad(EVP_PKEY_CTX *ctx, int pad);
 109  int EVP_PKEY_CTX_set_dh_nid(EVP_PKEY_CTX *ctx, int nid);
 110  int EVP_PKEY_CTX_set_dh_rfc5114(EVP_PKEY_CTX *ctx, int rfc5114);
 111  int EVP_PKEY_CTX_set_dhx_rfc5114(EVP_PKEY_CTX *ctx, int rfc5114);
 112  int EVP_PKEY_CTX_set_dh_kdf_type(EVP_PKEY_CTX *ctx, int kdf);
 113  int EVP_PKEY_CTX_get_dh_kdf_type(EVP_PKEY_CTX *ctx);
 114  int EVP_PKEY_CTX_set0_dh_kdf_oid(EVP_PKEY_CTX *ctx, ASN1_OBJECT *oid);
 115  int EVP_PKEY_CTX_get0_dh_kdf_oid(EVP_PKEY_CTX *ctx, ASN1_OBJECT **oid);
 116  int EVP_PKEY_CTX_set_dh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
 117  int EVP_PKEY_CTX_get_dh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);
 118  int EVP_PKEY_CTX_set_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int len);
 119  int EVP_PKEY_CTX_get_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len);
 120  int EVP_PKEY_CTX_set0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len);
 121  int EVP_PKEY_CTX_get0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm);
 122
 123  #include <openssl/ec.h>
 124
 125  int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid);
 126  int EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, int param_enc);
 127  int EVP_PKEY_CTX_set_ecdh_cofactor_mode(EVP_PKEY_CTX *ctx, int cofactor_mode);
 128  int EVP_PKEY_CTX_get_ecdh_cofactor_mode(EVP_PKEY_CTX *ctx);
 129  int EVP_PKEY_CTX_set_ecdh_kdf_type(EVP_PKEY_CTX *ctx, int kdf);
 130  int EVP_PKEY_CTX_get_ecdh_kdf_type(EVP_PKEY_CTX *ctx);
 131  int EVP_PKEY_CTX_set_ecdh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
 132  int EVP_PKEY_CTX_get_ecdh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);
 133  int EVP_PKEY_CTX_set_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int len);
 134  int EVP_PKEY_CTX_get_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len);
 135  int EVP_PKEY_CTX_set0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len);
 136  int EVP_PKEY_CTX_get0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm);
 137
 138  int EVP_PKEY_CTX_set1_id(EVP_PKEY_CTX *ctx, void *id, size_t id_len);
 139  int EVP_PKEY_CTX_get1_id(EVP_PKEY_CTX *ctx, void *id);
 140  int EVP_PKEY_CTX_get1_id_len(EVP_PKEY_CTX *ctx, size_t *id_len);
 141
 142 =head1 DESCRIPTION
 143
 144 The function EVP_PKEY_CTX_ctrl() sends a control operation to the context
 145 B<ctx>. The key type used must match B<keytype> if it is not -1. The parameter
 146 B<optype> is a mask indicating which operations the control can be applied to.
 147 The control command is indicated in B<cmd> and any additional arguments in
 148 B<p1> and B<p2>.
 149
 150 For B<cmd> = B<EVP_PKEY_CTRL_SET_MAC_KEY>, B<p1> is the length of the MAC key,
 151 and B<p2> is MAC key. This is used by Poly1305, SipHash, HMAC and CMAC.
 152
 153 Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will
 154 instead call one of the algorithm specific macros below.
 155
 156 The function EVP_PKEY_CTX_ctrl_uint64() is a wrapper that directly passes a
 157 uint64 value as B<p2> to EVP_PKEY_CTX_ctrl().
 158
 159 The function EVP_PKEY_CTX_ctrl_str() allows an application to send an algorithm
 160 specific control operation to a context B<ctx> in string form. This is
 161 intended to be used for options specified on the command line or in text
 162 files. The commands supported are documented in the openssl utility
 163 command line pages for the option B<-pkeyopt> which is supported by the
 164 B<pkeyutl>, B<genpkey> and B<req> commands.
 165
 166 The function EVP_PKEY_CTX_md() sends a message digest control operation
 167 to the context B<ctx>. The message digest is specified by its name B<md>.
 168
 169 All the remaining "functions" are implemented as macros.
 170
 171 The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used
 172 in a signature. It can be used in the RSA, DSA and ECDSA algorithms.
 173
 174 The EVP_PKEY_CTX_get_signature_md() macro gets the message digest type used in a
 175 signature. It can be used in the RSA, DSA and ECDSA algorithms.
 176
 177 Key generation typically involves setting up parameters to be used and
 178 generating the private and public key data. Some algorithm implementations
 179 allow private key data to be set explicitly using the EVP_PKEY_CTX_set_mac_key()
 180 macro. In this case key generation is simply the process of setting up the
 181 parameters for the key and then setting the raw key data to the value explicitly
 182 provided by that macro. Normally applications would call
 183 L<EVP_PKEY_new_raw_private_key(3)> or similar functions instead of this macro.
 184
 185 The EVP_PKEY_CTX_set_mac_key() macro can be used with any of the algorithms
 186 supported by the L<EVP_PKEY_new_raw_private_key(3)> function.
 187
 188 =head2 RSA parameters
 189
 190 The EVP_PKEY_CTX_set_rsa_padding() macro sets the RSA padding mode for B<ctx>.
 191 The B<pad> parameter can take the value B<RSA_PKCS1_PADDING> for PKCS#1
 192 padding, B<RSA_SSLV23_PADDING> for SSLv23 padding, B<RSA_NO_PADDING> for
 193 no padding, B<RSA_PKCS1_OAEP_PADDING> for OAEP padding (encrypt and
 194 decrypt only), B<RSA_X931_PADDING> for X9.31 padding (signature operations
 195 only) and B<RSA_PKCS1_PSS_PADDING> (sign and verify only).
 196
 197 Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md()
 198 is used. If this macro is called for PKCS#1 padding the plaintext buffer is
 199 an actual digest value and is encapsulated in a DigestInfo structure according
 200 to PKCS#1 when signing and this structure is expected (and stripped off) when
 201 verifying. If this control is not used with RSA and PKCS#1 padding then the
 202 supplied data is used directly and not encapsulated. In the case of X9.31
 203 padding for RSA the algorithm identifier byte is added or checked and removed
 204 if this control is called. If it is not called then the first byte of the plaintext
 205 buffer is expected to be the algorithm identifier byte.
 206
 207 The EVP_PKEY_CTX_get_rsa_padding() macro gets the RSA padding mode for B<ctx>.
 208
 209 The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro sets the RSA PSS salt length to
 210 B<len>. As its name implies it is only supported for PSS padding. Three special
 211 values are supported: B<RSA_PSS_SALTLEN_DIGEST> sets the salt length to the
 212 digest length, B<RSA_PSS_SALTLEN_MAX> sets the salt length to the maximum
 213 permissible value. When verifying B<RSA_PSS_SALTLEN_AUTO> causes the salt length
 214 to be automatically determined based on the B<PSS> block structure. If this
 215 macro is not called maximum salt length is used when signing and auto detection
 216 when verifying is used by default.
 217
 218 The EVP_PKEY_CTX_get_rsa_pss_saltlen() macro gets the RSA PSS salt length
 219 for B<ctx>. The padding mode must have been set to B<RSA_PKCS1_PSS_PADDING>.
 220
 221 The EVP_PKEY_CTX_set_rsa_keygen_bits() macro sets the RSA key length for
 222 RSA key generation to B<bits>. If not specified 1024 bits is used.
 223
 224 The EVP_PKEY_CTX_set_rsa_keygen_pubexp() macro sets the public exponent value
 225 for RSA key generation to B<pubexp>. Currently it should be an odd integer. The
 226 B<pubexp> pointer is used internally by this function so it should not be
 227 modified or freed after the call. If not specified 65537 is used.
 228
 229 The EVP_PKEY_CTX_set_rsa_keygen_primes() macro sets the number of primes for
 230 RSA key generation to B<primes>. If not specified 2 is used.
 231
 232 The EVP_PKEY_CTX_set_rsa_mgf1_md() macro sets the MGF1 digest for RSA padding
 233 schemes to B<md>. If not explicitly set the signing digest is used. The
 234 padding mode must have been set to B<RSA_PKCS1_OAEP_PADDING>
 235 or B<RSA_PKCS1_PSS_PADDING>.
 236
 237 The EVP_PKEY_CTX_get_rsa_mgf1_md() macro gets the MGF1 digest for B<ctx>.
 238 If not explicitly set the signing digest is used. The padding mode must have
 239 been set to B<RSA_PKCS1_OAEP_PADDING> or B<RSA_PKCS1_PSS_PADDING>.
 240
 241 The EVP_PKEY_CTX_set_rsa_oaep_md() macro sets the message digest type used
 242 in RSA OAEP to B<md>. The padding mode must have been set to
 243 B<RSA_PKCS1_OAEP_PADDING>.
 244
 245 The EVP_PKEY_CTX_get_rsa_oaep_md() macro gets the message digest type used
 246 in RSA OAEP to B<md>. The padding mode must have been set to
 247 B<RSA_PKCS1_OAEP_PADDING>.
 248
 249 The EVP_PKEY_CTX_set0_rsa_oaep_label() macro sets the RSA OAEP label to
 250 B<label> and its length to B<len>. If B<label> is NULL or B<len> is 0,
 251 the label is cleared. The library takes ownership of the label so the
 252 caller should not free the original memory pointed to by B<label>.
 253 The padding mode must have been set to B<RSA_PKCS1_OAEP_PADDING>.
 254
 255 The EVP_PKEY_CTX_get0_rsa_oaep_label() macro gets the RSA OAEP label to
 256 B<label>. The return value is the label length. The padding mode
 257 must have been set to B<RSA_PKCS1_OAEP_PADDING>. The resulting pointer is owned
 258 by the library and should not be freed by the caller.
 259
 260 =head2 DSA parameters
 261
 262 The EVP_PKEY_CTX_set_dsa_paramgen_bits() macro sets the number of bits used
 263 for DSA parameter generation to B<nbits>. If not specified, 1024 is used.
 264
 265 The EVP_PKEY_CTX_set_dsa_paramgen_q_bits() macro sets the number of bits in the
 266 subprime parameter B<q> for DSA parameter generation to B<qbits>. If not
 267 specified, 160 is used. If a digest function is specified below, this parameter
 268 is ignored and instead, the number of bits in B<q> matches the size of the
 269 digest.
 270
 271 The EVP_PKEY_CTX_set_dsa_paramgen_md() macro sets the digest function used for
 272 DSA parameter generation to B<md>. If not specified, one of SHA-1, SHA-224, or
 273 SHA-256 is selected to match the bit length of B<q> above.
 274
 275 =head2 DH parameters
 276
 277 The EVP_PKEY_CTX_set_dh_paramgen_prime_len() macro sets the length of the DH
 278 prime parameter B<p> for DH parameter generation. If this macro is not called
 279 then 1024 is used. Only accepts lengths greater than or equal to 256.
 280
 281 The EVP_PKEY_CTX_set_dh_paramgen_subprime_len() macro sets the length of the DH
 282 optional subprime parameter B<q> for DH parameter generation. The default is
 283 256 if the prime is at least 2048 bits long or 160 otherwise. The DH
 284 paramgen type must have been set to x9.42.
 285
 286 The EVP_PKEY_CTX_set_dh_paramgen_generator() macro sets DH generator to B<gen>
 287 for DH parameter generation. If not specified 2 is used.
 288
 289 The EVP_PKEY_CTX_set_dh_paramgen_type() macro sets the key type for DH
 290 parameter generation. Use 0 for PKCS#3 DH and 1 for X9.42 DH.
 291 The default is 0.
 292
 293 The EVP_PKEY_CTX_set_dh_pad() macro sets the DH padding mode. If B<pad> is
 294 1 the shared secret is padded with zeroes up to the size of the DH prime B<p>.
 295 If B<pad> is zero (the default) then no padding is performed.
 296
 297 EVP_PKEY_CTX_set_dh_nid() sets the DH parameters to values corresponding to
 298 B<nid> as defined in RFC7919. The B<nid> parameter must be B<NID_ffdhe2048>,
 299 B<NID_ffdhe3072>, B<NID_ffdhe4096>, B<NID_ffdhe6144>, B<NID_ffdhe8192>
 300 or B<NID_undef> to clear the stored value. This macro can be called during
 301 parameter or key generation.
 302 The nid parameter and the rfc5114 parameter are mutually exclusive.
 303
 304 The EVP_PKEY_CTX_set_dh_rfc5114() and EVP_PKEY_CTX_set_dhx_rfc5114() macros are
 305 synonymous. They set the DH parameters to the values defined in RFC5114. The
 306 B<rfc5114> parameter must be 1, 2 or 3 corresponding to RFC5114 sections
 307 2.1, 2.2 and 2.3. or 0 to clear the stored value. This macro can be called
 308 during parameter generation. The B<ctx> must have a key type of
 309 B<EVP_PKEY_DHX>.
 310 The rfc5114 parameter and the nid parameter are mutually exclusive.
 311
 312 =head2 DH key derivation function parameters
 313
 314 Note that all of the following functions require that the B<ctx> parameter has
 315 a private key type of B<EVP_PKEY_DHX>. When using key derivation, the output of
 316 EVP_PKEY_derive() is the output of the KDF instead of the DH shared secret.
 317 The KDF output is typically used as a Key Encryption Key (KEK) that in turn
 318 encrypts a Content Encryption Key (CEK).
 319
 320 The EVP_PKEY_CTX_set_dh_kdf_type() macro sets the key derivation function type
 321 to B<kdf> for DH key derivation. Possible values are B<EVP_PKEY_DH_KDF_NONE>
 322 and B<EVP_PKEY_DH_KDF_X9_42> which uses the key derivation specified in RFC2631
 323 (based on the keying algorithm described in X9.42). When using key derivation,
 324 the B<kdf_oid>, B<kdf_md> and B<kdf_outlen> parameters must also be specified.
 325
 326 The EVP_PKEY_CTX_get_dh_kdf_type() macro gets the key derivation function type
 327 for B<ctx> used for DH key derivation. Possible values are B<EVP_PKEY_DH_KDF_NONE>
 328 and B<EVP_PKEY_DH_KDF_X9_42>.
 329
 330 The EVP_PKEY_CTX_set0_dh_kdf_oid() macro sets the key derivation function
 331 object identifier to B<oid> for DH key derivation. This OID should identify
 332 the algorithm to be used with the Content Encryption Key.
 333 The library takes ownership of the object identifier so the caller should not
 334 free the original memory pointed to by B<oid>.
 335
 336 The EVP_PKEY_CTX_get0_dh_kdf_oid() macro gets the key derivation function oid
 337 for B<ctx> used for DH key derivation. The resulting pointer is owned by the
 338 library and should not be freed by the caller.
 339
 340 The EVP_PKEY_CTX_set_dh_kdf_md() macro sets the key derivation function
 341 message digest to B<md> for DH key derivation. Note that RFC2631 specifies
 342 that this digest should be SHA1 but OpenSSL tolerates other digests.
 343
 344 The EVP_PKEY_CTX_get_dh_kdf_md() macro gets the key derivation function
 345 message digest for B<ctx> used for DH key derivation.
 346
 347 The EVP_PKEY_CTX_set_dh_kdf_outlen() macro sets the key derivation function
 348 output length to B<len> for DH key derivation.
 349
 350 The EVP_PKEY_CTX_get_dh_kdf_outlen() macro gets the key derivation function
 351 output length for B<ctx> used for DH key derivation.
 352
 353 The EVP_PKEY_CTX_set0_dh_kdf_ukm() macro sets the user key material to
 354 B<ukm> and its length to B<len> for DH key derivation. This parameter is optional
 355 and corresponds to the partyAInfo field in RFC2631 terms. The specification
 356 requires that it is 512 bits long but this is not enforced by OpenSSL.
 357 The library takes ownership of the user key material so the caller should not
 358 free the original memory pointed to by B<ukm>.
 359
 360 The EVP_PKEY_CTX_get0_dh_kdf_ukm() macro gets the user key material for B<ctx>.
 361 The return value is the user key material length. The resulting pointer is owned
 362 by the library and should not be freed by the caller.
 363
 364 =head2 EC parameters
 365
 366 The EVP_PKEY_CTX_set_ec_paramgen_curve_nid() sets the EC curve for EC parameter
 367 generation to B<nid>. For EC parameter generation this macro must be called
 368 or an error occurs because there is no default curve.
 369 This function can also be called to set the curve explicitly when
 370 generating an EC key.
 371
 372 The EVP_PKEY_CTX_set_ec_param_enc() macro sets the EC parameter encoding to
 373 B<param_enc> when generating EC parameters or an EC key. The encoding can be
 374 B<OPENSSL_EC_EXPLICIT_CURVE> for explicit parameters (the default in versions
 375 of OpenSSL before 1.1.0) or B<OPENSSL_EC_NAMED_CURVE> to use named curve form.
 376 For maximum compatibility the named curve form should be used. Note: the
 377 B<OPENSSL_EC_NAMED_CURVE> value was added in OpenSSL 1.1.0; previous
 378 versions should use 0 instead.
 379
 380 =head2 ECDH parameters
 381
 382 The EVP_PKEY_CTX_set_ecdh_cofactor_mode() macro sets the cofactor mode to
 383 B<cofactor_mode> for ECDH key derivation. Possible values are 1 to enable
 384 cofactor key derivation, 0 to disable it and -1 to clear the stored cofactor
 385 mode and fallback to the private key cofactor mode.
 386
 387 The EVP_PKEY_CTX_get_ecdh_cofactor_mode() macro returns the cofactor mode for
 388 B<ctx> used for ECDH key derivation. Possible values are 1 when cofactor key
 389 derivation is enabled and 0 otherwise.
 390
 391 =head2 ECDH key derivation function parameters
 392
 393 The EVP_PKEY_CTX_set_ecdh_kdf_type() macro sets the key derivation function type
 394 to B<kdf> for ECDH key derivation. Possible values are B<EVP_PKEY_ECDH_KDF_NONE>
 395 and B<EVP_PKEY_ECDH_KDF_X9_63> which uses the key derivation specified in X9.63.
 396 When using key derivation, the B<kdf_md> and B<kdf_outlen> parameters must
 397 also be specified.
 398
 399 The EVP_PKEY_CTX_get_ecdh_kdf_type() macro returns the key derivation function
 400 type for B<ctx> used for ECDH key derivation. Possible values are
 401 B<EVP_PKEY_ECDH_KDF_NONE> and B<EVP_PKEY_ECDH_KDF_X9_63>.
 402
 403 The EVP_PKEY_CTX_set_ecdh_kdf_md() macro sets the key derivation function
 404 message digest to B<md> for ECDH key derivation. Note that X9.63 specifies
 405 that this digest should be SHA1 but OpenSSL tolerates other digests.
 406
 407 The EVP_PKEY_CTX_get_ecdh_kdf_md() macro gets the key derivation function
 408 message digest for B<ctx> used for ECDH key derivation.
 409
 410 The EVP_PKEY_CTX_set_ecdh_kdf_outlen() macro sets the key derivation function
 411 output length to B<len> for ECDH key derivation.
 412
 413 The EVP_PKEY_CTX_get_ecdh_kdf_outlen() macro gets the key derivation function
 414 output length for B<ctx> used for ECDH key derivation.
 415
 416 The EVP_PKEY_CTX_set0_ecdh_kdf_ukm() macro sets the user key material to B<ukm>
 417 for ECDH key derivation. This parameter is optional and corresponds to the
 418 shared info in X9.63 terms. The library takes ownership of the user key material
 419 so the caller should not free the original memory pointed to by B<ukm>.
 420
 421 The EVP_PKEY_CTX_get0_ecdh_kdf_ukm() macro gets the user key material for B<ctx>.
 422 The return value is the user key material length. The resulting pointer is owned
 423 by the library and should not be freed by the caller.
 424
 425 =head2 Other parameters
 426
 427 The EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and EVP_PKEY_CTX_get1_id_len()
 428 macros are used to manipulate the special identifier field for specific signature
 429 algorithms such as SM2. The EVP_PKEY_CTX_set1_id() sets an ID pointed by B<id> with
 430 the length B<id_len> to the library. The library takes a copy of the id so that
 431 the caller can safely free the original memory pointed to by B<id>. The
 432 EVP_PKEY_CTX_get1_id_len() macro returns the length of the ID set via a previous
 433 call to EVP_PKEY_CTX_set1_id(). The length is usually used to allocate adequate
 434 memory for further calls to EVP_PKEY_CTX_get1_id(). The EVP_PKEY_CTX_get1_id()
 435 macro returns the previously set ID value to caller in B<id>. The caller should
 436 allocate adequate memory space for the B<id> before calling EVP_PKEY_CTX_get1_id().
 437
 438 =head1 RETURN VALUES
 439
 440 EVP_PKEY_CTX_ctrl() and its macros return a positive value for success and 0
 441 or a negative value for failure. In particular a return value of -2
 442 indicates the operation is not supported by the public key algorithm.
 443
 444 =head1 SEE ALSO
 445
 446 L<EVP_PKEY_CTX_new(3)>,
 447 L<EVP_PKEY_encrypt(3)>,
 448 L<EVP_PKEY_decrypt(3)>,
 449 L<EVP_PKEY_sign(3)>,
 450 L<EVP_PKEY_verify(3)>,
 451 L<EVP_PKEY_verify_recover(3)>,
 452 L<EVP_PKEY_derive(3)>,
 453 L<EVP_PKEY_keygen(3)>
 454
 455 =head1 HISTORY
 456
 457 The
 458 EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and EVP_PKEY_CTX_get1_id_len()
 459 macros were added in 1.1.1, other functions were added in OpenSSL 1.0.0.
 460
 461 =head1 COPYRIGHT
 462
 463 Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.
 464
 465 Licensed under the Apache License 2.0 (the "License").  You may not use
 466 this file except in compliance with the License.  You can obtain a copy
 467 in the file LICENSE in the source distribution or at
 468 L<https://www.openssl.org/source/license.html>.
 469
 470 =cut