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