From: Richard Levitte Date: Tue, 10 Sep 2024 16:16:10 +0000 (+0200) Subject: docs: Document the new signature interface for providers X-Git-Tag: openssl-3.5.0-alpha1~1130 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=04c134a95b643329ef45fed886263cfd9df71c32;p=thirdparty%2Fopenssl.git docs: Document the new signature interface for providers Reviewed-by: Matt Caswell Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/25423) --- diff --git a/doc/man7/provider-signature.pod b/doc/man7/provider-signature.pod index cb26a1c75db..40922e0aea9 100644 --- a/doc/man7/provider-signature.pod +++ b/doc/man7/provider-signature.pod @@ -22,17 +22,36 @@ provider-signature - The signature library E-E provider functions void OSSL_FUNC_signature_freectx(void *ctx); void *OSSL_FUNC_signature_dupctx(void *ctx); + /* Get the key types that a signature algorithm supports */ + const char **OSSL_FUNC_signature_query_key_types(void); + /* Signing */ int OSSL_FUNC_signature_sign_init(void *ctx, void *provkey, const OSSL_PARAM params[]); int OSSL_FUNC_signature_sign(void *ctx, unsigned char *sig, size_t *siglen, size_t sigsize, const unsigned char *tbs, size_t tbslen); + int OSSL_FUNC_signature_sign_message_init(void *ctx, void *provkey, + const OSSL_PARAM params[]); + int OSSL_FUNC_signature_sign_message_update(void *ctx, const unsigned char *in, + size_t inlen); + int OSSL_FUNC_signature_sign_message_final(void *ctx, unsigned char *sig, + size_t *siglen, size_t sigsize); /* Verifying */ int OSSL_FUNC_signature_verify_init(void *ctx, void *provkey, const OSSL_PARAM params[]); int OSSL_FUNC_signature_verify(void *ctx, const unsigned char *sig, size_t siglen, const unsigned char *tbs, size_t tbslen); + int OSSL_FUNC_signature_verify_message_init(void *ctx, void *provkey, + const OSSL_PARAM params[]); + int OSSL_FUNC_signature_verify_message_update(void *ctx, const unsigned char *in, + size_t inlen); + /* + * OSSL_FUNC_signature_verify_message_final requires that the signature to be + * verified is specified via a "signature" OSSL_PARAM, which is given with a + * previous call of OSSL_FUNC_signature_set_ctx_params(). + */ + int OSSL_FUNC_signature_verify_message_final(void *ctx); /* Verify Recover */ int OSSL_FUNC_signature_verify_recover_init(void *ctx, void *provkey, @@ -87,8 +106,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, +functions L, L, and L (as well as other related functions). @@ -115,11 +133,19 @@ macros in L, as follows: OSSL_FUNC_signature_freectx OSSL_FUNC_SIGNATURE_FREECTX OSSL_FUNC_signature_dupctx OSSL_FUNC_SIGNATURE_DUPCTX + OSSL_FUNC_signature_query_key_types OSSL_FUNC_SIGNATURE_QUERY_KEY_TYPES + OSSL_FUNC_signature_sign_init OSSL_FUNC_SIGNATURE_SIGN_INIT OSSL_FUNC_signature_sign OSSL_FUNC_SIGNATURE_SIGN + OSSL_FUNC_signature_sign_message_init OSSL_FUNC_SIGNATURE_SIGN_MESSAGE_INIT + OSSL_FUNC_signature_sign_message_update OSSL_FUNC_SIGNATURE_SIGN_MESSAGE_UPDATE + OSSL_FUNC_signature_sign_message_final OSSL_FUNC_SIGNATURE_SIGN_MESSAGE_FINAL OSSL_FUNC_signature_verify_init OSSL_FUNC_SIGNATURE_VERIFY_INIT OSSL_FUNC_signature_verify OSSL_FUNC_SIGNATURE_VERIFY + OSSL_FUNC_signature_verify_message_init OSSL_FUNC_SIGNATURE_VERIFY_MESSAGE_INIT + OSSL_FUNC_signature_verify_message_update OSSL_FUNC_SIGNATURE_VERIFY_MESSAGE_UPDATE + OSSL_FUNC_signature_verify_message_final OSSL_FUNC_SIGNATURE_VERIFY_MESSAGE_FINAL OSSL_FUNC_signature_verify_recover_init OSSL_FUNC_SIGNATURE_VERIFY_RECOVER_INIT OSSL_FUNC_signature_verify_recover OSSL_FUNC_SIGNATURE_VERIFY_RECOVER @@ -153,8 +179,16 @@ set of "signature" functions, i.e. at least one of: =item OSSL_FUNC_signature_sign_init and OSSL_FUNC_signature_sign +=item OSSL_FUNC_signature_sign_message_init and OSSL_FUNC_signature_sign + +=item OSSL_FUNC_signature_sign_message_init, OSSL_FUNC_signature_sign_message_update and OSSL_FUNC_signature_sign_message_final + =item OSSL_FUNC_signature_verify_init and OSSL_FUNC_signature_verify +=item OSSL_FUNC_signature_verify_message_init and OSSL_FUNC_signature_verify + +=item OSSL_FUNC_signature_verify_message_init, OSSL_FUNC_signature_verify_message_update and OSSL_FUNC_signature_verify_message_final + =item OSSL_FUNC_signature_verify_recover_init and OSSL_FUNC_signature_verify_recover =item OSSL_FUNC_signature_digest_sign_init, OSSL_FUNC_signature_digest_sign_update and OSSL_FUNC_signature_digest_sign_final @@ -216,6 +250,38 @@ The length of the signature should be written to I<*siglen>. If I is NULL then the maximum length of the signature should be written to I<*siglen>. +=head2 Message Signing Functions + +These functions are suitable for providers that implement algorithms that +accumulate a full message and sign the result of that accumulation, such as +RSA-SHA256. + +OSSL_FUNC_signature_sign_message_init() initialises a context for signing a +message given a provider side signature context in the I parameter, and a +pointer to a provider key object in the I parameter. +The I, if not NULL, should be set on the context in a manner similar to +using OSSL_FUNC_signature_set_ctx_params(). +The key object should have been previously generated, loaded or imported into +the provider using the key management (OSSL_OP_KEYMGMT) operation (see +provider-keymgmt(7)>. + +OSSL_FUNC_signature_sign_message_update() gathers the data pointed at by +I, which is I bytes long. + +OSSL_FUNC_signature_sign_message_final() performs the actual signing on the +data that was gathered with OSSL_FUNC_signature_sign_message_update(). + +OSSL_FUNC_signature_sign() can be used for one-shot signature calls. In that +case, I is expected to be the whole message to be signed, I bytes +long. + +For both OSSL_FUNC_signature_sign_message_final() and OSSL_FUNC_signature_sign(), +if I is not NULL, the signature should be written to the location pointed +to by I, and it should not exceed I bytes in length. +The length of the signature should be written to I<*siglen>. +If I is NULL then the maximum length of the signature should be written to +I<*siglen>. + =head2 Verify Functions OSSL_FUNC_signature_verify_init() initialises a context for verifying a signature given @@ -234,6 +300,34 @@ is I bytes long. The signature is pointed to by the I parameter which is I bytes long. +=head2 Message Verify Functions + +These functions are suitable for providers that implement algorithms that +accumulate a full message and verify a signature on the result of that +accumulation, such as RSA-SHA256. + +OSSL_FUNC_signature_verify_message_init() initialises a context for verifying +a signature on a message given a provider side signature context in the I +parameter, and a pointer to a provider key object in the I parameter. +The I, if not NULL, should be set on the context in a manner similar to +using OSSL_FUNC_signature_set_ctx_params(). +The key object should have been previously generated, loaded or imported into +the provider using the key management (OSSL_OP_KEYMGMT) operation (see +provider-keymgmt(7)>. + +OSSL_FUNC_signature_verify_message_update() gathers the data pointed at by +I, which is I bytes long. + +OSSL_FUNC_signature_verify_message_final() performs the actual verification on +the data that was gathered with OSSL_FUNC_signature_verify_message_update(). +The signature itself must have been passed through the "signature" +(B) L +before this function is called. + +OSSL_FUNC_signature_verify() can be used for one-shot verification calls. In +that case, I is expected to be the whole message to be verified on, +I bytes long. + =head2 Verify Recover Functions OSSL_FUNC_signature_verify_recover_init() initialises a context for recovering the @@ -352,6 +446,22 @@ signature functions. It is required in order to calculate the "algorithm-id". Sets the name of the property query associated with the "digest" algorithm. NULL is used if this optional value is not set. +=back + +Note that when implementing a signature algorithm that gathers a full message, +like RSA-SHA256, the "digest" and "properties" parameters should not be used. +For such implementations, it's acceptable to simply ignore them if they happen +to be passed in a call to OSSL_FUNC_signature_set_ctx_params(). For such +implementations, however, it is not acceptable to have them in the B +array that's returned by OSSL_FUNC_signature_settable_ctx_params(). + +=over 4 + +=item "signature" (B) + +Sets the signature to verify, specifically when +OSSL_FUNC_signature_verify_message_final() is used. + =item "digest-size" (B) Gets or sets the output size of the digest algorithm used for the input to the @@ -437,7 +547,7 @@ Setting this to 0 will ignore the error and set the approved "fips-indicator" to This option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0. -=item "sign-x931-pad-check" (B) +=item "sign-x931-pad-check" (B) If required this parameter should be set before the padding mode is set. The default value of 1 causes an error if the padding mode is set to X9.31 padding