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