Commit 47418dd8de for openssl.org

commit 47418dd8de635448fd1f5dfb583070e1f5fcf559
Author: Samaresh Kumar Singh <ssam3003@gmail.com>
Date:   Tue Nov 18 10:51:07 2025 -0600

    Improve provider-signature documentation clarity

    - Add explicit links to related EVP_* functions for each signature method
    - Clarify the differences between sign/verify, message sign/verify, and digest sign/verify functions
    - Document TLS 1.3 requirements: digest_sign/verify functions are mandatory for libssl usage
    - Provide guidance for provider developers on which functions to implement for different use cases

    Fixes #27127

    Signed-off-by: Samaresh Kumar Singh <ssam3003@gmail.com>

    Reviewed-by: Paul Dale <paul.dale@oracle.com>
    Reviewed-by: Nikola Pajkovsky <nikolap@openssl.org>
    (Merged from https://github.com/openssl/openssl/pull/29166)

diff --git a/doc/man7/provider-signature.pod b/doc/man7/provider-signature.pod
index ca9781091e..d5af5a2e38 100644
--- a/doc/man7/provider-signature.pod
+++ b/doc/man7/provider-signature.pod
@@ -178,26 +178,87 @@ set of "signature" functions, i.e. at least one of:

 =item OSSL_FUNC_signature_sign_init and OSSL_FUNC_signature_sign

+Used via L<EVP_PKEY_sign_init(3)> and L<EVP_PKEY_sign(3)>.
+These functions operate on pre-digested data (the "to be signed" or TBS value).
+
 =item OSSL_FUNC_signature_sign_message_init and OSSL_FUNC_signature_sign

+Used via L<EVP_PKEY_sign_message_init(3)> and L<EVP_PKEY_sign(3)> when signing a complete message.
+The implementation internally handles message digesting.
+
 =item OSSL_FUNC_signature_sign_message_init, OSSL_FUNC_signature_sign_message_update and OSSL_FUNC_signature_sign_message_final

+Streaming variant of message signing, used via L<EVP_PKEY_sign_message_init(3)>,
+L<EVP_PKEY_sign_message_update(3)>, and L<EVP_PKEY_sign_message_final(3)>.
+
 =item OSSL_FUNC_signature_verify_init and OSSL_FUNC_signature_verify

+Used via L<EVP_PKEY_verify_init(3)> and L<EVP_PKEY_verify(3)>.
+These functions operate on pre-digested data.
+
 =item OSSL_FUNC_signature_verify_message_init and OSSL_FUNC_signature_verify

+Used via L<EVP_PKEY_verify_message_init(3)> and L<EVP_PKEY_verify(3)> when verifying a complete message.
+The implementation internally handles message digesting.
+
 =item OSSL_FUNC_signature_verify_message_init, OSSL_FUNC_signature_verify_message_update and OSSL_FUNC_signature_verify_message_final

+Streaming variant of message verification, used via L<EVP_PKEY_verify_message_init(3)>,
+L<EVP_PKEY_verify_message_update(3)>, and L<EVP_PKEY_verify_message_final(3)>.
+
 =item OSSL_FUNC_signature_verify_recover_init and OSSL_FUNC_signature_verify_recover

+Used via L<EVP_PKEY_verify_recover_init(3)> and L<EVP_PKEY_verify_recover(3)>.
+Applicable only to signature schemes that support signature recovery (such as RSA).
+
 =item OSSL_FUNC_signature_digest_sign_init, OSSL_FUNC_signature_digest_sign_update and OSSL_FUNC_signature_digest_sign_final

+Streaming digest-sign variant, used via L<EVP_DigestSignInit(3)>,
+L<EVP_DigestSignUpdate(3)>, and L<EVP_DigestSignFinal(3)>.
+
 =item OSSL_FUNC_signature_digest_verify_init, OSSL_FUNC_signature_digest_verify_update and OSSL_FUNC_signature_digest_verify_final

+Streaming digest-verify variant, used via L<EVP_DigestVerifyInit(3)>,
+L<EVP_DigestVerifyUpdate(3)>, and L<EVP_DigestVerifyFinal(3)>.
+
 =item OSSL_FUNC_signature_digest_sign_init and OSSL_FUNC_signature_digest_sign

+One-shot digest-sign variant, used via L<EVP_DigestSign(3)>.
+
 =item OSSL_FUNC_signature_digest_verify_init and OSSL_FUNC_signature_digest_verify

+One-shot digest-verify variant, used via L<EVP_DigestVerify(3)>.
+
+=back
+
+B<Important Note for TLS Support:> For a provider signature implementation to
+be usable within F<libssl> for TLS connections, it B<must> implement the
+digest-sign and digest-verify functions
+(OSSL_FUNC_signature_digest_sign_init/update/final or the one-shot variant, and
+OSSL_FUNC_signature_digest_verify_init/update/final or the one-shot variant).
+The TLS handshake code in F<libssl> specifically requires these digest functions
+and will not use implementations that only provide the basic sign/verify functions
+(OSSL_FUNC_signature_sign_init/sign or OSSL_FUNC_signature_verify_init/verify).
+
+The choice of which function set to implement depends on your use case:
+
+=over 4
+
+=item *
+
+For general-purpose signature operations and TLS support: implement the
+digest-sign and digest-verify functions.
+
+=item *
+
+For operations on pre-digested data only: implement the basic sign and verify
+functions.
+
+=item *
+
+For signature schemes with recovery capability: additionally implement the
+verify-recover functions.
+
 =back

 The OSSL_FUNC_signature_set_ctx_params() and