mirrors/openssl
0
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2024-11-23 18:13:39 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: Document the new signature interface for providers

Browse Source 
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/25423)
This commit is contained in:
Richard Levitte 2024-09-10 18:16:10 +02:00 committed by Tomas Mraz
parent 22c2928a9a
commit 04c134a95b
1 changed files with 113 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -22,17 +22,36 @@ provider-signature - The signature library E<lt>-E<gt> 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<EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)>,
functions L<EVP_PKEY_sign(3)>, L<EVP_PKEY_verify(3)>,
and L<EVP_PKEY_verify_recover(3)> (as well
as other related functions).
@ -115,11 +133,19 @@ macros in L<openssl-core_dispatch.h(7)>, 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<sig> 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<ctx> parameter, and a
pointer to a provider key object in the I<provkey> parameter.
The I<params>, 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<in>, which is I<inlen> 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<tbs> is expected to be the whole message to be signed, I<tbslen> bytes
long.
For both OSSL_FUNC_signature_sign_message_final() and OSSL_FUNC_signature_sign(),
if I<sig> is not NULL, the signature should be written to the location pointed
to by I<sig>, and it should not exceed I<sigsize> bytes in length.
The length of the signature should be written to I<*siglen>.
If I<sig> 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<tbslen> bytes long.
The signature is pointed to by the I<sig> parameter which is I<siglen> 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<ctx>
parameter, and a pointer to a provider key object in the I<provkey> parameter.
The I<params>, 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<in>, which is I<inlen> 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<OSSL_SIGNATURE_PARAM_SIGNATURE>) L<Signature parameter|/Signature parameters>
before this function is called.
OSSL_FUNC_signature_verify() can be used for one-shot verification calls. In
that case, I<tbs> is expected to be the whole message to be verified on,
I<tbslen> 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<OSSL_PARAM>
array that's returned by OSSL_FUNC_signature_settable_ctx_params().
=over 4
=item "signature" (B<OSSL_SIGNATURE_PARAM_SIGNATURE>) <octet string>
Sets the signature to verify, specifically when
OSSL_FUNC_signature_verify_message_final() is used.
=item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <unsigned integer>
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<SIGNATURE_PARAM_FIPS_SIGN_X931_PAD_CHECK>) <integer>
=item "sign-x931-pad-check" (B<OSSL_SIGNATURE_PARAM_FIPS_SIGN_X931_PAD_CHECK>) <integer>
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