docs: Document the implemented composite signature+hash algorithms

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)

diff --git a/doc/man7/EVP_SIGNATURE-DSA.pod b/doc/man7/EVP_SIGNATURE-DSA.pod
index 74879f0e61394686e67d0a2d9d94f8579a56fa07..6a2def1c0be8fbb0a40bd540daf4079335db18c4 100644 (file)
--- a/doc/man7/EVP_SIGNATURE-DSA.pod
+++ b/doc/man7/EVP_SIGNATURE-DSA.pod
@@ -13,6 +13,48 @@ See L<EVP_PKEY-DSA(7)> for information related to DSA keys.
 As part of FIPS 140-3 DSA is not longer FIPS approved for key generation and
 signature validation, but is still allowed for signature verification.
 
+=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 "DSA", "dsaEncryption", "1.2.840.10040.4.1"
+
+The base signature algorithm, supported explicitly fetched with
+L<EVP_PKEY_sign_init_ex2(3)>, and implicitly fetched (through
+L<EC keys|EVP_PKEY-EC(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 "DSA-SHA1", "DSA-SHA-1", "dsaWithSHA1", "1.2.840.10040.4.3"
+
+=item "DSA-SHA2-224", "DSA-SHA224", "dsa_with_SHA224", "2.16.840.1.101.3.4.3.1"
+
+=item "DSA-SHA2-256", "DSA-SHA256", "dsa_with_SHA256", "2.16.840.1.101.3.4.3.2"
+
+=item "DSA-SHA2-384", "DSA-SHA384", "dsa_with_SHA384", "id-dsa-with-sha384", "1.2.840.1.101.3.4.3.3"
+
+=item "DSA-SHA2-512", "DSA-SHA512", "dsa_with_SHA512", "id-dsa-with-sha512", "1.2.840.1.101.3.4.3.4"
+
+=item "DSA-SHA3-224", "dsa_with_SHA3-224", "id-dsa-with-sha3-224", "2.16.840.1.101.3.4.3.5"
+
+=item "DSA-SHA3-256", "dsa_with_SHA3-256", "id-dsa-with-sha3-256", "2.16.840.1.101.3.4.3.6"
+
+=item "DSA-SHA3-384", "dsa_with_SHA3-384", "id-dsa-with-sha3-384", "2.16.840.1.101.3.4.3.7"
+
+=item "DSA-SHA3-512", "dsa_with_SHA3-512", "id-dsa-with-sha3-512", "2.16.840.1.101.3.4.3.8"
+
+DSA 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)>.
+
+=back
+
 =head2 Signature Parameters
 
 The following signature parameters can be set using EVP_PKEY_CTX_set_params().
@@ -26,6 +68,9 @@ using EVP_PKEY_sign_init_ex() or EVP_PKEY_verify_init_ex().
 
 =item "properties" (B<OSSL_SIGNATURE_PARAM_PROPERTIES>) <UTF8 string>
 
+These two are not supported with the DSA signature schemes that already
+include a message digest algorithm, See L</Algorithm Names> above.
+
 =item "nonce-type" (B<OSSL_SIGNATURE_PARAM_NONCE_TYPE>) <unsigned integer>
 
 =item "key-check" (B<OSSL_SIGNATURE_PARAM_FIPS_KEY_CHECK>) <integer>

diff --git a/doc/man7/EVP_SIGNATURE-ECDSA.pod b/doc/man7/EVP_SIGNATURE-ECDSA.pod
index 1d60d23b24b7dccc1b4fa3084c297b44ccde3d99..bc75ed140814f9262f2777c3538b8aed80e09a15 100644 (file)
--- a/doc/man7/EVP_SIGNATURE-ECDSA.pod
+++ b/doc/man7/EVP_SIGNATURE-ECDSA.pod
@@ -9,6 +9,48 @@ EVP_SIGNATURE-ECDSA - The EVP_PKEY ECDSA signature implementation.
 Support for computing ECDSA signatures.
 See L<EVP_PKEY-EC(7)> for information related to EC 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 "ECDSA"
+
+The base signature algorithm, supported explicitly fetched with
+L<EVP_PKEY_sign_init_ex2(3)>, and implicitly fetched (through
+L<EC keys|EVP_PKEY-EC(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 "ECDSA-SHA1", "ECDSA-SHA-1", "ecdsa-with-SHA1", "1.2.840.10045.4.1"
+
+=item "ECDSA-SHA2-224", "ECDSA-SHA224", "ecdsa-with-SHA224", "1.2.840.10045.4.3.1"
+
+=item "ECDSA-SHA2-256", "ECDSA-SHA256", "ecdsa-with-SHA256", "1.2.840.10045.4.3.2"
+
+=item "ECDSA-SHA2-384", "ECDSA-SHA384", "ecdsa-with-SHA384", "1.2.840.10045.4.3.3"
+
+=item "ECDSA-SHA2-512", "ECDSA-SHA512", "ecdsa-with-SHA512", "1.2.840.10045.4.3.4"
+
+=item "ECDSA-SHA3-224", "ecdsa_with_SHA3-224", "id-ecdsa-with-sha3-224", "2.16.840.1.101.3.4.3.9"
+
+=item "ECDSA-SHA3-256", "ecdsa_with_SHA3-256", "id-ecdsa-with-sha3-256", "2.16.840.1.101.3.4.3.10"
+
+=item "ECDSA-SHA3-384", "ecdsa_with_SHA3-384", "id-ecdsa-with-sha3-384", "2.16.840.1.101.3.4.3.11"
+
+=item "ECDSA-SHA3-512", "ecdsa_with_SHA3-512", "id-ecdsa-with-sha3-512", "2.16.840.1.101.3.4.3.12"
+
+ECDSA 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)>.
+
+=back
+
 =head2 ECDSA Signature Parameters
 
 The following signature parameters can be set using EVP_PKEY_CTX_set_params().
@@ -21,6 +63,9 @@ and before calling EVP_PKEY_sign() or EVP_PKEY_verify().
 
 =item "properties" (B<OSSL_SIGNATURE_PARAM_PROPERTIES>) <UTF8 string>
 
+These two are not supported with the ECDSA signature schemes that already
+include a message digest algorithm, See L</Algorithm Names> above.
+
 =item "nonce-type" (B<OSSL_SIGNATURE_PARAM_NONCE_TYPE>) <unsigned integer>
 
 =item "key-check" (B<OSSL_SIGNATURE_PARAM_FIPS_KEY_CHECK>) <integer>

diff --git a/doc/man7/EVP_SIGNATURE-RSA.pod b/doc/man7/EVP_SIGNATURE-RSA.pod
index 979b612d6c10c96d04248d2408a0ca20abd624ec..5dc27ac2838e6b857df890104f30390660f95e62 100644 (file)
--- a/doc/man7/EVP_SIGNATURE-RSA.pod
+++ b/doc/man7/EVP_SIGNATURE-RSA.pod
@@ -26,24 +26,36 @@ 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)>.
 
-Can't be used with L<EVP_PKEY_sign_message_init(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 algorithm.  They
+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