Deprecate the low level Diffie-Hellman functions.
[openssl.git] / doc / man3 / DH_generate_key.pod
1 =pod
2
3 =head1 NAME
4
5 DH_generate_key, DH_compute_key - perform Diffie-Hellman key exchange
6
7 =head1 SYNOPSIS
8
9  #include <openssl/dh.h>
10
11 Deprecated since OpenSSL 3.0, can be hidden entirely by defining
12 B<OPENSSL_API_COMPAT> with a suitable version value, see
13 L<openssl_user_macros(7)>:
14
15  int DH_generate_key(DH *dh);
16
17  int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh);
18
19 =head1 DESCRIPTION
20
21 Both of the functions described on this page are deprecated.
22 Applications should instead use L<EVP_PKEY_derive_init(3)>
23 and L<EVP_PKEY_derive(3)>.
24
25 DH_generate_key() performs the first step of a Diffie-Hellman key
26 exchange by generating private and public DH values. By calling
27 DH_compute_key(), these are combined with the other party's public
28 value to compute the shared key.
29
30 DH_generate_key() expects B<dh> to contain the shared parameters
31 B<dh-E<gt>p> and B<dh-E<gt>g>. It generates a random private DH value
32 unless B<dh-E<gt>priv_key> is already set, and computes the
33 corresponding public value B<dh-E<gt>pub_key>, which can then be
34 published.
35
36 DH_compute_key() computes the shared secret from the private DH value
37 in B<dh> and the other party's public value in B<pub_key> and stores
38 it in B<key>. B<key> must point to B<DH_size(dh)> bytes of memory.
39
40 =head1 RETURN VALUES
41
42 DH_generate_key() returns 1 on success, 0 otherwise.
43
44 DH_compute_key() returns the size of the shared secret on success, -1
45 on error.
46
47 The error codes can be obtained by L<ERR_get_error(3)>.
48
49 =head1 SEE ALSO
50
51 L<EVP_PKEY_derive(3)>,
52 L<DH_new(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>, L<DH_size(3)>
53
54 =head1 HISTORY
55
56 Both of these functions were deprecated in OpenSSL 3.0.
57
58 =head1 COPYRIGHT
59
60 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
61
62 Licensed under the Apache License 2.0 (the "License").  You may not use
63 this file except in compliance with the License.  You can obtain a copy
64 in the file LICENSE in the source distribution or at
65 L<https://www.openssl.org/source/license.html>.
66
67 =cut