+++ /dev/null
-=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 in use has parameter restrictions 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 has usage restrictions then an error is returned if an attempt is
-made to set the salt length below the minimum value. It is otherwise similar
-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
-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 the generated key. If any
-restrictions are set (using the macros described below) then B<all> parameters
-are restricted. For example, 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 2017 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
--- /dev/null
+=pod
+
+=head1 NAME
+
+RSA-PSS - EVP_PKEY RSA-PSS algorithm support
+
+=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<RSA-PSS> EVP_PKEY implementation 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 in use has parameter restrictions 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 has usage restrictions then an error is returned if an attempt is
+made to set the salt length below the minimum value. It is otherwise similar
+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
+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 the generated key. If any
+restrictions are set (using the macros described below) then B<all> parameters
+are restricted. For example, 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 NOTES
+
+A context for the B<RSA-PSS> algorithm can be obtained by calling:
+
+ EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA_PSS, NULL);
+
+The public key format is documented in RFC4055.
+
+The PKCS#8 private key format used for RSA-PSS keys is similar to the RSA
+format except it uses the B<id-RSASSA-PSS> OID and the parameters field, if
+present, restricts the key parameters in the same way as the public key.
+
+=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 2017 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
projects / oweals / openssl.git / commitdiff