From d977f3c424179056a30029b43f157a686139ca48 Mon Sep 17 00:00:00 2001 From: "Dr. David von Oheimb" Date: Mon, 14 Apr 2025 16:05:01 +0200 Subject: [PATCH] provider-signature.pod: add missing doc of OSSL_FUNC_signature_query_key_types(), fix doc of return types, etc. Reviewed-by: Nicola Tuveri Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/27367) (cherry picked from commit 1146b74a8a5784cc51426695d038ad8d9a4cc717) --- doc/man7/provider-signature.pod | 41 ++++++++++++++++++++++++--------- 1 file changed, 30 insertions(+), 11 deletions(-) diff --git a/doc/man7/provider-signature.pod b/doc/man7/provider-signature.pod index 58a1ca71a76..61202b52364 100644 --- 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, L, -and L (as well -as other related functions). +and L (as well as other related functions). All "functions" mentioned here are passed as function pointers between F and the provider in L 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. 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 relies on this operation and is used by -many other functions signing ASN.1 structures such as X.509 certificates, +The L 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) @@ -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 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, -L +L, L, +L, L, L, +L, L, L, +L, L =head1 HISTORY -- 2.47.2