EVP_PKEY_CTX_set_rsa_keygen_bits,
EVP_PKEY_CTX_set_rsa_keygen_pubexp,
EVP_PKEY_CTX_set_rsa_keygen_primes,
+EVP_PKEY_CTX_set_rsa_mgf1_md_name,
EVP_PKEY_CTX_set_rsa_mgf1_md,
EVP_PKEY_CTX_get_rsa_mgf1_md,
+EVP_PKEY_CTX_get_rsa_mgf1_md_name,
+EVP_PKEY_CTX_set_rsa_oaep_md_name,
EVP_PKEY_CTX_set_rsa_oaep_md,
EVP_PKEY_CTX_get_rsa_oaep_md,
+EVP_PKEY_CTX_get_rsa_oaep_md_name,
EVP_PKEY_CTX_set0_rsa_oaep_label,
EVP_PKEY_CTX_get0_rsa_oaep_label,
EVP_PKEY_CTX_set_dsa_paramgen_bits,
int EVP_PKEY_CTX_set_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits);
int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp);
int EVP_PKEY_CTX_set_rsa_keygen_primes(EVP_PKEY_CTX *ctx, int primes);
+ int EVP_PKEY_CTX_set_rsa_mgf1_md_name(EVP_PKEY_CTX *ctx, const char *mdname,
+ const char *mdprops);
int EVP_PKEY_CTX_set_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
int EVP_PKEY_CTX_get_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);
+ int EVP_PKEY_CTX_get_rsa_mgf1_md_name(EVP_PKEY_CTX *ctx, char *name,
+ size_t namelen);
+ int EVP_PKEY_CTX_set_rsa_oaep_md_name(EVP_PKEY_CTX *ctx, const char *mdname,
+ const char *mdprops);
int EVP_PKEY_CTX_set_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
int EVP_PKEY_CTX_get_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);
+ int EVP_PKEY_CTX_get_rsa_oaep_md_name(EVP_PKEY_CTX *ctx, char *name,
+ size_t namelen)
int EVP_PKEY_CTX_set0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char *label, int len);
int EVP_PKEY_CTX_get0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char **label);
See L<OSSL_PROVIDER(3)> for more information on providers.
See L<OSSL_PARAM(3)> for more information on parameters.
These functions must only be called after the EVP_PKEY_CTX has been initialised
-for use in an operation (for example by L<EVP_PKEY_sign_init_ex(3)>,
-L<EVP_PKEY_derive_init_ex(3)> or other similar functions).
+for use in an operation.
The parameters currently supported by the default provider are:
=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer>
Sets the DH padding mode.
-If B<OSSL_EXCHANGE_PARAM_PAD> is 1 then the shared secret is padded with zeroes
+If B<OSSL_EXCHANGE_PARAM_PAD> is 1 then the shared secret is padded with zeros
up to the size of the DH prime B<p>.
If B<OSSL_EXCHANGE_PARAM_PAD> is zero (the default) then no padding is
performed.
=back
EVP_PKEY_CTX_gettable_params() and EVP_PKEY_CTX_settable_params() gets a
-constant B<OSSL_PARAM> array that decribes the gettable and
+constant B<OSSL_PARAM> array that describes the gettable and
settable parameters for the current algorithm implementation, i.e. parameters
that can be used with EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params()
respectively.
See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
These functions must only be called after the EVP_PKEY_CTX has been initialised
-for use in an operation (for example by L<EVP_PKEY_sign_init_ex(3)>,
-L<EVP_PKEY_derive_init_ex(3)> or other similar functions).
+for use in an operation.
The function EVP_PKEY_CTX_ctrl() sends a control operation to the context
B<ctx>. The key type used must match B<keytype> if it is not -1. The parameter
=head2 RSA parameters
-The EVP_PKEY_CTX_set_rsa_padding() macro sets the RSA padding mode for B<ctx>.
+The EVP_PKEY_CTX_set_rsa_padding() function sets the RSA padding mode for B<ctx>.
The B<pad> parameter can take the value B<RSA_PKCS1_PADDING> for PKCS#1
padding, B<RSA_SSLV23_PADDING> for SSLv23 padding, B<RSA_NO_PADDING> for
no padding, B<RSA_PKCS1_OAEP_PADDING> for OAEP padding (encrypt and
decrypt only), B<RSA_X931_PADDING> for X9.31 padding (signature operations
-only) and B<RSA_PKCS1_PSS_PADDING> (sign and verify only).
+only), B<RSA_PKCS1_PSS_PADDING> (sign and verify only) and
+B<RSA_PKCS1_WITH_TLS_PADDING> for TLS RSA ClientKeyExchange message padding
+(decryption only).
Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md()
is used. If this macro is called for PKCS#1 padding the plaintext buffer is
if this control is called. If it is not called then the first byte of the plaintext
buffer is expected to be the algorithm identifier byte.
-The EVP_PKEY_CTX_get_rsa_padding() macro gets the RSA padding mode for B<ctx>.
+The EVP_PKEY_CTX_get_rsa_padding() function gets the RSA padding mode for B<ctx>.
The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro sets the RSA PSS salt length to
B<len>. As its name implies it is only supported for PSS padding. Three special
The EVP_PKEY_CTX_set_rsa_keygen_primes() macro sets the number of primes for
RSA key generation to B<primes>. If not specified 2 is used.
-The EVP_PKEY_CTX_set_rsa_mgf1_md() macro sets the MGF1 digest for RSA padding
-schemes to B<md>. If not explicitly set the signing digest is used. The
-padding mode must have been set to B<RSA_PKCS1_OAEP_PADDING>
+The EVP_PKEY_CTX_set_rsa_mgf1_md_name() function sets the MGF1 digest for RSA
+padding schemes to the digest named B<mdname>. If the RSA algorithm
+implementation for the selected provider supports it then the digest will be
+fetched using the properties B<mdprops>. If not explicitly set the signing
+digest is used. The padding mode must have been set to B<RSA_PKCS1_OAEP_PADDING>
or B<RSA_PKCS1_PSS_PADDING>.
-The EVP_PKEY_CTX_get_rsa_mgf1_md() macro gets the MGF1 digest for B<ctx>.
-If not explicitly set the signing digest is used. The padding mode must have
-been set to B<RSA_PKCS1_OAEP_PADDING> or B<RSA_PKCS1_PSS_PADDING>.
-
-The EVP_PKEY_CTX_set_rsa_oaep_md() macro sets the message digest type used
-in RSA OAEP to B<md>. The padding mode must have been set to
+The EVP_PKEY_CTX_set_rsa_mgf1_md() function does the same as
+EVP_PKEY_CTX_set_rsa_mgf1_md_name() except that the name of the digest is
+inferred from the supplied B<md> and it is not possible to specify any
+properties.
+
+The EVP_PKEY_CTX_get_rsa_mgf1_md_name() function gets the name of the MGF1
+digest algorithm for B<ctx>. If not explicitly set the signing digest is used.
+The padding mode must have been set to B<RSA_PKCS1_OAEP_PADDING> or
+B<RSA_PKCS1_PSS_PADDING>.
+
+The EVP_PKEY_CTX_get_rsa_mgf1_md() function does the same as
+EVP_PKEY_CTX_get_rsa_mgf1_md_name() except that it returns a pointer to an
+EVP_MD object instead. Note that only known, built-in EVP_MD objects will be
+returned. The EVP_MD object may be NULL if the digest is not one of these (such
+as a digest only implemented in a third party provider).
+
+The EVP_PKEY_CTX_set_rsa_oaep_md_name() function sets the message digest type
+used in RSA OAEP to the digest named B<mdname>. If the RSA algorithm
+implementation for the selected provider supports it then the digest will be
+fetched using the properties B<mdprops>. The padding mode must have been set to
B<RSA_PKCS1_OAEP_PADDING>.
-The EVP_PKEY_CTX_get_rsa_oaep_md() macro gets the message digest type used
-in RSA OAEP to B<md>. The padding mode must have been set to
-B<RSA_PKCS1_OAEP_PADDING>.
+The EVP_PKEY_CTX_set_rsa_oaep_md() function does the same as
+EVP_PKEY_CTX_set_rsa_oaep_md_name() except that the name of the digest is
+inferred from the supplied B<md> and it is not possible to specify any
+properties.
+
+The EVP_PKEY_CTX_get_rsa_oaep_md_name() function gets the message digest
+algorithm name used in RSA OAEP and stores it in the buffer B<name> which is of
+size B<namelen>. The padding mode must have been set to
+B<RSA_PKCS1_OAEP_PADDING>. The buffer should be sufficiently large for any
+expected digest algorithm names or the function will fail.
-The EVP_PKEY_CTX_set0_rsa_oaep_label() macro sets the RSA OAEP label to
+The EVP_PKEY_CTX_get_rsa_oaep_md() function does the same as
+EVP_PKEY_CTX_get_rsa_oaep_md_name() except that it returns a pointer to an
+EVP_MD object instead. Note that only known, built-in EVP_MD objects will be
+returned. The EVP_MD object may be NULL if the digest is not one of these (such
+as a digest only implemented in a third party provider).
+
+The EVP_PKEY_CTX_set0_rsa_oaep_label() function sets the RSA OAEP label to
B<label> and its length to B<len>. If B<label> is NULL or B<len> is 0,
the label is cleared. The library takes ownership of the label so the
caller should not free the original memory pointed to by B<label>.
The padding mode must have been set to B<RSA_PKCS1_OAEP_PADDING>.
-The EVP_PKEY_CTX_get0_rsa_oaep_label() macro gets the RSA OAEP label to
+The EVP_PKEY_CTX_get0_rsa_oaep_label() function gets the RSA OAEP label to
B<label>. The return value is the label length. The padding mode
must have been set to B<RSA_PKCS1_OAEP_PADDING>. The resulting pointer is owned
by the library and should not be freed by the caller.
+B<RSA_PKCS1_WITH_TLS_PADDING> is used when decrypting an RSA encrypted TLS
+pre-master secret in a TLS ClientKeyExchange message. It is the same as
+RSA_PKCS1_PADDING except that it additionally verifies that the result is the
+correct length and the first two bytes are the protocol version initially
+requested by the client. If the encrypted content is publicly invalid then the
+decryption will fail. However, if the padding checks fail then decryption will
+still appear to succeed but a random TLS premaster secret will be returned
+instead. This padding mode accepts two parameters which can be set using the
+L<EVP_PKEY_CTX_set_params(3)> function. These are
+OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION and
+OSSL_ASYM_CIPHER_PARAM_TLS_NEGOTIATED_VERSION, both of which are expected to be
+unsigned integers. Normally only the first of these will be set and represents
+the TLS protocol version that was first requested by the client (e.g. 0x0303 for
+TLSv1.2, 0x0302 for TLSv1.1 etc). Historically some buggy clients would use the
+negotiated protocol version instead of the protocol version first requested. If
+this behaviour should be tolerated then
+OSSL_ASYM_CIPHER_PARAM_TLS_NEGOTIATED_VERSION should be set to the actual
+negotiated protocol version. Otherwise it should be left unset.
+
=head2 DSA parameters
The EVP_PKEY_CTX_set_dsa_paramgen_bits() macro sets the number of bits used
The EVP_PKEY_CTX_set_dh_paramgen_prime_len() macro sets the length of the DH
prime parameter B<p> for DH parameter generation. If this macro is not called
-then 1024 is used. Only accepts lengths greater than or equal to 256.
+then 2048 is used. Only accepts lengths greater than or equal to 256.
The EVP_PKEY_CTX_set_dh_paramgen_subprime_len() macro sets the length of the DH
optional subprime parameter B<q> for DH parameter generation. The default is
256 if the prime is at least 2048 bits long or 160 otherwise. The DH
-paramgen type must have been set to x9.42.
+paramgen type must have been set to B<DH_PARAMGEN_TYPE_FIPS_186_2> or
+B<DH_PARAMGEN_TYPE_FIPS_186_4>.
The EVP_PKEY_CTX_set_dh_paramgen_generator() macro sets DH generator to B<gen>
for DH parameter generation. If not specified 2 is used.
The EVP_PKEY_CTX_set_dh_paramgen_type() macro sets the key type for DH
-parameter generation. Use 0 for PKCS#3 DH and 1 for X9.42 DH.
-The default is 0.
+parameter generation. The supported parameters are:
+
+=over 4
+
+=item B<DH_PARAMGEN_TYPE_GENERATOR>
+
+Uses a generator g (PKCS#3 format).
+
+=item B<DH_PARAMGEN_TYPE_FIPS_186_2>
+
+FIPS186-2 FFC parameter generator (X9.42 DH).
+
+=item B<DH_PARAMGEN_TYPE_FIPS_186_4>
+
+FIPS186-4 FFC parameter generator.
+
+=back
+
+The default is B<DH_PARAMGEN_TYPE_GENERATOR>.
The EVP_PKEY_CTX_set_dh_pad() function sets the DH padding mode.
-If B<pad> is 1 the shared secret is padded with zeroes up to the size of the DH
+If B<pad> is 1 the shared secret is padded with zeros up to the size of the DH
prime B<p>.
If B<pad> is zero (the default) then no padding is performed.
EVP_PKEY_CTX_set_dh_nid() sets the DH parameters to values corresponding to
-B<nid> as defined in RFC7919. The B<nid> parameter must be B<NID_ffdhe2048>,
-B<NID_ffdhe3072>, B<NID_ffdhe4096>, B<NID_ffdhe6144>, B<NID_ffdhe8192>
-or B<NID_undef> to clear the stored value. This macro can be called during
-parameter or key generation.
+B<nid> as defined in RFC7919 or RFC3526. The B<nid> parameter must be
+B<NID_ffdhe2048>, B<NID_ffdhe3072>, B<NID_ffdhe4096>, B<NID_ffdhe6144>,
+B<NID_ffdhe8192>, B<NID_modp_1536>, B<NID_modp_2048>, B<NID_modp_3072>,
+B<NID_modp_4096>, B<NID_modp_6144>, B<NID_modp_8192> or B<NID_undef> to clear
+the stored value. This macro can be called during parameter or key generation.
The nid parameter and the rfc5114 parameter are mutually exclusive.
The EVP_PKEY_CTX_set_dh_rfc5114() and EVP_PKEY_CTX_set_dhx_rfc5114() macros are
error.
It may also return NULL if there are no settable parameters available.
-EVP_PKEY_CTX_set_signature_md(), EVP_PKEY_CTX_set_dh_pad(), EVP_PKEY_CTX_ctrl()
-and its macros return a positive value for success and 0 or a negative value for
-failure. In particular a return value of -2 indicates the operation is not
-supported by the public key algorithm.
+All other functions and macros described on this page return a positive value
+for success and 0 or a negative value for failure. In particular a return value
+of -2 indicates the operation is not supported by the public key algorithm.
=head1 SEE ALSO
=head1 HISTORY
-The
-EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and EVP_PKEY_CTX_get1_id_len()
-macros were added in 1.1.1, other functions were added in OpenSSL 1.0.0.
-
-EVP_PKEY_CTX_get_signature_md(), EVP_PKEY_CTX_set_signature_md() and
-EVP_PKEY_CTX_set_dh_pad() were macros in OpenSSL 1.1.1 and below. From OpenSSL
-3.0 they are functions.
+EVP_PKEY_CTX_get_signature_md(), EVP_PKEY_CTX_set_signature_md(),
+EVP_PKEY_CTX_set_dh_pad(), EVP_PKEY_CTX_set_rsa_padding(),
+EVP_PKEY_CTX_get_rsa_padding(), EVP_PKEY_CTX_get_rsa_mgf1_md(),
+EVP_PKEY_CTX_set_rsa_mgf1_md(), EVP_PKEY_CTX_set_rsa_oaep_md(),
+EVP_PKEY_CTX_get_rsa_oaep_md(), EVP_PKEY_CTX_set0_rsa_oaep_label(),
+EVP_PKEY_CTX_get0_rsa_oaep_label() were macros in OpenSSL 1.1.1 and below. From
+OpenSSL 3.0 they are functions.
+
+EVP_PKEY_CTX_get_rsa_oaep_md_name(), EVP_PKEY_CTX_get_rsa_mgf1_md_name(),
+EVP_PKEY_CTX_set_rsa_mgf1_md_name() and EVP_PKEY_CTX_set_rsa_oaep_md_name() were
+added in OpenSSL 3.0.
+
+The EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and
+EVP_PKEY_CTX_get1_id_len() macros were added in 1.1.1, other functions were
+added in OpenSSL 1.0.0.
=head1 COPYRIGHT
projects / thirdparty / openssl.git / blobdiff