From: Samaresh Kumar Singh <ssam3003@gmail.com>
Date: Tue, 18 Nov 2025 16:51:07 +0000 (-0600)
Subject: Improve provider-signature documentation clarity
X-Git-Tag: 4.0-PRE-CLANG-FORMAT-WEBKIT~108
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=47418dd8de635448fd1f5dfb583070e1f5fcf559;p=thirdparty%2Fopenssl.git

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 ca9781091e4..d5af5a2e389 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