Revise EVP_PKEY param handling

[oweals/openssl.git] / doc / man3 / EVP_PKEY_CTX_ctrl.pod

diff --git a/doc/man3/EVP_PKEY_CTX_ctrl.pod b/doc/man3/EVP_PKEY_CTX_ctrl.pod
index 9d1812f6bd65a38e7855a7433d5bd8edd8342ed8..18b984162e5709dbaeacc57595ae092b00315462 100644 (file)
--- a/doc/man3/EVP_PKEY_CTX_ctrl.pod
+++ b/doc/man3/EVP_PKEY_CTX_ctrl.pod
@@ -2,7 +2,10 @@
 
 =head1 NAME
 
 
 =head1 NAME
 

+EVP_PKEY_CTX_get_params,
+EVP_PKEY_CTX_gettable_params,

 EVP_PKEY_CTX_set_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,
 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>
 
 
  #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);
  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);
 
  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
 
 
 =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.
 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
 
 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
 
 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.
 
 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
 
 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.
 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>.
 
 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.
 
 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
 
 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
 
 
 =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
 
 
 =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_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
 
 
 =head1 COPYRIGHT