| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | EVP_SIGNATURE-DSA
|
|---|
| 6 | - The B<EVP_PKEY> DSA signature implementation
|
|---|
| 7 |
|
|---|
| 8 | =head1 DESCRIPTION
|
|---|
| 9 |
|
|---|
| 10 | Support for computing DSA signatures. The signature produced with
|
|---|
| 11 | L<EVP_PKEY_sign(3)> is DER encoded ASN.1 in the form described in
|
|---|
| 12 | RFC 3279, section 2.2.2.
|
|---|
| 13 | See L<EVP_PKEY-DSA(7)> for information related to DSA keys.
|
|---|
| 14 |
|
|---|
| 15 | As part of FIPS 140-3 DSA is not longer FIPS approved for key generation and
|
|---|
| 16 | signature validation, but is still allowed for signature verification.
|
|---|
| 17 |
|
|---|
| 18 | =head2 Algorithm Names
|
|---|
| 19 |
|
|---|
| 20 | In this list, names are grouped together to signify that they are the same
|
|---|
| 21 | algorithm having multiple names. This also includes the OID in canonical
|
|---|
| 22 | decimal form (which means that they are possible to fetch if the caller has a
|
|---|
| 23 | mere OID which came out in this form after a call to L<OBJ_obj2txt(3)>).
|
|---|
| 24 |
|
|---|
| 25 | =over 4
|
|---|
| 26 |
|
|---|
| 27 | =item "DSA", "dsaEncryption", "1.2.840.10040.4.1"
|
|---|
| 28 |
|
|---|
| 29 | The base signature algorithm, supported explicitly fetched with
|
|---|
| 30 | L<EVP_PKEY_sign_init_ex2(3)>, and implicitly fetched (through
|
|---|
| 31 | L<EC keys|EVP_PKEY-EC(7)>) with L<EVP_DigestSignInit(3)> and
|
|---|
| 32 | L<EVP_DigestVerifyInit(3)>.
|
|---|
| 33 |
|
|---|
| 34 | It can't be used with L<EVP_PKEY_sign_message_init(3)>
|
|---|
| 35 |
|
|---|
| 36 | =item "DSA-SHA1", "DSA-SHA-1", "dsaWithSHA1", "1.2.840.10040.4.3"
|
|---|
| 37 |
|
|---|
| 38 | =item "DSA-SHA2-224", "DSA-SHA224", "dsa_with_SHA224", "2.16.840.1.101.3.4.3.1"
|
|---|
| 39 |
|
|---|
| 40 | =item "DSA-SHA2-256", "DSA-SHA256", "dsa_with_SHA256", "2.16.840.1.101.3.4.3.2"
|
|---|
| 41 |
|
|---|
| 42 | =item "DSA-SHA2-384", "DSA-SHA384", "dsa_with_SHA384", "id-dsa-with-sha384", "1.2.840.1.101.3.4.3.3"
|
|---|
| 43 |
|
|---|
| 44 | =item "DSA-SHA2-512", "DSA-SHA512", "dsa_with_SHA512", "id-dsa-with-sha512", "1.2.840.1.101.3.4.3.4"
|
|---|
| 45 |
|
|---|
| 46 | =item "DSA-SHA3-224", "dsa_with_SHA3-224", "id-dsa-with-sha3-224", "2.16.840.1.101.3.4.3.5"
|
|---|
| 47 |
|
|---|
| 48 | =item "DSA-SHA3-256", "dsa_with_SHA3-256", "id-dsa-with-sha3-256", "2.16.840.1.101.3.4.3.6"
|
|---|
| 49 |
|
|---|
| 50 | =item "DSA-SHA3-384", "dsa_with_SHA3-384", "id-dsa-with-sha3-384", "2.16.840.1.101.3.4.3.7"
|
|---|
| 51 |
|
|---|
| 52 | =item "DSA-SHA3-512", "dsa_with_SHA3-512", "id-dsa-with-sha3-512", "2.16.840.1.101.3.4.3.8"
|
|---|
| 53 |
|
|---|
| 54 | DSA signature schemes with diverse message digest algorithms. They are all
|
|---|
| 55 | supported explicitly fetched with L<EVP_PKEY_sign_init_ex2(3)> and
|
|---|
| 56 | L<EVP_PKEY_sign_message_init(3)>.
|
|---|
| 57 |
|
|---|
| 58 | =back
|
|---|
| 59 |
|
|---|
| 60 | =head2 Signature Parameters
|
|---|
| 61 |
|
|---|
| 62 | The following signature parameters can be set using EVP_PKEY_CTX_set_params().
|
|---|
| 63 | This may be called after EVP_PKEY_sign_init() or EVP_PKEY_verify_init(),
|
|---|
| 64 | and before calling EVP_PKEY_sign() or EVP_PKEY_verify(). They may also be set
|
|---|
| 65 | using EVP_PKEY_sign_init_ex() or EVP_PKEY_verify_init_ex().
|
|---|
| 66 |
|
|---|
| 67 | =over 4
|
|---|
| 68 |
|
|---|
| 69 | =item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
|
|---|
| 70 |
|
|---|
| 71 | =item "properties" (B<OSSL_SIGNATURE_PARAM_PROPERTIES>) <UTF8 string>
|
|---|
| 72 |
|
|---|
| 73 | These two are not supported with the DSA signature schemes that already
|
|---|
| 74 | include a message digest algorithm, See L</Algorithm Names> above.
|
|---|
| 75 |
|
|---|
| 76 | =item "nonce-type" (B<OSSL_SIGNATURE_PARAM_NONCE_TYPE>) <unsigned integer>
|
|---|
| 77 |
|
|---|
| 78 | =item "key-check" (B<OSSL_SIGNATURE_PARAM_FIPS_KEY_CHECK>) <integer>
|
|---|
| 79 |
|
|---|
| 80 | =item "digest-check" (B<OSSL_SIGNATURE_PARAM_FIPS_DIGEST_CHECK>) <integer>
|
|---|
| 81 |
|
|---|
| 82 | =item "sign-check" (B<OSSL_SIGNATURE_PARAM_FIPS_SIGN_CHECK>) <int>
|
|---|
| 83 |
|
|---|
| 84 | The settable parameters are described in L<provider-signature(7)>.
|
|---|
| 85 |
|
|---|
| 86 | =back
|
|---|
| 87 |
|
|---|
| 88 | The following signature parameters can be retrieved using
|
|---|
| 89 | EVP_PKEY_CTX_get_params().
|
|---|
| 90 |
|
|---|
| 91 | =over 4
|
|---|
| 92 |
|
|---|
| 93 | =item "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string>
|
|---|
| 94 |
|
|---|
| 95 | =item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
|
|---|
| 96 |
|
|---|
| 97 | =item "nonce-type" (B<OSSL_SIGNATURE_PARAM_NONCE_TYPE>) <unsigned integer>
|
|---|
| 98 |
|
|---|
| 99 | =item "fips-indicator" (B<OSSL_SIGNATURE_PARAM_FIPS_APPROVED_INDICATOR>) <integer>
|
|---|
| 100 |
|
|---|
| 101 | The gettable parameters are described in L<provider-signature(7)>.
|
|---|
| 102 |
|
|---|
| 103 | =back
|
|---|
| 104 |
|
|---|
| 105 | =head1 SEE ALSO
|
|---|
| 106 |
|
|---|
| 107 | L<EVP_PKEY_CTX_set_params(3)>,
|
|---|
| 108 | L<EVP_PKEY_sign(3)>,
|
|---|
| 109 | L<EVP_PKEY_verify(3)>,
|
|---|
| 110 | L<provider-signature(7)>,
|
|---|
| 111 |
|
|---|
| 112 | =head1 HISTORY
|
|---|
| 113 |
|
|---|
| 114 | DSA Key generation and signature generation are no longer FIPS approved in
|
|---|
| 115 | OpenSSL 3.4. See L<fips_module(7)/FIPS indicators> for more information.
|
|---|
| 116 |
|
|---|
| 117 | =head1 COPYRIGHT
|
|---|
| 118 |
|
|---|
| 119 | Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 120 |
|
|---|
| 121 | Licensed under the Apache License 2.0 (the "License"). You may not use
|
|---|
| 122 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 123 | in the file LICENSE in the source distribution or at
|
|---|
| 124 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 125 |
|
|---|
| 126 | =cut
|
|---|
