]>
Commit | Line | Data |
---|---|---|
4486d0cd UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
22aa4a3a BB |
5 | DH_generate_key, DH_compute_key, DH_compute_key_padded - perform |
6 | Diffie-Hellman key exchange | |
4486d0cd UM |
7 | |
8 | =head1 SYNOPSIS | |
9 | ||
10 | #include <openssl/dh.h> | |
11 | ||
3dbf8243 MC |
12 | The following functions have been deprecated since OpenSSL 3.0, and can be |
13 | hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, | |
14 | see L<openssl_user_macros(7)>: | |
ada66e78 | 15 | |
4486d0cd UM |
16 | int DH_generate_key(DH *dh); |
17 | ||
22aa4a3a BB |
18 | int DH_compute_key(unsigned char *key, const BIGNUM *pub_key, DH *dh); |
19 | ||
20 | int DH_compute_key_padded(unsigned char *key, const BIGNUM *pub_key, DH *dh); | |
4486d0cd UM |
21 | |
22 | =head1 DESCRIPTION | |
23 | ||
22aa4a3a | 24 | All of the functions described on this page are deprecated. |
ada66e78 P |
25 | Applications should instead use L<EVP_PKEY_derive_init(3)> |
26 | and L<EVP_PKEY_derive(3)>. | |
27 | ||
4486d0cd UM |
28 | DH_generate_key() performs the first step of a Diffie-Hellman key |
29 | exchange by generating private and public DH values. By calling | |
22aa4a3a BB |
30 | DH_compute_key() or DH_compute_key_padded(), these are combined with |
31 | the other party's public value to compute the shared key. | |
4486d0cd UM |
32 | |
33 | DH_generate_key() expects B<dh> to contain the shared parameters | |
34 | B<dh-E<gt>p> and B<dh-E<gt>g>. It generates a random private DH value | |
924875e5 BM |
35 | unless B<dh-E<gt>priv_key> is already set, and computes the |
36 | corresponding public value B<dh-E<gt>pub_key>, which can then be | |
37 | published. | |
4486d0cd UM |
38 | |
39 | DH_compute_key() computes the shared secret from the private DH value | |
40 | in B<dh> and the other party's public value in B<pub_key> and stores | |
41 | it in B<key>. B<key> must point to B<DH_size(dh)> bytes of memory. | |
22aa4a3a BB |
42 | The padding style is RFC 5246 (8.1.2) that strips leading zero bytes. |
43 | It is not constant time due to the leading zero bytes being stripped. | |
44 | The return value should be considered public. | |
45 | ||
46 | DH_compute_key_padded() is similar but stores a fixed number of bytes. | |
47 | The padding style is NIST SP 800-56A (C.1) that retains leading zero bytes. | |
48 | It is constant time due to the leading zero bytes being retained. | |
49 | The return value should be considered public. | |
4486d0cd UM |
50 | |
51 | =head1 RETURN VALUES | |
52 | ||
53 | DH_generate_key() returns 1 on success, 0 otherwise. | |
54 | ||
55 | DH_compute_key() returns the size of the shared secret on success, -1 | |
56 | on error. | |
57 | ||
22aa4a3a BB |
58 | DH_compute_key_padded() returns B<DH_size(dh)> on success, -1 on error. |
59 | ||
9b86974e | 60 | The error codes can be obtained by L<ERR_get_error(3)>. |
4486d0cd UM |
61 | |
62 | =head1 SEE ALSO | |
63 | ||
ada66e78 | 64 | L<EVP_PKEY_derive(3)>, |
b97fdb57 | 65 | L<DH_new(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>, L<DH_size(3)> |
4486d0cd | 66 | |
ada66e78 P |
67 | =head1 HISTORY |
68 | ||
22aa4a3a BB |
69 | DH_compute_key_padded() was added in OpenSSL 1.0.2. |
70 | ||
71 | All of these functions were deprecated in OpenSSL 3.0. | |
ada66e78 | 72 | |
e2f92610 RS |
73 | =head1 COPYRIGHT |
74 | ||
4333b89f | 75 | Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 76 | |
4746f25a | 77 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
78 | this file except in compliance with the License. You can obtain a copy |
79 | in the file LICENSE in the source distribution or at | |
80 | L<https://www.openssl.org/source/license.html>. | |
81 | ||
82 | =cut |