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