From: Dr. Stephen Henson <steve@openssl.org>
Date: Fri, 6 Jan 2017 14:41:04 +0000 (+0000)
Subject: Add documentation for PSS control operations.
X-Git-Tag: OpenSSL_1_1_1-pre1~2751
X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=commitdiff_plain;h=c916505092fd92773d481e3fb29d6575f8f66278;hp=bc1ea030eff79c592250f1a2eed8dc7879217218

Add documentation for PSS control operations.

Reviewed-by: Rich Salz <rsalz@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/2177)
---

diff --git a/doc/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md.pod b/doc/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md.pod
new file mode 100644
index 0000000000..6607bdf8a6
--- /dev/null
+++ b/doc/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md.pod
@@ -0,0 +1,99 @@
+=pod
+
+=head1 NAME
+
+EVP_PKEY_CTX_set_rsa_pss_keygen_md, EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md,
+EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen - RSA PSS signature algorithm
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int EVP_PKEY_CTX_set_rsa_pss_keygen_md(EVP_PKEY_CTX *pctx,
+                                        const EVP_MD *md);
+ int EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md(EVP_PKEY_CTX *pctx,
+                                             const EVP_MD *md);
+ int EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen(EVP_PKEY_CTX *pctx,
+                                             int saltlen);
+
+=head1 DESCRIPTION
+
+The B<EVP_PKEY_RSA_PSS> algorithm implements the RSA PSS signature algorithm.
+It is a restricted version of the RSA algorithm which only supports signing,
+verification and key generation using PSS padding modes with optional
+parameter restrictions.
+
+It has associated private key and public key formats.
+
+This algorithm shares several control operations with the B<RSA> algorithm
+but with some restrictions described below.
+
+=head1 SIGNING AND VERIFICATION
+
+Siging and verification is similar to the B<RSA> algorithm except the
+padding mode is always PSS. If the key used restricts parameters then
+the corresponding signature parameters are set to the restrictions:
+for example if the key can only be used with digest SHA256, MGF1 SHA256
+and minimum salt length 32 then the digest, MGF1 digest and salt length
+will be set to SHA256, SHA256 and 32 respectively.
+
+The macro EVP_PKEY_CTX_set_rsa_padding() is supported but an error is
+returned if an attempt is made to set the padding mode to anything other
+than B<PSS>. It is otherwise similar to the B<RSA> version.
+
+The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro is used to set the salt length.
+If the key is restricted then an error is returned if an attempt is made
+to set the salt below the minimum value. It is otherwise similar to the
+B<RSA> operation except special negative values are not supported.
+
+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 is
+restricted 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.
+
+=head1 KEY GENERATION
+
+As with RSA key generation the EVP_PKEY_CTX_set_rsa_rsa_keygen_bits()
+and EVP_PKEY_CTX_set_rsa_keygen_pubexp() macros are supported for RSA PSS:
+they have exactly the same meaning as for the RSA algorithm.
+
+Optional parameter restrictions can be specified when generating a PSS key
+by default no parameter restrictions are placed on a generate key. If any
+restrictions are set (using the macros described below) then B<all>
+parameters are restricted: e.g. setting a minimum salt length also restricts
+the digest and MGF1 algorithms. If any restrictions are in place then
+they are reflected in the corresponding parameters of the public key
+when (for example) a certificate request is signed.
+
+EVP_PKEY_CTX_set_rsa_pss_keygen_md() restricts the digest algorithm the
+generated key can use to B<md>.
+
+EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md() restricts the MGF1 algorithm the
+generated key can use to B<md>.
+
+EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen() restricts the minimum salt length
+to B<saltlen>.
+
+=head1 RETURN VALUES
+
+All these functions return 1 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
+
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_CTX_ctrl_str(3)>,
+L<EVP_PKEY_derive(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut