diff options
| -rw-r--r-- | CHANGES | 11 | ||||
| -rw-r--r-- | doc/man3/EVP_KEYEXCH_free.pod | 46 | ||||
| -rw-r--r-- | doc/man3/EVP_MD_fetch.pod | 14 | ||||
| -rw-r--r-- | doc/man3/EVP_PKEY_CTX_ctrl.pod | 30 | ||||
| -rw-r--r-- | doc/man3/EVP_PKEY_derive.pod | 36 |
5 files changed, 124 insertions, 13 deletions
@@ -9,6 +9,17 @@ Changes between 1.1.1 and 3.0.0 [xx XXX xxxx] + *) A new type, EVP_KEYEXCH, has been introduced to represent key exchange + algorithms. An implementation of a key exchange algorithm can be obtained + by using the function EVP_KEYEXCH_fetch(). An EVP_KEYEXCH algorithm can be + used in a call to EVP_PKEY_derive_init_ex() which works in a similar way to + the older EVP_PKEY_derive_init() function. See the man pages for the new + functions for further details. + [Matt Caswell] + + *) The EVP_PKEY_CTX_set_dh_pad() macro has now been converted to a function. + [Matt Caswell] + *) Removed the function names from error messages and deprecated the xxx_F_xxx define's. [Rich Salz] diff --git a/doc/man3/EVP_KEYEXCH_free.pod b/doc/man3/EVP_KEYEXCH_free.pod new file mode 100644 index 0000000000..d10d768b97 --- /dev/null +++ b/doc/man3/EVP_KEYEXCH_free.pod @@ -0,0 +1,46 @@ +=pod + +=head1 NAME + +EVP_KEYEXCH_free, EVP_KEYEXCH_up_ref +- Functions to manage EVP_KEYEXCH algorithm objects + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + void EVP_KEYEXCH_free(EVP_KEYEXCH *exchange); + int EVP_KEYEXCH_up_ref(EVP_KEYEXCH *exchange); + +=head1 DESCRIPTION + +EVP_KEYEXCH_free() decrements the reference count for the B<EVP_KEYEXCH> +structure. Typically this structure will have been obtained from an earlier call +to L<EVP_KEYEXCH_fetch(3)>. If the reference count drops to 0 then the +structure is freed. + +EVP_KEYEXCH_up_ref() increments the reference count for an B<EVP_KEYEXCH> +structure. + +=head1 RETURN VALUES + +EVP_KEYEXCH_up_ref() returns 1 for success or 0 otherwise. + +=head1 SEE ALSO + +L<EVP_KEYEXCH_fetch(3)> + +=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<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man3/EVP_MD_fetch.pod b/doc/man3/EVP_MD_fetch.pod index 1e43b4fb93..11390d0e94 100644 --- a/doc/man3/EVP_MD_fetch.pod +++ b/doc/man3/EVP_MD_fetch.pod @@ -2,7 +2,7 @@ =head1 NAME -EVP_MD_fetch, EVP_CIPHER_fetch +EVP_MD_fetch, EVP_CIPHER_fetch, EVP_KEYEXCH_fetch - Functions to explicitly fetch algorithm implementations =head1 SYNOPSIS @@ -13,6 +13,8 @@ EVP_MD_fetch, EVP_CIPHER_fetch const char *properties); EVP_CIPHER *EVP_CIPHER_fetch(OPENSSL_CTX *ctx, const char *algorithm, const char *properties); + EVP_KEYEXCH *EVP_KEYEXCH_fetch(OPENSSL_CTX *ctx, const char *algorithm, + const char *properties); =head1 DESCRIPTION @@ -38,6 +40,10 @@ Represents a Message Authentication Code algorithm. Represents a Key Derivation Function algorithm. +=item B<EVP_KEYEXCH> + +Represents a Key Exchange algorithm. + =back The algorithm objects may or may not have an associated algorithm @@ -62,6 +68,12 @@ Typically, this will return an implementation of the appropriate algorithm from the default provider unless the default search criteria have been changed and/or different providers have been loaded. +Implicit fetching can also occur with functions such as +L<EVP_PKEY_CTX_derive_init_ex(3)> where a NULL algorithm parameter is supplied. +In this case an algorithm implementation is implicitly fetched using default +search criteria and an algorithm name that is consistent with the type of +EVP_PKEY being used. + =item Explicit Fetch With explicit fetch an application uses one of the "fetch" functions to obtain diff --git a/doc/man3/EVP_PKEY_CTX_ctrl.pod b/doc/man3/EVP_PKEY_CTX_ctrl.pod index 1bab6d16ea..369fc0f9d0 100644 --- a/doc/man3/EVP_PKEY_CTX_ctrl.pod +++ b/doc/man3/EVP_PKEY_CTX_ctrl.pod @@ -2,6 +2,7 @@ =head1 NAME +EVP_PKEY_CTX_set_params, EVP_PKEY_CTX_ctrl, EVP_PKEY_CTX_ctrl_str, EVP_PKEY_CTX_ctrl_uint64, @@ -62,6 +63,8 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len #include <openssl/evp.h> + int EVP_PKEY_CTX_set_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params); + int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, int cmd, int p1, void *p2); int EVP_PKEY_CTX_ctrl_uint64(EVP_PKEY_CTX *ctx, int keytype, int optype, @@ -141,6 +144,25 @@ 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. +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. +The parameters currently supported by the default provider are: + +=over 4 + +=item OSSL_EXCHANGE_PARAM_PAD (int type) + +Sets the DH padding mode. +If B<OSSL_EXCHANGE_PARAM_PAD> is 1 then the shared secret is padded with zeroes +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. + +=back + 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. @@ -290,8 +312,9 @@ The EVP_PKEY_CTX_set_dh_paramgen_type() macro sets the key type for DH parameter generation. Use 0 for PKCS#3 DH and 1 for X9.42 DH. The default is 0. -The EVP_PKEY_CTX_set_dh_pad() macro sets the DH padding mode. If B<pad> is -1 the shared secret is padded with zeroes up to the size of the DH prime B<p>. +The EVP_PKEY_CTX_set_dh_pad() function sets the DH padding mode. +If B<pad> is 1 the shared secret is padded with zeroes up to the size of the DH +prime B<p>. If B<pad> is zero (the default) then no padding is performed. EVP_PKEY_CTX_set_dh_nid() sets the DH parameters to values corresponding to @@ -458,6 +481,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. + =head1 COPYRIGHT Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man3/EVP_PKEY_derive.pod b/doc/man3/EVP_PKEY_derive.pod index a6747f410c..8d5432688b 100644 --- a/doc/man3/EVP_PKEY_derive.pod +++ b/doc/man3/EVP_PKEY_derive.pod @@ -2,20 +2,33 @@ =head1 NAME -EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive public key algorithm shared secret +EVP_PKEY_derive_init, EVP_PKEY_derive_init_ex, EVP_PKEY_derive_set_peer, +EVP_PKEY_derive - derive public key algorithm shared secret =head1 SYNOPSIS #include <openssl/evp.h> + int EVP_PKEY_derive_init_ex(EVP_PKEY_CTX *ctx, EVP_KEYEXCH *exchange); int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx); int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer); int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen); =head1 DESCRIPTION -The EVP_PKEY_derive_init() function initializes a public key algorithm -context using key B<pkey> for shared secret derivation. +The EVP_PKEY_derive_init_ex() function initializes a public key algorithm +context for shared secret derivation using the key exchange algorithm +B<exchange>. +The key exchange algorithm B<exchange> should be fetched using a call to +L<EVP_KEYEXCH_fetch(3)>. +The EVP_PKEY object associated with B<ctx> must be compatible with that +algorithm. +B<exchange> may be NULL in which case the EVP_KEYEXCH algorithm is fetched +implicitly based on the type of EVP_PKEY associated with B<ctx>. +See L<EVP_KEYEXCH_fetch(3)> 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_set_peer() function sets the peer key: this will normally be a public key. @@ -29,18 +42,19 @@ written to B<keylen>. =head1 NOTES -After the call to EVP_PKEY_derive_init() algorithm specific control -operations can be performed to set any appropriate parameters for the -operation. +After the call to EVP_PKEY_derive_init() or EVP_PKEY_derive_init_ex() algorithm +specific control operations can be performed to set any appropriate parameters +for the operation. The function EVP_PKEY_derive() can be called more than once on the same context if several operations are performed using the same parameters. =head1 RETURN VALUES -EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1 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_derive_init_ex(), EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1 +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 EXAMPLE @@ -86,10 +100,12 @@ L<EVP_PKEY_decrypt(3)>, L<EVP_PKEY_sign(3)>, L<EVP_PKEY_verify(3)>, L<EVP_PKEY_verify_recover(3)>, +L<EVP_KEYEXCH_fetch(3)> =head1 HISTORY -These functions were added in OpenSSL 1.0.0. +These functions were added in OpenSSL 1.0.0. The EVP_PKEY_derive_init_ex() +function was added in OpenSSL 3.0. =head1 COPYRIGHT |