Mirrors/openssl
0
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2026-01-18 17:11:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

Improve provider-signature documentation clarity

Browse Source 
- 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)
This commit is contained in:
Samaresh Kumar Singh
2025-11-18 10:51:07 -06:00
committed by Tomas Mraz
parent 0c2a196af8
commit 47418dd8de
1 changed files with 61 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
doc/man7/provider-signature.pod
View File

@@ -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