]>
Commit | Line | Data |
---|---|---|
ba702545 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
ee22fca5 | 5 | EVP_PKEY_derive_init, EVP_PKEY_derive_init_ex, |
e454a393 | 6 | EVP_PKEY_derive_set_peer_ex, EVP_PKEY_derive_set_peer, EVP_PKEY_derive |
c0e0984f | 7 | - derive public key algorithm shared secret |
ba702545 DSH |
8 | |
9 | =head1 SYNOPSIS | |
10 | ||
11 | #include <openssl/evp.h> | |
12 | ||
13 | int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx); | |
ee22fca5 | 14 | int EVP_PKEY_derive_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]); |
e454a393 SL |
15 | int EVP_PKEY_derive_set_peer_ex(EVP_PKEY_CTX *ctx, EVP_PKEY *peer, |
16 | int validate_peer); | |
ba702545 DSH |
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 | ||
20 | =head1 DESCRIPTION | |
21 | ||
c0e0984f RL |
22 | EVP_PKEY_derive_init() initializes a public key algorithm context I<ctx> for |
23 | shared secret derivation using the algorithm given when the context was created | |
24 | using L<EVP_PKEY_CTX_new(3)> or variants thereof. The algorithm is used to | |
25 | fetch a B<EVP_KEYEXCH> method implicitly, see L<provider(7)/Implicit fetch> for | |
8c1cbc72 | 26 | more information about implicit fetches. |
c0e0984f | 27 | |
ee22fca5 P |
28 | EVP_PKEY_derive_init_ex() is the same as EVP_PKEY_derive_init() but additionally |
29 | sets the passed parameters I<params> on the context before returning. | |
30 | ||
e454a393 SL |
31 | EVP_PKEY_derive_set_peer_ex() sets the peer key: this will normally |
32 | be a public key. The I<validate_peer> will validate the public key if this value | |
33 | is non zero. | |
34 | ||
e304aa87 | 35 | EVP_PKEY_derive_set_peer() is similar to EVP_PKEY_derive_set_peer_ex() with |
e454a393 | 36 | I<validate_peer> set to 1. |
ba702545 | 37 | |
c0e0984f RL |
38 | EVP_PKEY_derive() derives a shared secret using I<ctx>. |
39 | If I<key> is NULL then the maximum size of the output buffer is written to the | |
40 | I<keylen> parameter. If I<key> is not NULL then before the call the I<keylen> | |
41 | parameter should contain the length of the I<key> buffer, if the call is | |
42 | successful the shared secret is written to I<key> and the amount of data | |
43 | written to I<keylen>. | |
ba702545 DSH |
44 | |
45 | =head1 NOTES | |
46 | ||
fadb57e5 | 47 | After the call to EVP_PKEY_derive_init(), algorithm |
12df11bd MC |
48 | specific control operations can be performed to set any appropriate parameters |
49 | for the operation. | |
ba702545 DSH |
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 | ||
54 | =head1 RETURN VALUES | |
55 | ||
fadb57e5 | 56 | EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1 |
12df11bd MC |
57 | for success and 0 or a negative value for failure. |
58 | In particular a return value of -2 indicates the operation is not supported by | |
59 | the public key algorithm. | |
ba702545 | 60 | |
cda77422 | 61 | =head1 EXAMPLES |
ba702545 DSH |
62 | |
63 | Derive shared secret (for example DH or EC keys): | |
64 | ||
65 | #include <openssl/evp.h> | |
66 | #include <openssl/rsa.h> | |
67 | ||
68 | EVP_PKEY_CTX *ctx; | |
9db6673e | 69 | ENGINE *eng; |
ba702545 DSH |
70 | unsigned char *skey; |
71 | size_t skeylen; | |
72 | EVP_PKEY *pkey, *peerkey; | |
9db6673e | 73 | /* NB: assumes pkey, eng, peerkey have been already set up */ |
ba702545 | 74 | |
9db6673e | 75 | ctx = EVP_PKEY_CTX_new(pkey, eng); |
ba702545 | 76 | if (!ctx) |
2947af32 | 77 | /* Error occurred */ |
ba702545 | 78 | if (EVP_PKEY_derive_init(ctx) <= 0) |
2947af32 | 79 | /* Error */ |
ba702545 | 80 | if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0) |
2947af32 | 81 | /* Error */ |
ba702545 DSH |
82 | |
83 | /* Determine buffer length */ | |
84 | if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0) | |
2947af32 | 85 | /* Error */ |
ba702545 DSH |
86 | |
87 | skey = OPENSSL_malloc(skeylen); | |
88 | ||
89 | if (!skey) | |
2947af32 | 90 | /* malloc failure */ |
1bc74519 | 91 | |
ba702545 | 92 | if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0) |
2947af32 | 93 | /* Error */ |
ba702545 DSH |
94 | |
95 | /* Shared secret is skey bytes written to buffer skey */ | |
96 | ||
97 | =head1 SEE ALSO | |
98 | ||
9b86974e RS |
99 | L<EVP_PKEY_CTX_new(3)>, |
100 | L<EVP_PKEY_encrypt(3)>, | |
101 | L<EVP_PKEY_decrypt(3)>, | |
102 | L<EVP_PKEY_sign(3)>, | |
103 | L<EVP_PKEY_verify(3)>, | |
104 | L<EVP_PKEY_verify_recover(3)>, | |
12df11bd | 105 | L<EVP_KEYEXCH_fetch(3)> |
ba702545 DSH |
106 | |
107 | =head1 HISTORY | |
108 | ||
ee22fca5 P |
109 | The EVP_PKEY_derive_init(), EVP_PKEY_derive_set_peer() and EVP_PKEY_derive() |
110 | functions were originally added in OpenSSL 1.0.0. | |
111 | ||
e454a393 SL |
112 | The EVP_PKEY_derive_init_ex() and EVP_PKEY_derive_set_peer_ex() functions were |
113 | added in OpenSSL 3.0. | |
ba702545 | 114 | |
e2f92610 RS |
115 | =head1 COPYRIGHT |
116 | ||
fecb3aae | 117 | Copyright 2006-2022 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 118 | |
4746f25a | 119 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
120 | this file except in compliance with the License. You can obtain a copy |
121 | in the file LICENSE in the source distribution or at | |
122 | L<https://www.openssl.org/source/license.html>. | |
123 | ||
124 | =cut |