From d8fef6da579c23956c57b03488cb8702cd6d2066 Mon Sep 17 00:00:00 2001
From: Matt Caswell <matt@openssl.org>
Date: Wed, 6 Nov 2019 13:39:21 +0000
Subject: [PATCH] Document various new/changes EVP_PKEY_CTX_* functions

We have converted a number of macros to functions and made them work
with providers. We've also added some *_ex() variants that needed
documenting.

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10152)
---
 doc/man3/EVP_PKEY_CTX_ctrl.pod                | 102 +++++++++++++-----
 .../EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod    |   8 +-
 2 files changed, 79 insertions(+), 31 deletions(-)

diff --git a/doc/man3/EVP_PKEY_CTX_ctrl.pod b/doc/man3/EVP_PKEY_CTX_ctrl.pod
index fe12b09043..06151d4a5c 100644
--- a/doc/man3/EVP_PKEY_CTX_ctrl.pod
+++ b/doc/man3/EVP_PKEY_CTX_ctrl.pod
@@ -20,10 +20,14 @@ EVP_PKEY_CTX_get_rsa_pss_saltlen,
 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,
@@ -95,10 +99,18 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
  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);
 
@@ -241,7 +253,7 @@ supported by the L<EVP_PKEY_new_raw_private_key(3)> function.
 
 =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
@@ -258,7 +270,7 @@ padding for RSA the algorithm identifier byte is added or checked and removed
 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
@@ -283,30 +295,59 @@ modified or freed after the call. If not specified 65537 is used.
 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.
@@ -497,10 +538,9 @@ EVP_PKEY_CTX_settable_params() returns an OSSL_PARAM array on success or NULL on
 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
 
@@ -515,13 +555,21 @@ L<EVP_PKEY_keygen(3)>
 
 =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
 
diff --git a/doc/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod b/doc/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod
index 6d42ab8b0f..e3ed14cfc6 100644
--- a/doc/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod
+++ b/doc/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod
@@ -35,10 +35,10 @@ to the B<RSA> operation except detection of the salt length (using
 RSA_PSS_SALTLEN_AUTO) is not supported for verification if the key has
 usage restrictions.
 
-The EVP_PKEY_CTX_set_signature_md() and EVP_PKEY_CTX_set_rsa_mgf1_md() macros
-are used to set the digest and MGF1 algorithms respectively. If the key has
-usage restrictions then an error is returned if an attempt is made to set the
-digest to anything other than the restricted value. Otherwise these are
+The L<EVP_PKEY_CTX_set_signature_md(3)> and L<EVP_PKEY_CTX_set_rsa_mgf1_md(3)>
+fuunctions are used to set the digest and MGF1 algorithms respectively. If the
+key has usage restrictions then an error is returned if an attempt is made to
+set the digest to anything other than the restricted value. Otherwise these are
 similar to the B<RSA> versions.
 
 =head2 Key Generation
-- 
2.25.1