NAME
EVP_PKEY_derive_init
,
EVP_PKEY_derive_set_peer
,
EVP_PKEY_CTX_get0_peerkey
,
EVP_PKEY_derive
—
derive public key algorithm shared
secret
SYNOPSIS
#include
<openssl/evp.h>
int
EVP_PKEY_derive_init
(EVP_PKEY_CTX
*ctx);
int
EVP_PKEY_derive_set_peer
(EVP_PKEY_CTX
*ctx, EVP_PKEY *peerkey);
EVP_PKEY *
EVP_PKEY_CTX_get0_peerkey
(EVP_PKEY_CTX
*ctx);
int
EVP_PKEY_derive
(EVP_PKEY_CTX
*ctx, unsigned char *key, size_t
*keylen);
DESCRIPTION
EVP_PKEY_derive_init
()
initializes the public key algorithm context ctx for
shared secret derivation using the EVP_PKEY object
already stored in ctx. The library provides built-in
support for keys with an
EVP_PKEY_base_id(3) of EVP_PKEY_DH
,
EVP_PKEY_EC
, EVP_PKEY_HKDF
,
and EVP_PKEY_X25519
.
After the call to
EVP_PKEY_derive_init
(),
algorithm specific control operations can optionally be performed to set any
appropriate parameters for the operation.
EVP_PKEY_derive_set_peer
()
configures the ctx, which already needs to be
initialized with EVP_PKEY_derive_init
(),
EVP_PKEY_encrypt_init(3), or
EVP_PKEY_decrypt_init(3), to use the
peerkey, which is normally a public key. In case of
success, the reference count of the peerkey is
incremented by one. Consequently, the caller needs to call
EVP_PKEY_free(3) on the peerkey when the caller
no longer needs it, even if it is still in use by
ctx.
EVP_PKEY_derive
()
derives a shared secret using ctx. If
key is NULL
, then the maximum
size of the output buffer is written to the keylen
parameter. If key is not NULL
then before the call the keylen parameter should
contain the length of the key buffer. If the call is
successful, the shared secret is written to key and
the amount of data written to keylen.
The function
EVP_PKEY_derive
()
can be called more than once on the same context if several operations are
performed using the same parameters.
RETURN VALUES
EVP_PKEY_derive_init
(),
EVP_PKEY_derive_set_peer
(), 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.
For EVP_PKEY_derive_set_peer
(), a return
value of -1 can for example occur if ctx is not
properly initialized, does not contain an EVP_PKEY
that can be retrieved with
EVP_PKEY_CTX_get0_pkey(3), the
EVP_PKEY_id(3) of both keys mismatch, or
EVP_PKEY_cmp_parameters(3) reports mismatching key
parameters.
EVP_PKEY_derive
() fails with a return
value of -1 for example if ctx has not been
successfully initialized with
EVP_PKEY_derive_init
().
EVP_PKEY_CTX_get0_peerkey
() returns an
internal pointer to the peerkey used by
ctx without incrementing its reference count.
EXAMPLES
Derive shared secret (for example DH or EC keys):
#include <openssl/evp.h> #include <openssl/rsa.h> EVP_PKEY_CTX *ctx; unsigned char *skey; size_t skeylen; EVP_PKEY *pkey, *peerkey; /* Assumes that pkey and peerkey have already been set up. */ ctx = EVP_PKEY_CTX_new(pkey, NULL); if (!ctx) /* Error occurred */ if (EVP_PKEY_derive_init(ctx) <= 0) /* Error */ if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0) /* Error */ /* Determine buffer length */ if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0) /* Error */ skey = malloc(skeylen); if (!skey) /* malloc failure */ if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0) /* Error */ /* Shared secret is skey bytes written to buffer skey */
SEE ALSO
EVP_PKEY_CTX_new(3), EVP_PKEY_decrypt(3), EVP_PKEY_encrypt(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), EVP_PKEY_verify_recover(3), X25519(3)
HISTORY
EVP_PKEY_derive_init
(),
EVP_PKEY_derive_set_peer
(),
EVP_PKEY_CTX_get0_peerkey
(), and
EVP_PKEY_derive
() first appeared in OpenSSL 1.0.0
and have been available since OpenBSD 4.9.