EVP_PKEY_DERIVE(3) | Library Functions Manual | EVP_PKEY_DERIVE(3)

# 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

library “libcrypto”
`#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.

June 8, 2025 | Debian