1=pod 2 3=head1 NAME 4 5EVP_SIGNATURE-RSA 6- The EVP_PKEY RSA signature implementation 7 8=head1 DESCRIPTION 9 10Support for computing RSA signatures. 11See L<EVP_PKEY-RSA(7)> for information related to RSA keys. 12 13=head2 Algorithm Names 14 15In this list, names are grouped together to signify that they are the same 16algorithm having multiple names. This also includes the OID in canonical 17decimal form (which means that they are possible to fetch if the caller has a 18mere OID which came out in this form after a call to L<OBJ_obj2txt(3)>). 19 20=over 4 21 22=item "RSA", "rsaEncryption", "1.2.840.113549.1.1.1" 23 24The base signature algorithm, supported explicitly fetched with 25L<EVP_PKEY_sign_init_ex2(3)>, and implicitly fetched (through 26L<RSA keys|EVP_PKEY-RSA(7)>) with L<EVP_DigestSignInit(3)> and 27L<EVP_DigestVerifyInit(3)>. 28 29It can't be used with L<EVP_PKEY_sign_message_init(3)> 30 31=item "RSA-RIPEMD160", "ripemd160WithRSA", "1.3.36.3.3.1.2" 32 33=item "RSA-SHA2-256", "RSA-SHA256", "sha256WithRSAEncryption", "1.2.840.113549.1.1.11" 34 35=item "RSA-SHA2-384", "RSA-SHA384", "sha384WithRSAEncryption", "1.2.840.113549.1.1.12" 36 37=item "RSA-SHA2-512", "RSA-SHA512", "sha512WithRSAEncryption", "1.2.840.113549.1.1.13" 38 39=item "RSA-SHA2-224", "RSA-SHA224", "sha224WithRSAEncryption", "1.2.840.113549.1.1.14" 40 41=item "RSA-SHA2-512/224", "RSA-SHA512-224", "sha512-224WithRSAEncryption", "1.2.840.113549.1.1.15" 42 43=item "RSA-SHA2-512/256", "RSA-SHA512-256", "sha512-256WithRSAEncryption", "1.2.840.113549.1.1.16" 44 45=item "RSA-SHA3-224", "id-rsassa-pkcs1-v1_5-with-sha3-224", "2.16.840.1.101.3.4.3.13" 46 47=item "RSA-SHA3-256", "id-rsassa-pkcs1-v1_5-with-sha3-256", "2.16.840.1.101.3.4.3.14" 48 49=item "RSA-SHA3-384", "id-rsassa-pkcs1-v1_5-with-sha3-384", "2.16.840.1.101.3.4.3.15" 50 51=item "RSA-SHA3-512", "id-rsassa-pkcs1-v1_5-with-sha3-512", "2.16.840.1.101.3.4.3.16" 52 53=item "RSA-SM3", "sm3WithRSAEncryption", "1.2.156.10197.1.504" 54 55PKCS#1 v1.5 RSA signature schemes with diverse message digest algorithms. They 56are all supported explicitly fetched with L<EVP_PKEY_sign_init_ex2(3)> and 57L<EVP_PKEY_sign_message_init(3)>. 58They are all pre-set to use the pad mode "pkcs1". This cannot be changed. 59 60=back 61 62=head2 Signature Parameters 63 64The following signature parameters can be set using EVP_PKEY_CTX_set_params(). 65This may be called after EVP_PKEY_sign_init() or EVP_PKEY_verify_init(), 66and before calling EVP_PKEY_sign() or EVP_PKEY_verify(). They may also be set 67using EVP_PKEY_sign_init_ex() or EVP_PKEY_verify_init_ex(). 68 69=over 4 70 71=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string> 72 73=item "properties" (B<OSSL_SIGNATURE_PARAM_PROPERTIES>) <UTF8 string> 74 75These are not supported with the RSA signature schemes that already include a 76message digest algorithm, See L</Algorithm Names> above. 77 78These common parameters are described in L<provider-signature(7)>. 79 80=item "pad-mode" (B<OSSL_SIGNATURE_PARAM_PAD_MODE>) <UTF8 string> 81 82The type of padding to be used. Its value can be one of the following: 83 84=over 4 85 86=item "none" (B<OSSL_PKEY_RSA_PAD_MODE_NONE>) 87 88=item "pkcs1" (B<OSSL_PKEY_RSA_PAD_MODE_PKCSV15>) 89 90=item "x931" (B<OSSL_PKEY_RSA_PAD_MODE_X931>) 91 92This padding mode is no longer supported by the FIPS provider for signature 93generation, but may be used for signature verification for legacy use cases. 94(This is a FIPS 140-3 requirement) 95 96=item "pss" (B<OSSL_PKEY_RSA_PAD_MODE_PSS>) 97 98=back 99 100=item "mgf1-digest" (B<OSSL_SIGNATURE_PARAM_MGF1_DIGEST>) <UTF8 string> 101 102The digest algorithm name to use for the maskGenAlgorithm used by "pss" mode. 103 104=item "mgf1-properties" (B<OSSL_SIGNATURE_PARAM_MGF1_PROPERTIES>) <UTF8 string> 105 106Sets the name of the property query associated with the "mgf1-digest" algorithm. 107NULL is used if this optional value is not set. 108 109=item "saltlen" (B<OSSL_SIGNATURE_PARAM_PSS_SALTLEN>) <integer> or <UTF8 string> 110 111The "pss" mode minimum salt length. The value can either be an integer, 112a string value representing a number or one of the following string values: 113 114=over 4 115 116=item "digest" (B<OSSL_PKEY_RSA_PSS_SALT_LEN_DIGEST>) 117 118Use the same length as the digest size. 119 120=item "max" (B<OSSL_PKEY_RSA_PSS_SALT_LEN_MAX>) 121 122Use the maximum salt length. 123 124=item "auto" (B<OSSL_PKEY_RSA_PSS_SALT_LEN_AUTO>) 125 126Auto detect the salt length. 127 128=item "auto-digestmax" (B<OSSL_PKEY_RSA_PSS_SALT_LEN_AUTO_DIGEST_MAX>) 129 130Auto detect the salt length when verifying. Maximize the salt length up to the 131digest size when signing to comply with FIPS 186-4 section 5.5. 132 133=back 134 135=back 136 137The OpenSSL FIPS provider also supports the following parameters: 138 139=over 4 140 141=item "key-check" (B<OSSL_SIGNATURE_PARAM_FIPS_KEY_CHECK>) <integer> 142 143=item "digest-check" (B<OSSL_SIGNATURE_PARAM_FIPS_DIGEST_CHECK>) <integer> 144 145=item "sign-x931-pad-check" (B<OSSL_SIGNATURE_PARAM_FIPS_SIGN_X931_PAD_CHECK>) <integer> 146 147These parameters are described in L<provider-signature(7)>. 148 149=item "rsa-pss-saltlen-check" (B<OSSL_SIGNATURE_PARAM_FIPS_RSA_PSS_SALTLEN_CHECK>) <integer> 150 151The default value of 1 causes an error during signature generation or 152verification if salt length (B<OSSL_SIGNATURE_PARAM_PSS_SALTLEN>) is not between 153zero and the output block size of the digest function (inclusive). 154Setting this to zero will ignore the error and set the approved "fips-indicator" 155to 0. 156This option breaks FIPS compliance if it causes the approved "fips-indicator" 157to return 0. 158 159=back 160 161The following signature parameters can be retrieved using 162EVP_PKEY_CTX_get_params(). 163 164=over 4 165 166=item "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string> 167 168=item "fips-indicator" (B<OSSL_SIGNATURE_PARAM_FIPS_APPROVED_INDICATOR>) <integer> 169 170=item "verify-message" (B<OSSL_SIGNATURE_PARAM_FIPS_VERIFY_MESSAGE> <integer> 171 172These common parameter are described in L<provider-signature(7)>. 173 174=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string> 175 176=item "pad-mode" (B<OSSL_SIGNATURE_PARAM_PAD_MODE>) <UTF8 string> 177 178=item "mgf1-digest" (B<OSSL_SIGNATURE_PARAM_MGF1_DIGEST>) <UTF8 string> 179 180=item "saltlen" (B<OSSL_SIGNATURE_PARAM_PSS_SALTLEN>) <integer> or <UTF8 string> 181 182These parameters are as described above. 183 184=back 185 186=head1 SEE ALSO 187 188L<EVP_PKEY_CTX_set_params(3)>, 189L<EVP_PKEY_sign(3)>, 190L<EVP_PKEY_verify(3)>, 191L<provider-signature(7)>, 192 193=head1 COPYRIGHT 194 195Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved. 196 197Licensed under the Apache License 2.0 (the "License"). You may not use 198this file except in compliance with the License. You can obtain a copy 199in the file LICENSE in the source distribution or at 200L<https://www.openssl.org/source/license.html>. 201 202=cut 203
