provider-signature.pod: add missing doc of OSSL_FUNC_signature_query_key_types()...

Reviewed-by: Nicola Tuveri <nic.tuv@gmail.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/27367)

(cherry picked from commit 1146b74a8a5784cc51426695d038ad8d9a4cc717)

diff --git a/doc/man7/provider-signature.pod b/doc/man7/provider-signature.pod
index 58a1ca71a76d939f211305290ae9dd527a2d42ac..61202b523640238723b06198ce30f6b4d38b1844 100644 (file)
--- a/doc/man7/provider-signature.pod
+++ b/doc/man7/provider-signature.pod
@@ -107,8 +107,7 @@ for further information.
 The signature (OSSL_OP_SIGNATURE) operation enables providers to implement
 signature algorithms and make them available to applications via the API
 functions L<EVP_PKEY_sign(3)>, L<EVP_PKEY_verify(3)>,
-and L<EVP_PKEY_verify_recover(3)> (as well
-as other related functions).
+and L<EVP_PKEY_verify_recover(3)> (as well as other related functions).
 
 All "functions" mentioned here are passed as function pointers between
 F<libcrypto> and the provider in L<OSSL_DISPATCH(3)> arrays via
@@ -201,10 +200,22 @@ set of "signature" functions, i.e. at least one of:
 
 =back
 
-OSSL_FUNC_signature_set_ctx_params and OSSL_FUNC_signature_settable_ctx_params are optional,
-but if one of them is present then the other one must also be present. The same
-applies to OSSL_FUNC_signature_get_ctx_params and OSSL_FUNC_signature_gettable_ctx_params, as
-well as the "md_params" functions. The OSSL_FUNC_signature_dupctx function is optional.
+The OSSL_FUNC_signature_set_ctx_params() and
+OSSL_FUNC_signature_settable_ctx_params() functions are optional,
+but if one of them is provided then the other one must also be provided.
+The same applies to the OSSL_FUNC_signature_get_ctx_params() and
+OSSL_FUNC_signature_gettable_ctx_params() functions,
+as well as the "md_params" functions.
+
+The OSSL_FUNC_signature_dupctx() function is optional.
+It is not yet used by OpenSSL.
+
+The OSSL_FUNC_signature_query_key_types() function is optional.
+When present, it should return a NULL-terminated array of strings
+indicating the key types supported by the provider for signature operations.
+Otherwise the signature algorithm name must match the given key
+or match the default signature algorithm name of the key,
+both checked using L<EVP_SIGNATURE_is_a(3)>.
 
 A signature algorithm must also implement some mechanism for generating,
 loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation.
@@ -474,8 +485,8 @@ Gets the DER-encoded AlgorithmIdentifier for the signature operation.
 This typically corresponds to the combination of a digest algorithm
 with a purely asymmetric signature algorithm, such as SHA256WithECDSA.
 
-The L<ASN1_item_sign_ctx(3)> relies on this operation and is used by
-many other functions signing ASN.1 structures such as X.509 certificates,
+The L<ASN1_item_sign_ctx(3)> function relies on this operation and is used by
+many other functions that sign ASN.1 structures such as X.509 certificates,
 certificate requests, and CRLs, as well as OCSP, CMP, and CMS messages.
 
 =item "nonce-type" (B<OSSL_SIGNATURE_PARAM_NONCE_TYPE>) <unsigned integer>
@@ -604,12 +615,20 @@ OSSL_FUNC_signature_gettable_ctx_params(), OSSL_FUNC_signature_settable_ctx_para
 OSSL_FUNC_signature_gettable_md_ctx_params() and OSSL_FUNC_signature_settable_md_ctx_params(),
 return the gettable or settable parameters in a constant L<OSSL_PARAM(3)> array.
 
-All other functions should return 1 for success or 0 on error.
+OSSL_FUNC_signature_query_key_types() should return a NULL-terminated array of strings.
+
+All verification functions should return 1 for success,
+0 for a non-matching signature, and a negative value for operation failure.
+
+All other functions should return 1 for success
+and 0 or a negative value for failure.
 
 =head1 SEE ALSO
 
-L<provider(7)>,
-L<ASN1_item_sign_ctx(3)>
+L<provider(7)>, L<provider-base(7)/Provider Functions>,
+L<OSSL_PARAM(3)>, L<OSSL_DISPATCH(3)>, L<OSSL_ALGORITHM(3)>,
+L<EVP_PKEY_sign(3)>, L<EVP_PKEY_verify(3)>, L<EVP_PKEY_verify_recover(3)>,
+L<EVP_SIGNATURE_is_a(3)>, L<ASN1_item_sign_ctx(3)>
 
 =head1 HISTORY