diff options
author | Matt Caswell <matt@openssl.org> | 2019-09-04 12:46:02 +0100 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2019-09-09 14:00:00 +0100 |
commit | 9c45222ddc36124b8826d98dc0794f3eef1e5f0b (patch) | |
tree | ab9140d515d73f044944d4998244b047282ada0d /doc | |
parent | 21fb7067228e39633755aeba251e925634e64870 (diff) |
Revise EVP_PKEY param handling
We add new functions for getting parameters and discovering the gettable
and settable parameters. We also make EVP_PKEY_CTX_get_signature_md() a
function and implement it in terms of the new functions.
This enables applications to discover the set of parameters that are
supported for a given algorithm implementation.
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9753)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/EVP_PKEY_CTX_ctrl.pod | 63 | ||||
-rw-r--r-- | doc/man7/provider-keyexch.pod | 28 | ||||
-rw-r--r-- | doc/man7/provider-signature.pod | 40 |
3 files changed, 87 insertions, 44 deletions
diff --git a/doc/man3/EVP_PKEY_CTX_ctrl.pod b/doc/man3/EVP_PKEY_CTX_ctrl.pod index 9d1812f6bd..18b984162e 100644 --- a/doc/man3/EVP_PKEY_CTX_ctrl.pod +++ b/doc/man3/EVP_PKEY_CTX_ctrl.pod @@ -2,7 +2,10 @@ =head1 NAME +EVP_PKEY_CTX_get_params, +EVP_PKEY_CTX_gettable_params, EVP_PKEY_CTX_set_params, +EVP_PKEY_CTX_settable_params, EVP_PKEY_CTX_ctrl, EVP_PKEY_CTX_ctrl_str, EVP_PKEY_CTX_ctrl_uint64, @@ -63,7 +66,10 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len #include <openssl/evp.h> + int EVP_PKEY_CTX_get_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params); + const OSSL_PARAM *EVP_PKEY_CTX_gettable_params(EVP_PKEY_CTX *ctx); int EVP_PKEY_CTX_set_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params); + const OSSL_PARAM *EVP_PKEY_CTX_settable_params(EVP_PKEY_CTX *ctx); int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, int cmd, int p1, void *p2); @@ -144,16 +150,20 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len =head1 DESCRIPTION -The EVP_PKEY_CTX_set_params() function sends arbitrary parameters to the -algorithm implementation. +The EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params() functions get and +send arbitrary parameters from and to the algorithm implementation respectively. Not all parameters may be supported by all providers. See L<OSSL_PROVIDER(3)> for more information on providers. See L<OSSL_PARAM(3)> for more information on parameters. +These functions must only be called after the EVP_PKEY_CTX has been initialised +for use in an operation (for example by L<EVP_PKEY_sign_init_ex(3)>, +L<EVP_PKEY_derive_init_ex(3)> or other similar functions). + The parameters currently supported by the default provider are: =over 4 -=item OSSL_EXCHANGE_PARAM_PAD (uint type) +=item "exchange-pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <uint> Sets the DH padding mode. If B<OSSL_EXCHANGE_PARAM_PAD> is 1 then the shared secret is padded with zeroes @@ -161,19 +171,29 @@ up to the size of the DH prime B<p>. If B<OSSL_EXCHANGE_PARAM_PAD> is zero (the default) then no padding is performed. -=item OSSL_SIGNATURE_PARAM_DIGEST (UTF8 string type) +=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <utf8 string> -Sets the name of the digest algorithm used for the input to the signature -functions. +Gets and sets the name of the digest algorithm used for the input to the +signature functions. -=item OSSL_SIGNATURE_PARAM_DIGEST_SIZE (size_t type) +=item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <size_t> -Sets the output size of the digest algorithm used for the input to the signature -functions. +Gets and 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 +EVP_PKEY_CTX_gettable_params() and EVP_PKEY_CTX_settable_params() gets a +constant B<OSSL_PARAM> array that decribes the gettable and +settable parameters for the current algorithm implementation, i.e. parameters +that can be used with EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params() +respectively. +See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor. +These functions must only be called after the EVP_PKEY_CTX has been initialised +for use in an operation (for example by L<EVP_PKEY_sign_init_ex(3)>, +L<EVP_PKEY_derive_init_ex(3)> or other similar functions). + The function EVP_PKEY_CTX_ctrl() sends a control operation to the context B<ctx>. The key type used must match B<keytype> if it is not -1. The parameter B<optype> is a mask indicating which operations the control can be applied to. @@ -199,13 +219,13 @@ B<pkeyutl>, B<genpkey> and B<req> commands. The function EVP_PKEY_CTX_md() sends a message digest control operation to the context B<ctx>. The message digest is specified by its name B<md>. -All the remaining "functions" are implemented as macros. +The EVP_PKEY_CTX_set_signature_md() function sets the message digest type used +in a signature. It can be used in the RSA, DSA and ECDSA algorithms. -The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used +The EVP_PKEY_CTX_get_signature_md() function gets the message digest type used in a signature. It can be used in the RSA, DSA and ECDSA algorithms. -The EVP_PKEY_CTX_get_signature_md() macro gets the message digest type used in a -signature. It can be used in the RSA, DSA and ECDSA algorithms. +All the remaining "functions" are implemented as macros. Key generation typically involves setting up parameters to be used and generating the private and public key data. Some algorithm implementations @@ -471,9 +491,15 @@ allocate adequate memory space for the B<id> before calling EVP_PKEY_CTX_get1_id =head1 RETURN VALUES -EVP_PKEY_CTX_ctrl() and its macros return a positive value for success and 0 -or a negative value for failure. In particular a return value of -2 -indicates the operation is not supported by the public key algorithm. +EVP_PKEY_CTX_set_params() returns 1 for success or 0 otherwise. +EVP_PKEY_CTX_settable_params() returns an OSSL_PARAM array on success or NULL on +error. +It may also return NULL if there are no settable parameters available. + +EVP_PKEY_CTX_set_signature_md(), EVP_PKEY_CTX_set_dh_pad(), EVP_PKEY_CTX_ctrl() +and its macros return a positive value for success and 0 or a negative value for +failure. In particular a return value of -2 indicates the operation is not +supported by the public key algorithm. =head1 SEE ALSO @@ -492,8 +518,9 @@ The EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and EVP_PKEY_CTX_get1_id_len() macros were added in 1.1.1, other functions were added in OpenSSL 1.0.0. -EVP_PKEY_CTX_set_dh_pad() was a macro in OpenSSL 1.1.1 and below. -From OpenSSL 3.0 it is a function. +EVP_PKEY_CTX_get_signature_md(), EVP_PKEY_CTX_set_signature_md() and +EVP_PKEY_CTX_set_dh_pad() were macros in OpenSSL 1.1.1 and below. From OpenSSL +3.0 they are functions. =head1 COPYRIGHT diff --git a/doc/man7/provider-keyexch.pod b/doc/man7/provider-keyexch.pod index 71830c12c6..9ef294395c 100644 --- a/doc/man7/provider-keyexch.pod +++ b/doc/man7/provider-keyexch.pod @@ -29,8 +29,8 @@ provider-keyexch - The keyexch library E<lt>-E<gt> provider functions size_t outlen); /* Key Exchange parameters */ - int OP_keyexch_set_params(void *ctx, const OSSL_PARAM params[]); - + int OP_keyexch_set_ctx_params(void *ctx, const OSSL_PARAM params[]); + const OSSL_PARAM *OP_keyexch_settable_ctx_params(void); =head1 DESCRIPTION @@ -61,15 +61,16 @@ For example, the "function" OP_keyexch_newctx() has these: B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as macros in L<openssl-core_numbers.h(7)>, as follows: - OP_keyexch_newctx OSSL_FUNC_KEYEXCH_NEWCTX - OP_keyexch_freectx OSSL_FUNC_KEYEXCH_FREECTX - OP_keyexch_dupctx OSSL_FUNC_KEYEXCH_DUPCTX + OP_keyexch_newctx OSSL_FUNC_KEYEXCH_NEWCTX + OP_keyexch_freectx OSSL_FUNC_KEYEXCH_FREECTX + OP_keyexch_dupctx OSSL_FUNC_KEYEXCH_DUPCTX - OP_keyexch_init OSSL_FUNC_KEYEXCH_INIT - OP_keyexch_set_peer OSSL_FUNC_KEYEXCH_SET_PEER - OP_keyexch_derive OSSL_FUNC_KEYEXCH_DERIVE + OP_keyexch_init OSSL_FUNC_KEYEXCH_INIT + OP_keyexch_set_peer OSSL_FUNC_KEYEXCH_SET_PEER + OP_keyexch_derive OSSL_FUNC_KEYEXCH_DERIVE - OP_keyexch_set_params OSSL_FUNC_KEYEXCH_SET_PARAMS + OP_keyexch_set_ctx_params OSSL_FUNC_KEYEXCH_SET_CTX_PARAMS + OP_keyexch_settable_ctx_params OSSL_FUNC_KEYEXCH_SETTABLE_CTX_PARAMS A key exchange algorithm implementation may not implement all of these functions. In order to be a consistent set of functions a provider must implement @@ -127,8 +128,8 @@ written to B<*secretlen>. See L<OSSL_PARAM(3)> for further details on the parameters structure used by the OP_keyexch_set_params() function. -OP_keyexch_set_params() sets key exchange parameters associated with the given -provider side key exchange context B<ctx> to B<params>. +OP_keyexch_set_ctx_params() sets key exchange parameters associated with the +given provider side key exchange context B<ctx> to B<params>. Any parameter settings are additional to any that were previously set. Parameters currently recognised by built-in key exchange algorithms are as @@ -151,6 +152,11 @@ possible secret size. =back +OP_keyexch_settable_ctx_params() gets a constant B<OSSL_PARAM> array that +decribes the settable parameters, i.e. parameters that can be used with +OP_signature_set_ctx_params(). +See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor. + =head1 RETURN VALUES OP_keyexch_newctx() and OP_keyexch_dupctx() should return the newly created diff --git a/doc/man7/provider-signature.pod b/doc/man7/provider-signature.pod index 3894afd03c..1ab4831035 100644 --- a/doc/man7/provider-signature.pod +++ b/doc/man7/provider-signature.pod @@ -39,8 +39,10 @@ provider-signature - The signature library E<lt>-E<gt> provider functions const unsigned char *sig, size_t siglen); /* Signature parameters */ - int OP_signature_set_params(void *ctx, const OSSL_PARAM params[]); - + int OP_signature_get_ctx_params(void *ctx, OSSL_PARAM params[]); + const OSSL_PARAM *OP_signature_gettable_ctx_params(void); + int OP_signature_set_ctx_params(void *ctx, const OSSL_PARAM params[]); + const OSSL_PARAM *OP_signature_settable_ctx_params(void); =head1 DESCRIPTION @@ -86,7 +88,10 @@ macros in L<openssl-core_numbers.h(7)>, as follows: OP_signature_verify_recover_init OSSL_FUNC_SIGNATURE_VERIFY_RECOVER_INIT OP_signature_verify_recover OSSL_FUNC_SIGNATURE_VERIFY_RECOVER - OP_signature_set_params OSSL_FUNC_SIGNATURE_SET_PARAMS + OP_signature_get_ctx_params OSSL_FUNC_SIGNATURE_GET_CTX_PARAMS + OP_signature_gettable_ctx_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_PARAMS + OP_signature_set_ctx_params OSSL_FUNC_SIGNATURE_SET_CTX_PARAMS + OP_signature_settable_ctx_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_PARAMS A signature algorithm implementation may not implement all of these functions. In order to be a consistent set of functions a provider must implement @@ -174,10 +179,12 @@ the B<routlen> parameter. =head2 Signature Parameters See L<OSSL_PARAM(3)> for further details on the parameters structure used by -the OP_signature_set_params() function. +the OP_signature_get_ctx_params() and OP_signature_set_ctx_params() functions. -OP_signature_set_params() sets signature parameters associated with the given -provider side key exchange context B<ctx> to B<params>. +OP_signature_get_ctx_params() gets signature parameters associated with the +given provider side signature context B<ctx> and stored them in B<params>. +OP_signature_set_ctx_params() sets the signature parameters associated with the +given provider side signature context B<ctx> to B<params>. Any parameter settings are additional to any that were previously set. Parameters currently recognised by built-in signature algorithms are as @@ -187,27 +194,30 @@ algorithms: =over 4 -=item B<OSSL_SIGNATURE_PARAM_DIGEST> (UTF8 string) +=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <utf8 string> -Sets the name of the digest algorithm used for the input to the signature +Get or sets the name of the digest algorithm used for the input to the signature functions. -=item B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE> (size_t) +=item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <size_t> -Sets the output size of the digest algorithm used for the input to the signature -functions. +Gets or sets the output size of the digest algorithm used for the input to the +signature functions. =back +OP_signature_gettable_ctx_params() and OP_signature_settable_ctx_params() get a +constant B<OSSL_PARAM> array that decribes the gettable and settable parameters, +i.e. parameters that can be used with OP_signature_get_ctx_params() and +OP_signature_set_ctx_params() respectively. +See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor. + =head1 RETURN VALUES OP_signature_newctx() and OP_signature_dupctx() should return the newly created provider side signature, or NULL on failure. -OP_signature_sign_init(), OP_signature_sign(), OP_signature_verify_init(), -OP_signature_verify(), OP_signature_verify_recover_init(), -OP_signature_verify_recover() and OP_signature_set_params() should return 1 for -success or 0 on error. +All other functions should return 1 for success or 0 on error. =head1 SEE ALSO |