2020-05-26 11:53:07 +08:00
|
|
|
=pod
|
|
|
|
|
|
|
|
=head1 NAME
|
|
|
|
|
|
|
|
EVP_SIGNATURE-RSA
|
|
|
|
- The EVP_PKEY RSA signature implementation
|
|
|
|
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
|
|
|
|
Support for computing RSA signatures.
|
|
|
|
See L<EVP_PKEY-RSA(7)> for information related to RSA keys.
|
|
|
|
|
|
|
|
=head2 Signature Parameters
|
|
|
|
|
|
|
|
The following signature parameters can be set using EVP_PKEY_CTX_set_params().
|
|
|
|
This may be called after EVP_PKEY_sign_init() or EVP_PKEY_verify_init(),
|
2021-09-21 08:59:56 +08:00
|
|
|
and before calling EVP_PKEY_sign() or EVP_PKEY_verify().
|
2020-05-26 11:53:07 +08:00
|
|
|
|
|
|
|
=over 4
|
|
|
|
|
|
|
|
=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
|
|
|
|
|
|
|
|
=item "properties" (B<OSSL_SIGNATURE_PARAM_PROPERTIES>) <UTF8 string>
|
|
|
|
|
|
|
|
These common parameters are described in L<provider-signature(7)>.
|
|
|
|
|
|
|
|
=item "pad-mode" (B<OSSL_SIGNATURE_PARAM_PAD_MODE>) <UTF8 string>
|
|
|
|
|
|
|
|
The type of padding to be used. Its value can be one of the following:
|
|
|
|
|
|
|
|
=over 4
|
|
|
|
|
|
|
|
=item "none" (B<OSSL_PKEY_RSA_PAD_MODE_NONE>)
|
|
|
|
|
2021-09-21 08:59:56 +08:00
|
|
|
=item "pkcs1" (B<OSSL_PKEY_RSA_PAD_MODE_PKCSV15>)
|
2020-05-26 11:53:07 +08:00
|
|
|
|
|
|
|
=item "x931" (B<OSSL_PKEY_RSA_PAD_MODE_X931>)
|
|
|
|
|
2021-09-21 08:59:56 +08:00
|
|
|
=item "pss" (B<OSSL_PKEY_RSA_PAD_MODE_PSS>)
|
2020-05-26 11:53:07 +08:00
|
|
|
|
|
|
|
=back
|
|
|
|
|
|
|
|
=item "mgf1-digest" (B<OSSL_SIGNATURE_PARAM_MGF1_DIGEST>) <UTF8 string>
|
|
|
|
|
|
|
|
The digest algorithm name to use for the maskGenAlgorithm used by "pss" mode.
|
|
|
|
|
|
|
|
=item "mgf1-properties" (B<OSSL_SIGNATURE_PARAM_MGF1_PROPERTIES>) <UTF8 string>
|
|
|
|
|
|
|
|
Sets the name of the property query associated with the "mgf1-digest" algorithm.
|
|
|
|
NULL is used if this optional value is not set.
|
|
|
|
|
2022-07-07 05:26:16 +08:00
|
|
|
=item "saltlen" (B<OSSL_SIGNATURE_PARAM_PSS_SALTLEN>) <integer> or <UTF8 string>
|
2020-05-26 11:53:07 +08:00
|
|
|
|
2022-07-07 05:26:16 +08:00
|
|
|
The "pss" mode minimum salt length. The value can either be an integer,
|
|
|
|
a string value representing a number or one of the following string values:
|
2020-05-26 11:53:07 +08:00
|
|
|
|
|
|
|
=over 4
|
|
|
|
|
|
|
|
=item "digest" (B<OSSL_PKEY_RSA_PSS_SALT_LEN_DIGEST>)
|
|
|
|
|
|
|
|
Use the same length as the digest size.
|
|
|
|
|
|
|
|
=item "max" (B<OSSL_PKEY_RSA_PSS_SALT_LEN_MAX>)
|
|
|
|
|
|
|
|
Use the maximum salt length.
|
|
|
|
|
|
|
|
=item "auto" (B<OSSL_PKEY_RSA_PSS_SALT_LEN_AUTO>)
|
|
|
|
|
|
|
|
Auto detect the salt length.
|
|
|
|
|
signature: Clamp PSS salt len to MD len
FIPS 186-4 section 5 "The RSA Digital Signature Algorithm", subsection
5.5 "PKCS #1" says: "For RSASSA-PSS […] the length (in bytes) of the
salt (sLen) shall satisfy 0 <= sLen <= hLen, where hLen is the length of
the hash function output block (in bytes)."
Introduce a new option RSA_PSS_SALTLEN_AUTO_DIGEST_MAX and make it the
default. The new value will behave like RSA_PSS_SALTLEN_AUTO, but will
not use more than the digest length when signing, so that FIPS 186-4 is
not violated. This value has two advantages when compared with
RSA_PSS_SALTLEN_DIGEST: (1) It will continue to do auto-detection when
verifying signatures for maximum compatibility, where
RSA_PSS_SALTLEN_DIGEST would fail for other digest sizes. (2) It will
work for combinations where the maximum salt length is smaller than the
digest size, which typically happens with large digest sizes (e.g.,
SHA-512) and small RSA keys.
J.-S. Coron shows in "Optimal Security Proofs for PSS and Other
Signature Schemes. Advances in Cryptology – Eurocrypt 2002, volume 2332
of Lecture Notes in Computer Science, pp. 272 – 287. Springer Verlag,
2002." that longer salts than the output size of modern hash functions
do not increase security: "For example,for an application in which at
most one billion signatures will be generated, k0 = 30 bits of random
salt are actually sufficient to guarantee the same level of security as
RSA, and taking a larger salt does not increase the security level."
Signed-off-by: Clemens Lang <cllang@redhat.com>
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/19724)
2022-11-18 19:35:33 +08:00
|
|
|
=item "auto-digestmax" (B<OSSL_PKEY_RSA_PSS_SALT_LEN_AUTO_DIGEST_MAX>)
|
|
|
|
|
|
|
|
Auto detect the salt length when verifying. Maximize the salt length up to the
|
|
|
|
digest size when signing to comply with FIPS 186-4 section 5.5.
|
|
|
|
|
2020-05-26 11:53:07 +08:00
|
|
|
=back
|
|
|
|
|
|
|
|
=back
|
|
|
|
|
|
|
|
The following signature parameters can be retrieved using
|
|
|
|
EVP_PKEY_CTX_get_params().
|
|
|
|
|
|
|
|
=over 4
|
|
|
|
|
|
|
|
=item "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string>
|
|
|
|
|
|
|
|
This common parameter is described in L<provider-signature(7)>.
|
|
|
|
|
|
|
|
=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
|
|
|
|
|
|
|
|
=item "pad-mode" (B<OSSL_SIGNATURE_PARAM_PAD_MODE>) <UTF8 string>
|
|
|
|
|
|
|
|
=item "mgf1-digest" (B<OSSL_SIGNATURE_PARAM_MGF1_DIGEST>) <UTF8 string>
|
|
|
|
|
2022-07-07 05:26:16 +08:00
|
|
|
=item "saltlen" (B<OSSL_SIGNATURE_PARAM_PSS_SALTLEN>) <integer> or <UTF8 string>
|
|
|
|
|
2020-05-26 11:53:07 +08:00
|
|
|
These parameters are as described above.
|
|
|
|
|
|
|
|
=back
|
|
|
|
|
|
|
|
=head1 SEE ALSO
|
|
|
|
|
|
|
|
L<EVP_PKEY_CTX_set_params(3)>,
|
|
|
|
L<EVP_PKEY_sign(3)>,
|
|
|
|
L<EVP_PKEY_verify(3)>,
|
|
|
|
L<provider-signature(7)>,
|
|
|
|
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
|
2021-03-11 21:27:36 +08:00
|
|
|
Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
|
2020-05-26 11:53:07 +08:00
|
|
|
|
|
|
|
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>.
|
|
|
|
|
|
|
|
=cut
|