=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_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(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_derive_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);
+ int EVP_PKEY_derive_set_peer_ex(EVP_PKEY_CTX *ctx, EVP_PKEY *peer,
+ int validate_peer);
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.
+EVP_PKEY_derive_init() initializes a public key algorithm context I<ctx> for
+shared secret derivation using the algorithm given when the context was created
+using L<EVP_PKEY_CTX_new(3)> or variants thereof. The algorithm is used to
+fetch a B<EVP_KEYEXCH> method implicitly, see L<provider(7)/Implicit fetch> for
+more information about implicit fetches.
-The EVP_PKEY_derive_set_peer() function sets the peer key: this will normally
-be a public key.
+EVP_PKEY_derive_init_ex() is the same as EVP_PKEY_derive_init() but additionally
+sets the passed parameters I<params> on the context before returning.
-The EVP_PKEY_derive() derives a shared secret using B<ctx>.
-If B<key> is B<NULL> then the maximum size of the output buffer is written to
-the B<keylen> parameter. If B<key> is not B<NULL> then before the call the
-B<keylen> parameter should contain the length of the B<key> buffer, if the call
-is successful the shared secret is written to B<key> and the amount of data
-written to B<keylen>.
+EVP_PKEY_derive_set_peer_ex() sets the peer key: this will normally
+be a public key. The I<validate_peer> will validate the public key if this value
+is non zero.
+
+EVP_PKEY_derive_set_peer() is similar to EVP_PKEY_derive_set_peer_ex() with
+I<validate_peer> set to 1.
+
+EVP_PKEY_derive() derives a shared secret using I<ctx>.
+If I<key> is NULL then the maximum size of the output buffer is written to the
+I<keylen> parameter. If I<key> is not NULL then before the call the I<keylen>
+parameter should contain the length of the I<key> buffer, if the call is
+successful the shared secret is written to I<key> and the amount of data
+written to I<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(), 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() 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
+=head1 EXAMPLES
Derive shared secret (for example DH or EC keys):
#include <openssl/rsa.h>
EVP_PKEY_CTX *ctx;
+ ENGINE *eng;
unsigned char *skey;
size_t skeylen;
EVP_PKEY *pkey, *peerkey;
- /* NB: assumes pkey, peerkey have been already set up */
+ /* NB: assumes pkey, eng, peerkey have been already set up */
- ctx = EVP_PKEY_CTX_new(pkey);
+ ctx = EVP_PKEY_CTX_new(pkey, eng);
if (!ctx)
/* Error occurred */
if (EVP_PKEY_derive_init(ctx) <= 0)
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 first added to OpenSSL 1.0.0.
+The EVP_PKEY_derive_init(), EVP_PKEY_derive_set_peer() and EVP_PKEY_derive()
+functions were originally added in OpenSSL 1.0.0.
+
+The EVP_PKEY_derive_init_ex() and EVP_PKEY_derive_set_peer_ex() functions were
+added in OpenSSL 3.0.
=head1 COPYRIGHT
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2006-2022 The OpenSSL Project Authors. All Rights Reserved.
-Licensed under the OpenSSL license (the "License"). You may not use
+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>.
projects / openssl.git / blobdiff