=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
+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
+- EVP_PKEY RSA-PSS algorithm support functions
=head1 SYNOPSIS
=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.
+These are the functions that implement L<RSA-PSS(7)>.
-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.
+=head2 Signing and Verification
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 restrictionsthen an error is returned if an attempt is
+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 special negative values are not supported.
+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
digest to anything other than the restricted value. Otherwise these are
similar to the B<RSA> versions.
-=head1 KEY GENERATION
+=head2 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:
+As with RSA key generation the EVP_PKEY_CTX_set_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.
+Optional parameter restrictions can be specified when generating a PSS 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_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);
+
=head1 RETURN VALUES
All these functions return 1 for success and 0 or a negative value for failure.
=head1 SEE ALSO
+L<RSA-PSS(7)>,
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.
+Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
-Licensed under the OpenSSL license (the "License"). You may not use
+Licensed under the Apache License 2.0 (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>.
projects / openssl.git / blobdiff