1EVP_PKEY_DERIVE(3ossl)              OpenSSL             EVP_PKEY_DERIVE(3ossl)
2
3
4

NAME

6       EVP_PKEY_derive_init, EVP_PKEY_derive_init_ex,
7       EVP_PKEY_derive_set_peer_ex, EVP_PKEY_derive_set_peer, EVP_PKEY_derive
8       - derive public key algorithm shared secret
9

SYNOPSIS

11        #include <openssl/evp.h>
12
13        int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx);
14        int EVP_PKEY_derive_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);
15        int EVP_PKEY_derive_set_peer_ex(EVP_PKEY_CTX *ctx, EVP_PKEY *peer,
16                                        int validate_peer);
17        int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer);
18        int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
19

DESCRIPTION

21       EVP_PKEY_derive_init() initializes a public key algorithm context ctx
22       for shared secret derivation using the algorithm given when the context
23       was created using EVP_PKEY_CTX_new(3) or variants thereof.  The
24       algorithm is used to fetch a EVP_KEYEXCH method implicitly, see
25       "Implicit fetch" in provider(7) for more information about implicit
26       fetches.
27
28       EVP_PKEY_derive_init_ex() is the same as EVP_PKEY_derive_init() but
29       additionally sets the passed parameters params on the context before
30       returning.
31
32       EVP_PKEY_derive_set_peer_ex() sets the peer key: this will normally be
33       a public key. The validate_peer will validate the public key if this
34       value is non zero.
35
36       EVP_PKEY_derive_set_peer() is similar to EVP_PKEY_derive_set_peer_ex()
37       with validate_peer set to 1.
38
39       EVP_PKEY_derive() derives a shared secret using ctx.  If key is NULL
40       then the maximum size of the output buffer is written to the keylen
41       parameter. If key is not NULL then before the call the keylen parameter
42       should contain the length of the key buffer, if the call is successful
43       the shared secret is written to key and the amount of data written to
44       keylen.
45

NOTES

47       After the call to EVP_PKEY_derive_init(), algorithm specific control
48       operations can be performed to set any appropriate parameters for the
49       operation.
50
51       The function EVP_PKEY_derive() can be called more than once on the same
52       context if several operations are performed using the same parameters.
53

RETURN VALUES

55       EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1 for success and 0
56       or a negative value for failure.  In particular a return value of -2
57       indicates the operation is not supported by the public key algorithm.
58

EXAMPLES

60       Derive shared secret (for example DH or EC keys):
61
62        #include <openssl/evp.h>
63        #include <openssl/rsa.h>
64
65        EVP_PKEY_CTX *ctx;
66        ENGINE *eng;
67        unsigned char *skey;
68        size_t skeylen;
69        EVP_PKEY *pkey, *peerkey;
70        /* NB: assumes pkey, eng, peerkey have been already set up */
71
72        ctx = EVP_PKEY_CTX_new(pkey, eng);
73        if (!ctx)
74            /* Error occurred */
75        if (EVP_PKEY_derive_init(ctx) <= 0)
76            /* Error */
77        if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0)
78            /* Error */
79
80        /* Determine buffer length */
81        if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0)
82            /* Error */
83
84        skey = OPENSSL_malloc(skeylen);
85
86        if (!skey)
87            /* malloc failure */
88
89        if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0)
90            /* Error */
91
92        /* Shared secret is skey bytes written to buffer skey */
93

SEE ALSO

95       EVP_PKEY_CTX_new(3), EVP_PKEY_encrypt(3), EVP_PKEY_decrypt(3),
96       EVP_PKEY_sign(3), EVP_PKEY_verify(3), EVP_PKEY_verify_recover(3),
97       EVP_KEYEXCH_fetch(3)
98

HISTORY

100       The EVP_PKEY_derive_init(), EVP_PKEY_derive_set_peer() and
101       EVP_PKEY_derive() functions were originally added in OpenSSL 1.0.0.
102
103       The EVP_PKEY_derive_init_ex() and EVP_PKEY_derive_set_peer_ex()
104       functions were added in OpenSSL 3.0.
105

107       Copyright 2006-2022 The OpenSSL Project Authors. All Rights Reserved.
108
109       Licensed under the Apache License 2.0 (the "License").  You may not use
110       this file except in compliance with the License.  You can obtain a copy
111       in the file LICENSE in the source distribution or at
112       <https://www.openssl.org/source/license.html>.
113
114
115
1163.1.1                             2023-08-31            EVP_PKEY_DERIVE(3ossl)
Impressum