3cd5aeb3cc
The details for RSA and EdDSA have already been documented, albeit the RSA documentation wasn't conforming properly to the POD format. Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/25422)
203 lines
6.4 KiB
Plaintext
203 lines
6.4 KiB
Plaintext
=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 Algorithm Names
|
|
|
|
In this list, names are grouped together to signify that they are the same
|
|
algorithm having multiple names. This also includes the OID in canonical
|
|
decimal form (which means that they are possible to fetch if the caller has a
|
|
mere OID which came out in this form after a call to L<OBJ_obj2txt(3)>).
|
|
|
|
=over 4
|
|
|
|
=item "RSA", "rsaEncryption", "1.2.840.113549.1.1.1"
|
|
|
|
The base signature algorithm, supported explicitly fetched with
|
|
L<EVP_PKEY_sign_init_ex2(3)>, and implicitly fetched (through
|
|
L<RSA keys|EVP_PKEY-RSA(7)>) with L<EVP_DigestSignInit(3)> and
|
|
L<EVP_DigestVerifyInit(3)>.
|
|
|
|
It can't be used with L<EVP_PKEY_sign_message_init(3)>
|
|
|
|
=item "RSA-RIPEMD160", "ripemd160WithRSA", "1.3.36.3.3.1.2"
|
|
|
|
=item "RSA-SHA2-256", "RSA-SHA256", "sha256WithRSAEncryption", "1.2.840.113549.1.1.11"
|
|
|
|
=item "RSA-SHA2-384", "RSA-SHA384", "sha384WithRSAEncryption", "1.2.840.113549.1.1.12"
|
|
|
|
=item "RSA-SHA2-512", "RSA-SHA512", "sha512WithRSAEncryption", "1.2.840.113549.1.1.13"
|
|
|
|
=item "RSA-SHA2-224", "RSA-SHA224", "sha224WithRSAEncryption", "1.2.840.113549.1.1.14"
|
|
|
|
=item "RSA-SHA2-512/224", "RSA-SHA512-224", "sha512-224WithRSAEncryption", "1.2.840.113549.1.1.15"
|
|
|
|
=item "RSA-SHA2-512/256", "RSA-SHA512-256", "sha512-256WithRSAEncryption", "1.2.840.113549.1.1.16"
|
|
|
|
=item "RSA-SHA3-224", "id-rsassa-pkcs1-v1_5-with-sha3-224", "2.16.840.1.101.3.4.3.13"
|
|
|
|
=item "RSA-SHA3-256", "id-rsassa-pkcs1-v1_5-with-sha3-256", "2.16.840.1.101.3.4.3.14"
|
|
|
|
=item "RSA-SHA3-384", "id-rsassa-pkcs1-v1_5-with-sha3-384", "2.16.840.1.101.3.4.3.15"
|
|
|
|
=item "RSA-SHA3-512", "id-rsassa-pkcs1-v1_5-with-sha3-512", "2.16.840.1.101.3.4.3.16"
|
|
|
|
=item "RSA-SM3", "sm3WithRSAEncryption", "1.2.156.10197.1.504"
|
|
|
|
PKCS#1 v1.5 RSA signature schemes with diverse message digest algorithms. They
|
|
are all supported explicitly fetched with L<EVP_PKEY_sign_init_ex2(3)> and
|
|
L<EVP_PKEY_sign_message_init(3)>.
|
|
They are all pre-set to use the pad mode "pkcs1". This cannot be changed.
|
|
|
|
=back
|
|
|
|
=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(),
|
|
and before calling EVP_PKEY_sign() or EVP_PKEY_verify(). They may also be set
|
|
using EVP_PKEY_sign_init_ex() or EVP_PKEY_verify_init_ex().
|
|
|
|
=over 4
|
|
|
|
=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
|
|
|
|
=item "properties" (B<OSSL_SIGNATURE_PARAM_PROPERTIES>) <UTF8 string>
|
|
|
|
These are not supported with the RSA signature schemes that already include a
|
|
message digest algorithm, See L</Algorithm Names> above.
|
|
|
|
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>)
|
|
|
|
=item "pkcs1" (B<OSSL_PKEY_RSA_PAD_MODE_PKCSV15>)
|
|
|
|
=item "x931" (B<OSSL_PKEY_RSA_PAD_MODE_X931>)
|
|
|
|
This padding mode is no longer supported by the FIPS provider for signature
|
|
generation, but may be used for signature verification for legacy use cases.
|
|
(This is a FIPS 140-3 requirement)
|
|
|
|
=item "pss" (B<OSSL_PKEY_RSA_PAD_MODE_PSS>)
|
|
|
|
=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.
|
|
|
|
=item "saltlen" (B<OSSL_SIGNATURE_PARAM_PSS_SALTLEN>) <integer> or <UTF8 string>
|
|
|
|
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:
|
|
|
|
=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.
|
|
|
|
=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.
|
|
|
|
=back
|
|
|
|
=back
|
|
|
|
The OpenSSL FIPS provider also supports the following parameters:
|
|
|
|
=over 4
|
|
|
|
=item "key-check" (B<OSSL_SIGNATURE_PARAM_FIPS_KEY_CHECK>) <integer>
|
|
|
|
=item "digest-check" (B<OSSL_SIGNATURE_PARAM_FIPS_DIGEST_CHECK>) <integer>
|
|
|
|
=item "sign-x931-pad-check" (B<OSSL_SIGNATURE_PARAM_FIPS_SIGN_X931_PAD_CHECK>) <integer>
|
|
|
|
These parameters are described in L<provider-signature(7)>.
|
|
|
|
=item "rsa-pss-saltlen-check" (B<OSSL_SIGNATURE_PARAM_FIPS_RSA_PSS_SALTLEN_CHECK>) <integer>
|
|
|
|
The default value of 1 causes an error during signature generation or
|
|
verification if salt length (B<OSSL_SIGNATURE_PARAM_PSS_SALTLEN>) is not between
|
|
zero and the output block size of the digest function (inclusive).
|
|
Setting this to zero will ignore the error and set the approved "fips-indicator"
|
|
to 0.
|
|
This option breaks FIPS compliance if it causes the approved "fips-indicator"
|
|
to return 0.
|
|
|
|
=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>
|
|
|
|
=item "fips-indicator" (B<OSSL_SIGNATURE_PARAM_FIPS_APPROVED_INDICATOR>) <integer>
|
|
|
|
=item "verify-message" (B<OSSL_SIGNATURE_PARAM_FIPS_VERIFY_MESSAGE> <integer>
|
|
|
|
These common parameter are 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>
|
|
|
|
=item "saltlen" (B<OSSL_SIGNATURE_PARAM_PSS_SALTLEN>) <integer> or <UTF8 string>
|
|
|
|
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
|
|
|
|
Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
|
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
|