From: Matt Caswell Date: Tue, 3 Sep 2019 15:15:21 +0000 (+0100) Subject: Add public API docs for newly added EVP_SIGNATURE related functions X-Git-Tag: openssl-3.0.0-alpha1~1420 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=11031468c38c801b6acefe9bba9d531d92653da3;p=oweals%2Fopenssl.git Add public API docs for newly added EVP_SIGNATURE related functions Documentation for EVP_SIGNATURE_*() as well as EVP_PKEY_sign_init_ex(), EVP_PKEY_verify_init_ex() and EVP_PKEY_verify_recover_init_ex(). Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/9753) --- diff --git a/doc/man3/EVP_PKEY_CTX_ctrl.pod b/doc/man3/EVP_PKEY_CTX_ctrl.pod index 1787e19ab7..9d1812f6bd 100644 --- a/doc/man3/EVP_PKEY_CTX_ctrl.pod +++ b/doc/man3/EVP_PKEY_CTX_ctrl.pod @@ -161,6 +161,17 @@ up to the size of the DH prime B

. If B is zero (the default) then no padding is performed. +=item OSSL_SIGNATURE_PARAM_DIGEST (UTF8 string type) + +Sets the name of the digest algorithm used for the input to the signature +functions. + +=item OSSL_SIGNATURE_PARAM_DIGEST_SIZE (size_t type) + +Sets the output size of the digest algorithm used for the input to the signature +functions. +The internal algorithm that supports this parameter is DSA. + =back The function EVP_PKEY_CTX_ctrl() sends a control operation to the context diff --git a/doc/man3/EVP_PKEY_derive.pod b/doc/man3/EVP_PKEY_derive.pod index d6516e7933..832498ba76 100644 --- a/doc/man3/EVP_PKEY_derive.pod +++ b/doc/man3/EVP_PKEY_derive.pod @@ -25,10 +25,10 @@ The EVP_PKEY object associated with B must be compatible with that algorithm. B may be NULL in which case the EVP_KEYEXCH algorithm is fetched implicitly based on the type of EVP_PKEY associated with B. -See L for more information about implict fetches. +See L for more information about implict fetches. -The EVP_PKEY_derive_init() function is the same as EVP_PKEY_derive() except that -the EVP_KEYEXCH algorithm is always implicitly fetched. +The EVP_PKEY_derive_init() function is the same as EVP_PKEY_derive_init_ex() +except that the EVP_KEYEXCH algorithm is always implicitly fetched. The EVP_PKEY_derive_set_peer() function sets the peer key: this will normally be a public key. diff --git a/doc/man3/EVP_PKEY_sign.pod b/doc/man3/EVP_PKEY_sign.pod index d48edb5025..f30affd459 100644 --- a/doc/man3/EVP_PKEY_sign.pod +++ b/doc/man3/EVP_PKEY_sign.pod @@ -2,12 +2,14 @@ =head1 NAME -EVP_PKEY_sign_init, EVP_PKEY_sign - sign using a public key algorithm +EVP_PKEY_sign_init_ex, EVP_PKEY_sign_init, EVP_PKEY_sign +- sign using a public key algorithm =head1 SYNOPSIS #include + int EVP_PKEY_sign_init_ex(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *signature); int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx); int EVP_PKEY_sign(EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen, @@ -15,8 +17,18 @@ EVP_PKEY_sign_init, EVP_PKEY_sign - sign using a public key algorithm =head1 DESCRIPTION -The EVP_PKEY_sign_init() function initializes a public key algorithm -context using key B for a signing operation. +The EVP_PKEY_sign_init_ex() function initializes a public key algorithm +context for performing signing using the signature algorithm B. +The signature algorithm B should be fetched using a call to +L. +The EVP_PKEY object associated with B must be compatible with that +algorithm. +B may be NULL in which case the EVP_SIGNATURE algorithm is fetched +implicitly based on the type of EVP_PKEY associated with B. +See L for more information about implict fetches. + +The EVP_PKEY_sign_init() function is the same as EVP_PKEY_sign_init_ex() except +that the EVP_SIGNATURE algorithm is always implicitly fetched. The EVP_PKEY_sign() function performs a public key signing operation using B. The data to be signed is specified using the B and @@ -101,6 +113,7 @@ L =head1 HISTORY +EVP_PKEY_sign_init_ex() was added in OpenSSL 3.0. These functions were added in OpenSSL 1.0.0. =head1 COPYRIGHT diff --git a/doc/man3/EVP_PKEY_verify.pod b/doc/man3/EVP_PKEY_verify.pod index 0212202514..1e04a85ca9 100644 --- a/doc/man3/EVP_PKEY_verify.pod +++ b/doc/man3/EVP_PKEY_verify.pod @@ -2,12 +2,14 @@ =head1 NAME -EVP_PKEY_verify_init, EVP_PKEY_verify - signature verification using a public key algorithm +EVP_PKEY_verify_init_ex, EVP_PKEY_verify_init, EVP_PKEY_verify +- signature verification using a public key algorithm =head1 SYNOPSIS #include + int EVP_PKEY_verify_init_ex(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *signature); int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx); int EVP_PKEY_verify(EVP_PKEY_CTX *ctx, const unsigned char *sig, size_t siglen, @@ -15,8 +17,19 @@ EVP_PKEY_verify_init, EVP_PKEY_verify - signature verification using a public ke =head1 DESCRIPTION -The EVP_PKEY_verify_init() function initializes a public key algorithm -context using key B for a signature verification operation. +The EVP_PKEY_verify_init_ex() function initializes a public key algorithm +context for performing signature verification using the signature algorithm +B. +The signature algorithm B should be fetched using a call to +L. +The EVP_PKEY object associated with B must be compatible with that +algorithm. +B may be NULL in which case the EVP_SIGNATURE algorithm is fetched +implicitly based on the type of EVP_PKEY associated with B. +See L for more information about implict fetches. + +The EVP_PKEY_verify_init() function is the same as EVP_PKEY_verify_init_ex() +except that the EVP_SIGNATURE algorithm is always implicitly fetched. The EVP_PKEY_verify() function performs a public key verification operation using B. The signature is specified using the B and @@ -89,7 +102,8 @@ L =head1 HISTORY -These functions were added in OpenSSL 1.0.0. +EVP_PKEY_verify_init_ex() was added in OpenSSL 3.0. +All other functions were added in OpenSSL 1.0.0. =head1 COPYRIGHT diff --git a/doc/man3/EVP_PKEY_verify_recover.pod b/doc/man3/EVP_PKEY_verify_recover.pod index 2b425a3852..737c372dd1 100644 --- a/doc/man3/EVP_PKEY_verify_recover.pod +++ b/doc/man3/EVP_PKEY_verify_recover.pod @@ -2,12 +2,15 @@ =head1 NAME -EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover - recover signature using a public key algorithm +EVP_PKEY_verify_recover_init_ex, EVP_PKEY_verify_recover_init, +EVP_PKEY_verify_recover - recover signature using a public key algorithm =head1 SYNOPSIS #include + int EVP_PKEY_verify_recover_init_ex(EVP_PKEY_CTX *ctx, + EVP_SIGNATURE *signature); int EVP_PKEY_verify_recover_init(EVP_PKEY_CTX *ctx); int EVP_PKEY_verify_recover(EVP_PKEY_CTX *ctx, unsigned char *rout, size_t *routlen, @@ -15,8 +18,20 @@ EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover - recover signature using =head1 DESCRIPTION -The EVP_PKEY_verify_recover_init() function initializes a public key algorithm -context using key B for a verify recover operation. +The EVP_PKEY_verify_recover_init_ex() function initializes a public key +algorithm context for performing signature signed data recovery using the +signature algorithm B. +The signature algorithm B should be fetched using a call to +L. +The EVP_PKEY object associated with B must be compatible with that +algorithm. +B may be NULL in which case the EVP_SIGNATURE algorithm is fetched +implicitly based on the type of EVP_PKEY associated with B. +See L for more information about implict fetches. + +The EVP_PKEY_verify_recover_init() function is the same as +EVP_PKEY_verify_recover_init_ex() except that the EVP_SIGNATURE algorithm is +always implicitly fetched. The EVP_PKEY_verify_recover() function recovers signed data using B. The signature is specified using the B and diff --git a/doc/man3/EVP_SIGNATURE_free.pod b/doc/man3/EVP_SIGNATURE_free.pod new file mode 100644 index 0000000000..3e39b915e7 --- /dev/null +++ b/doc/man3/EVP_SIGNATURE_free.pod @@ -0,0 +1,64 @@ +=pod + +=head1 NAME + +EVP_SIGNATURE_fetch, EVP_SIGNATURE_free, EVP_SIGNATURE_up_ref, +EVP_SIGNATURE_provider +- Functions to manage EVP_SIGNATURE algorithm objects + +=head1 SYNOPSIS + + #include + + EVP_SIGNATURE *EVP_SIGNATURE_fetch(OPENSSL_CTX *ctx, const char *algorithm, + const char *properties); + void EVP_SIGNATURE_free(EVP_SIGNATURE *signature); + int EVP_SIGNATURE_up_ref(EVP_SIGNATURE *signature); + OSSL_PROVIDER *EVP_SIGNATURE_provider(const EVP_SIGNATURE *signature); + +=head1 DESCRIPTION + +EVP_SIGNATURE_fetch() fetches the implementation for the given +B from any provider offering it, within the criteria given +by the B. +The algorithm will be one offering functions for performing signature related +tasks such as signing and verifying. +See L for further information. + +The returned value must eventually be freed with EVP_SIGNATURE_free(). + +EVP_SIGNATURE_free() decrements the reference count for the B +structure. Typically this structure will have been obtained from an earlier call +to EVP_SIGNATURE_fetch(). If the reference count drops to 0 then the +structure is freed. + +EVP_SIGNATURE_up_ref() increments the reference count for an B +structure. + +EVP_SIGNATURE_provider() returns the provider that I was fetched from. + +=head1 RETURN VALUES + +EVP_SIGNATURE_fetch() returns a pointer to an B for success +or B for failure. + +EVP_SIGNATURE_up_ref() returns 1 for success or 0 otherwise. + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +The functions described here were added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut