Add public API docs for newly added EVP_SIGNATURE related functions

[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 e09a2fe7c2daf15ddb7a9b4666221b9b529a8f3d..9d1812f6bd65a38e7855a7433d5bd8edd8342ed8 100644 (file)
--- a/doc/man3/EVP_PKEY_CTX_ctrl.pod
+++ b/doc/man3/EVP_PKEY_CTX_ctrl.pod
@@ -2,6 +2,7 @@
 
 =head1 NAME
 
+EVP_PKEY_CTX_set_params,
 EVP_PKEY_CTX_ctrl,
 EVP_PKEY_CTX_ctrl_str,
 EVP_PKEY_CTX_ctrl_uint64,
@@ -23,6 +24,8 @@ EVP_PKEY_CTX_get_rsa_oaep_md,
 EVP_PKEY_CTX_set0_rsa_oaep_label,
 EVP_PKEY_CTX_get0_rsa_oaep_label,
 EVP_PKEY_CTX_set_dsa_paramgen_bits,
+EVP_PKEY_CTX_set_dsa_paramgen_q_bits,
+EVP_PKEY_CTX_set_dsa_paramgen_md,
 EVP_PKEY_CTX_set_dh_paramgen_prime_len,
 EVP_PKEY_CTX_set_dh_paramgen_subprime_len,
 EVP_PKEY_CTX_set_dh_paramgen_generator,
@@ -60,6 +63,8 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
 
  #include <openssl/evp.h>
 
+ int EVP_PKEY_CTX_set_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params);
+
  int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype,
                        int cmd, int p1, void *p2);
  int EVP_PKEY_CTX_ctrl_uint64(EVP_PKEY_CTX *ctx, int keytype, int optype,
@@ -72,7 +77,8 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
  int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
  int EVP_PKEY_CTX_get_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD **pmd);
 
- int EVP_PKEY_CTX_set_mac_key(EVP_PKEY_CTX *ctx, unsigned char *key, int len);
+ int EVP_PKEY_CTX_set_mac_key(EVP_PKEY_CTX *ctx, const unsigned char *key,
+                              int len);
 
  #include <openssl/rsa.h>
 
@@ -93,6 +99,8 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
  #include <openssl/dsa.h>
 
  int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits);
+ int EVP_PKEY_CTX_set_dsa_paramgen_q_bits(EVP_PKEY_CTX *ctx, int qbits);
+ int EVP_PKEY_CTX_set_dsa_paramgen_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
 
  #include <openssl/dh.h>
 
@@ -136,6 +144,36 @@ 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.
+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.
+The parameters currently supported by the default provider are:
+
+=over 4
+
+=item OSSL_EXCHANGE_PARAM_PAD (uint type)
+
+Sets the DH padding mode.
+If B<OSSL_EXCHANGE_PARAM_PAD> is 1 then the  shared secret is padded with zeroes
+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)
+
+Sets the name of the digest algorithm used for the input to the signature
+functions.
+
+=item OSSL_SIGNATURE_PARAM_DIGEST_SIZE (size_t type)
+
+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 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.
@@ -255,7 +293,17 @@ by the library and should not be freed by the caller.
 =head2 DSA parameters
 
 The EVP_PKEY_CTX_set_dsa_paramgen_bits() macro sets the number of bits used
-for DSA parameter generation to B<bits>. If not specified 1024 is used.
+for DSA parameter generation to B<nbits>. If not specified, 1024 is used.
+
+The EVP_PKEY_CTX_set_dsa_paramgen_q_bits() macro sets the number of bits in the
+subprime parameter B<q> for DSA parameter generation to B<qbits>. If not
+specified, 160 is used. If a digest function is specified below, this parameter
+is ignored and instead, the number of bits in B<q> matches the size of the
+digest.
+
+The EVP_PKEY_CTX_set_dsa_paramgen_md() macro sets the digest function used for
+DSA parameter generation to B<md>. If not specified, one of SHA-1, SHA-224, or
+SHA-256 is selected to match the bit length of B<q> above.
 
 =head2 DH parameters
 
@@ -275,8 +323,9 @@ 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.
 
-The EVP_PKEY_CTX_set_dh_pad() macro sets the DH padding mode. If B<pad> is
-1 the shared secret is padded with zeroes up to the size of the DH prime B<p>.
+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
+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
@@ -443,6 +492,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.
+
 =head1 COPYRIGHT
 
 Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.