Revise EVP_PKEY param handling

We add new functions for getting parameters and discovering the gettable
and settable parameters. We also make EVP_PKEY_CTX_get_signature_md() a
function and implement it in terms of the new functions.

This enables applications to discover the set of parameters that are
supported for a given algorithm implementation.

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9753)

3 files changed, 87 insertions, 44 deletions

diff --git a/doc/man3/EVP_PKEY_CTX_ctrl.pod b/doc/man3/EVP_PKEY_CTX_ctrl.pod
index 9d1812f6bd..18b984162e 100644
--- a/doc/man3/EVP_PKEY_CTX_ctrl.pod
+++ b/doc/man3/EVP_PKEY_CTX_ctrl.pod
@@ -2,7 +2,10 @@
 
 =head1 NAME
 
+EVP_PKEY_CTX_get_params,
+EVP_PKEY_CTX_gettable_params,
 EVP_PKEY_CTX_set_params,
+EVP_PKEY_CTX_settable_params,
 EVP_PKEY_CTX_ctrl,
 EVP_PKEY_CTX_ctrl_str,
 EVP_PKEY_CTX_ctrl_uint64,
@@ -63,7 +66,10 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
 
  #include <openssl/evp.h>
 
+ int EVP_PKEY_CTX_get_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params);
+ const OSSL_PARAM *EVP_PKEY_CTX_gettable_params(EVP_PKEY_CTX *ctx);
  int EVP_PKEY_CTX_set_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params);
+ const OSSL_PARAM *EVP_PKEY_CTX_settable_params(EVP_PKEY_CTX *ctx);
 
  int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype,
                        int cmd, int p1, void *p2);
@@ -144,16 +150,20 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
 
 =head1 DESCRIPTION
 
-The EVP_PKEY_CTX_set_params() function sends arbitrary parameters to the
-algorithm implementation.
+The EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params() functions get and
+send arbitrary parameters from and to the algorithm implementation respectively.
 Not all parameters may be supported by all providers.
 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).
+
 The parameters currently supported by the default provider are:
 
 =over 4
 
-=item OSSL_EXCHANGE_PARAM_PAD (uint type)
+=item "exchange-pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <uint>
 
 Sets the DH padding mode.
 If B<OSSL_EXCHANGE_PARAM_PAD> is 1 then the  shared secret is padded with zeroes
@@ -161,19 +171,29 @@ 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.
 
-=item OSSL_SIGNATURE_PARAM_DIGEST (UTF8 string type)
+=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <utf8 string>
 
-Sets the name of the digest algorithm used for the input to the signature
-functions.
+Gets and sets the name of the digest algorithm used for the input to the
+signature functions.
 
-=item OSSL_SIGNATURE_PARAM_DIGEST_SIZE (size_t type)
+=item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <size_t>
 
-Sets the output size of the digest algorithm used for the input to the signature
-functions.
+Gets and sets the output size of the digest algorithm used for the input to the
+signature functions.
 The internal algorithm that supports this parameter is DSA.
 
 =back
 
+EVP_PKEY_CTX_gettable_params() and EVP_PKEY_CTX_settable_params() gets a
+constant B<OSSL_PARAM> array that decribes 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).
+
 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
 B<optype> is a mask indicating which operations the control can be applied to.
@@ -199,13 +219,13 @@ B<pkeyutl>, B<genpkey> and B<req> commands.
 The function EVP_PKEY_CTX_md() sends a message digest control operation
 to the context B<ctx>. The message digest is specified by its name B<md>.
 
-All the remaining "functions" are implemented as macros.
+The EVP_PKEY_CTX_set_signature_md() function sets the message digest type used
+in a signature. It can be used in the RSA, DSA and ECDSA algorithms.
 
-The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used
+The EVP_PKEY_CTX_get_signature_md() function gets the message digest type used
 in a signature. It can be used in the RSA, DSA and ECDSA algorithms.
 
-The EVP_PKEY_CTX_get_signature_md() macro gets the message digest type used in a
-signature. It can be used in the RSA, DSA and ECDSA algorithms.
+All the remaining "functions" are implemented as macros.
 
 Key generation typically involves setting up parameters to be used and
 generating the private and public key data. Some algorithm implementations
@@ -471,9 +491,15 @@ allocate adequate memory space for the B<id> before calling EVP_PKEY_CTX_get1_id
 
 =head1 RETURN VALUES
 
-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.
+EVP_PKEY_CTX_set_params() returns 1 for success or 0 otherwise.
+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.
 
 =head1 SEE ALSO
 
@@ -492,8 +518,9 @@ 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_set_dh_pad() was a macro in OpenSSL 1.1.1 and below.
-From OpenSSL 3.0 it is a function.
+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.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man7/provider-keyexch.pod b/doc/man7/provider-keyexch.pod
index 71830c12c6..9ef294395c 100644
--- a/doc/man7/provider-keyexch.pod
+++ b/doc/man7/provider-keyexch.pod
@@ -29,8 +29,8 @@ provider-keyexch - The keyexch library E<lt>-E<gt> provider functions
                        size_t outlen);
 
  /* Key Exchange parameters */
- int OP_keyexch_set_params(void *ctx, const OSSL_PARAM params[]);
-
+ int OP_keyexch_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
+ const OSSL_PARAM *OP_keyexch_settable_ctx_params(void);
 
 =head1 DESCRIPTION
 
@@ -61,15 +61,16 @@ For example, the "function" OP_keyexch_newctx() has these:
 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
 macros in L<openssl-core_numbers.h(7)>, as follows:
 
- OP_keyexch_newctx           OSSL_FUNC_KEYEXCH_NEWCTX
- OP_keyexch_freectx          OSSL_FUNC_KEYEXCH_FREECTX
- OP_keyexch_dupctx           OSSL_FUNC_KEYEXCH_DUPCTX
+ OP_keyexch_newctx                OSSL_FUNC_KEYEXCH_NEWCTX
+ OP_keyexch_freectx               OSSL_FUNC_KEYEXCH_FREECTX
+ OP_keyexch_dupctx                OSSL_FUNC_KEYEXCH_DUPCTX
 
- OP_keyexch_init             OSSL_FUNC_KEYEXCH_INIT
- OP_keyexch_set_peer         OSSL_FUNC_KEYEXCH_SET_PEER
- OP_keyexch_derive           OSSL_FUNC_KEYEXCH_DERIVE
+ OP_keyexch_init                  OSSL_FUNC_KEYEXCH_INIT
+ OP_keyexch_set_peer              OSSL_FUNC_KEYEXCH_SET_PEER
+ OP_keyexch_derive                OSSL_FUNC_KEYEXCH_DERIVE
 
- OP_keyexch_set_params       OSSL_FUNC_KEYEXCH_SET_PARAMS
+ OP_keyexch_set_ctx_params        OSSL_FUNC_KEYEXCH_SET_CTX_PARAMS
+ OP_keyexch_settable_ctx_params   OSSL_FUNC_KEYEXCH_SETTABLE_CTX_PARAMS
 
 A key exchange algorithm implementation may not implement all of these functions.
 In order to be a consistent set of functions a provider must implement
@@ -127,8 +128,8 @@ written to B<*secretlen>.
 See L<OSSL_PARAM(3)> for further details on the parameters structure used by
 the OP_keyexch_set_params() function.
 
-OP_keyexch_set_params() sets key exchange parameters associated with the given
-provider side key exchange context B<ctx> to B<params>.
+OP_keyexch_set_ctx_params() sets key exchange parameters associated with the
+given provider side key exchange context B<ctx> to B<params>.
 Any parameter settings are additional to any that were previously set.
 
 Parameters currently recognised by built-in key exchange algorithms are as
@@ -151,6 +152,11 @@ possible secret size.
 
 =back
 
+OP_keyexch_settable_ctx_params() gets a constant B<OSSL_PARAM> array that
+decribes the settable parameters, i.e. parameters that can be used with
+OP_signature_set_ctx_params().
+See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
+
 =head1 RETURN VALUES
 
 OP_keyexch_newctx() and OP_keyexch_dupctx() should return the newly created
diff --git a/doc/man7/provider-signature.pod b/doc/man7/provider-signature.pod
index 3894afd03c..1ab4831035 100644
--- a/doc/man7/provider-signature.pod
+++ b/doc/man7/provider-signature.pod
@@ -39,8 +39,10 @@ provider-signature - The signature library E<lt>-E<gt> provider functions
                                  const unsigned char *sig, size_t siglen);
 
  /* Signature parameters */
- int OP_signature_set_params(void *ctx, const OSSL_PARAM params[]);
-
+ int OP_signature_get_ctx_params(void *ctx, OSSL_PARAM params[]);
+ const OSSL_PARAM *OP_signature_gettable_ctx_params(void);
+ int OP_signature_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
+ const OSSL_PARAM *OP_signature_settable_ctx_params(void);
 
 =head1 DESCRIPTION
 
@@ -86,7 +88,10 @@ macros in L<openssl-core_numbers.h(7)>, as follows:
  OP_signature_verify_recover_init    OSSL_FUNC_SIGNATURE_VERIFY_RECOVER_INIT
  OP_signature_verify_recover         OSSL_FUNC_SIGNATURE_VERIFY_RECOVER
 
- OP_signature_set_params             OSSL_FUNC_SIGNATURE_SET_PARAMS
+ OP_signature_get_ctx_params         OSSL_FUNC_SIGNATURE_GET_CTX_PARAMS
+ OP_signature_gettable_ctx_params    OSSL_FUNC_SIGNATURE_GETTABLE_CTX_PARAMS
+ OP_signature_set_ctx_params         OSSL_FUNC_SIGNATURE_SET_CTX_PARAMS
+ OP_signature_settable_ctx_params    OSSL_FUNC_SIGNATURE_SETTABLE_CTX_PARAMS
 
 A signature algorithm implementation may not implement all of these functions.
 In order to be a consistent set of functions a provider must implement
@@ -174,10 +179,12 @@ the B<routlen> parameter.
 =head2 Signature Parameters
 
 See L<OSSL_PARAM(3)> for further details on the parameters structure used by
-the OP_signature_set_params() function.
+the OP_signature_get_ctx_params() and OP_signature_set_ctx_params() functions.
 
-OP_signature_set_params() sets signature parameters associated with the given
-provider side key exchange context B<ctx> to B<params>.
+OP_signature_get_ctx_params() gets signature parameters associated with the
+given provider side signature context B<ctx> and stored them in B<params>.
+OP_signature_set_ctx_params() sets the signature parameters associated with the
+given provider side signature context B<ctx> to B<params>.
 Any parameter settings are additional to any that were previously set.
 
 Parameters currently recognised by built-in signature algorithms are as
@@ -187,27 +194,30 @@ algorithms:
 
 =over 4
 
-=item B<OSSL_SIGNATURE_PARAM_DIGEST> (UTF8 string)
+=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <utf8 string>
 
-Sets the name of the digest algorithm used for the input to the signature
+Get or sets the name of the digest algorithm used for the input to the signature
 functions.
 
-=item B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE> (size_t)
+=item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <size_t>
 
-Sets the output size of the digest algorithm used for the input to the signature
-functions.
+Gets or sets the output size of the digest algorithm used for the input to the
+signature functions.
 
 =back
 
+OP_signature_gettable_ctx_params() and OP_signature_settable_ctx_params() get a
+constant B<OSSL_PARAM> array that decribes the gettable and settable parameters,
+i.e. parameters that can be used with OP_signature_get_ctx_params() and
+OP_signature_set_ctx_params() respectively.
+See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
+
 =head1 RETURN VALUES
 
 OP_signature_newctx() and OP_signature_dupctx() should return the newly created
 provider side signature, or NULL on failure.
 
-OP_signature_sign_init(), OP_signature_sign(), OP_signature_verify_init(),
-OP_signature_verify(), OP_signature_verify_recover_init(),
-OP_signature_verify_recover() and OP_signature_set_params() should return 1 for
-success or 0 on error.
+All other functions should return 1 for success or 0 on error.
 
 =head1 SEE ALSO