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]
--- /dev/null
+=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
=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
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
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
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
=head1 NAME
+EVP_PKEY_CTX_set_params,
EVP_PKEY_CTX_ctrl,
EVP_PKEY_CTX_ctrl_str,
EVP_PKEY_CTX_ctrl_uint64,
#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,
=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.
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
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.
=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.
=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
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
projects / openssl.git / commitdiff