OpenBSD manual page server

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_GOSTR01, 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;
ENGINE *eng;
unsigned char *skey;
size_t skeylen;
EVP_PKEY *pkey, *peerkey;

/* Assumes that pkey, eng, and peerkey have already been set up. */
ctx = EVP_PKEY_CTX_new(pkey, eng);
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_meth_set_derive(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.