]>
Commit | Line | Data |
---|---|---|
0263b992 MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | DH_meth_new, DH_meth_free, DH_meth_dup, DH_meth_get0_name, DH_meth_set1_name, | |
6 | DH_meth_get_flags, DH_meth_set_flags, DH_meth_get0_app_data, | |
7 | DH_meth_set0_app_data, DH_meth_get_generate_key, DH_meth_set_generate_key, | |
8 | DH_meth_get_compute_key, DH_meth_set_compute_key, DH_meth_get_bn_mod_exp, | |
9 | DH_meth_set_bn_mod_exp, DH_meth_get_init, DH_meth_set_init, DH_meth_get_finish, | |
10 | DH_meth_set_finish, DH_meth_get_generate_params, | |
11 | DH_meth_set_generate_params - Routines to build up DH methods | |
12 | ||
13 | =head1 SYNOPSIS | |
14 | ||
15 | #include <openssl/dh.h> | |
16 | ||
ada66e78 P |
17 | Deprecated since OpenSSL 3.0, can be hidden entirely by defining |
18 | B<OPENSSL_API_COMPAT> with a suitable version value, see | |
19 | L<openssl_user_macros(7)>: | |
20 | ||
0263b992 | 21 | DH_METHOD *DH_meth_new(const char *name, int flags); |
e9b77246 | 22 | |
0263b992 | 23 | void DH_meth_free(DH_METHOD *dhm); |
e9b77246 | 24 | |
0263b992 | 25 | DH_METHOD *DH_meth_dup(const DH_METHOD *dhm); |
e9b77246 | 26 | |
0263b992 MC |
27 | const char *DH_meth_get0_name(const DH_METHOD *dhm); |
28 | int DH_meth_set1_name(DH_METHOD *dhm, const char *name); | |
e9b77246 | 29 | |
693be9a2 | 30 | int DH_meth_get_flags(const DH_METHOD *dhm); |
0263b992 | 31 | int DH_meth_set_flags(DH_METHOD *dhm, int flags); |
e9b77246 | 32 | |
0263b992 MC |
33 | void *DH_meth_get0_app_data(const DH_METHOD *dhm); |
34 | int DH_meth_set0_app_data(DH_METHOD *dhm, void *app_data); | |
e9b77246 BB |
35 | |
36 | int (*DH_meth_get_generate_key(const DH_METHOD *dhm))(DH *); | |
37 | int DH_meth_set_generate_key(DH_METHOD *dhm, int (*generate_key)(DH *)); | |
38 | ||
0263b992 | 39 | int (*DH_meth_get_compute_key(const DH_METHOD *dhm)) |
e9b77246 | 40 | (unsigned char *key, const BIGNUM *pub_key, DH *dh); |
0263b992 | 41 | int DH_meth_set_compute_key(DH_METHOD *dhm, |
e9b77246 BB |
42 | int (*compute_key)(unsigned char *key, const BIGNUM *pub_key, DH *dh)); |
43 | ||
0263b992 MC |
44 | int (*DH_meth_get_bn_mod_exp(const DH_METHOD *dhm)) |
45 | (const DH *dh, BIGNUM *r, const BIGNUM *a, const BIGNUM *p, | |
46 | const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx); | |
47 | int DH_meth_set_bn_mod_exp(DH_METHOD *dhm, | |
e9b77246 BB |
48 | int (*bn_mod_exp)(const DH *dh, BIGNUM *r, const BIGNUM *a, |
49 | const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx, | |
50 | BN_MONT_CTX *m_ctx)); | |
51 | ||
0263b992 MC |
52 | int (*DH_meth_get_init(const DH_METHOD *dhm))(DH *); |
53 | int DH_meth_set_init(DH_METHOD *dhm, int (*init)(DH *)); | |
e9b77246 BB |
54 | |
55 | int (*DH_meth_get_finish(const DH_METHOD *dhm))(DH *); | |
56 | int DH_meth_set_finish(DH_METHOD *dhm, int (*finish)(DH *)); | |
57 | ||
0263b992 | 58 | int (*DH_meth_get_generate_params(const DH_METHOD *dhm)) |
e9b77246 | 59 | (DH *, int, int, BN_GENCB *); |
0263b992 | 60 | int DH_meth_set_generate_params(DH_METHOD *dhm, |
e9b77246 | 61 | int (*generate_params)(DH *, int, int, BN_GENCB *)); |
0263b992 MC |
62 | |
63 | =head1 DESCRIPTION | |
64 | ||
ada66e78 P |
65 | All of the functions described on this page are deprecated. |
66 | Applications should instead use the provider APIs. | |
67 | ||
0263b992 | 68 | The B<DH_METHOD> type is a structure used for the provision of custom DH |
a970b14f | 69 | implementations. It provides a set of functions used by OpenSSL for the |
53934822 | 70 | implementation of the various DH capabilities. |
0263b992 MC |
71 | |
72 | DH_meth_new() creates a new B<DH_METHOD> structure. It should be given a | |
73 | unique B<name> and a set of B<flags>. The B<name> should be a NULL terminated | |
74 | string, which will be duplicated and stored in the B<DH_METHOD> object. It is | |
75 | the callers responsibility to free the original string. The flags will be used | |
76 | during the construction of a new B<DH> object based on this B<DH_METHOD>. Any | |
77 | new B<DH> object will have those flags set by default. | |
78 | ||
79 | DH_meth_dup() creates a duplicate copy of the B<DH_METHOD> object passed as a | |
80 | parameter. This might be useful for creating a new B<DH_METHOD> based on an | |
81 | existing one, but with some differences. | |
82 | ||
83 | DH_meth_free() destroys a B<DH_METHOD> structure and frees up any memory | |
84 | associated with it. | |
85 | ||
86 | DH_meth_get0_name() will return a pointer to the name of this DH_METHOD. This | |
87 | is a pointer to the internal name string and so should not be freed by the | |
88 | caller. DH_meth_set1_name() sets the name of the DH_METHOD to B<name>. The | |
89 | string is duplicated and the copy is stored in the DH_METHOD structure, so the | |
90 | caller remains responsible for freeing the memory associated with the name. | |
91 | ||
92 | DH_meth_get_flags() returns the current value of the flags associated with this | |
93 | DH_METHOD. DH_meth_set_flags() provides the ability to set these flags. | |
94 | ||
95 | The functions DH_meth_get0_app_data() and DH_meth_set0_app_data() provide the | |
96 | ability to associate implementation specific data with the DH_METHOD. It is | |
97 | the application's responsibility to free this data before the DH_METHOD is | |
98 | freed via a call to DH_meth_free(). | |
99 | ||
100 | DH_meth_get_generate_key() and DH_meth_set_generate_key() get and set the | |
101 | function used for generating a new DH key pair respectively. This function will | |
102 | be called in response to the application calling DH_generate_key(). The | |
103 | parameter for the function has the same meaning as for DH_generate_key(). | |
104 | ||
105 | DH_meth_get_compute_key() and DH_meth_set_compute_key() get and set the | |
106 | function used for computing a new DH shared secret respectively. This function | |
107 | will be called in response to the application calling DH_compute_key(). The | |
108 | parameters for the function have the same meaning as for DH_compute_key(). | |
109 | ||
110 | DH_meth_get_bn_mod_exp() and DH_meth_set_bn_mod_exp() get and set the function | |
111 | used for computing the following value: | |
112 | ||
113 | r = a ^ p mod m | |
114 | ||
115 | This function will be called by the default OpenSSL function for | |
116 | DH_generate_key(). The result is stored in the B<r> parameter. This function | |
117 | may be NULL unless using the default generate key function, in which case it | |
118 | must be present. | |
119 | ||
120 | DH_meth_get_init() and DH_meth_set_init() get and set the function used | |
121 | for creating a new DH instance respectively. This function will be | |
122 | called in response to the application calling DH_new() (if the current default | |
123 | DH_METHOD is this one) or DH_new_method(). The DH_new() and DH_new_method() | |
124 | functions will allocate the memory for the new DH object, and a pointer to this | |
125 | newly allocated structure will be passed as a parameter to the function. This | |
126 | function may be NULL. | |
127 | ||
128 | DH_meth_get_finish() and DH_meth_set_finish() get and set the function used | |
129 | for destroying an instance of a DH object respectively. This function will be | |
130 | called in response to the application calling DH_free(). A pointer to the DH | |
131 | to be destroyed is passed as a parameter. The destroy function should be used | |
132 | for DH implementation specific clean up. The memory for the DH itself should | |
133 | not be freed by this function. This function may be NULL. | |
134 | ||
135 | DH_meth_get_generate_params() and DH_meth_set_generate_params() get and set the | |
136 | function used for generating DH parameters respectively. This function will be | |
137 | called in response to the application calling DH_generate_parameters_ex() (or | |
138 | DH_generate_parameters()). The parameters for the function have the same | |
139 | meaning as for DH_generate_parameters_ex(). This function may be NULL. | |
140 | ||
141 | =head1 RETURN VALUES | |
142 | ||
143 | DH_meth_new() and DH_meth_dup() return the newly allocated DH_METHOD object | |
144 | or NULL on failure. | |
145 | ||
146 | DH_meth_get0_name() and DH_meth_get_flags() return the name and flags | |
147 | associated with the DH_METHOD respectively. | |
148 | ||
149 | All other DH_meth_get_*() functions return the appropriate function pointer | |
150 | that has been set in the DH_METHOD, or NULL if no such pointer has yet been | |
151 | set. | |
152 | ||
153 | DH_meth_set1_name() and all DH_meth_set_*() functions return 1 on success or | |
154 | 0 on failure. | |
155 | ||
156 | =head1 SEE ALSO | |
157 | ||
b97fdb57 | 158 | L<DH_new(3)>, L<DH_new(3)>, L<DH_generate_parameters(3)>, L<DH_generate_key(3)>, |
0263b992 MC |
159 | L<DH_set_method(3)>, L<DH_size(3)>, L<DH_get0_pqg(3)> |
160 | ||
161 | =head1 HISTORY | |
162 | ||
ada66e78 P |
163 | All of these functions were deprecated in OpenSSL 3.0. |
164 | ||
e90fc053 | 165 | The functions described here were added in OpenSSL 1.1.0. |
0263b992 | 166 | |
e2f92610 RS |
167 | =head1 COPYRIGHT |
168 | ||
c4d3c19b | 169 | Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 170 | |
4746f25a | 171 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
172 | this file except in compliance with the License. You can obtain a copy |
173 | in the file LICENSE in the source distribution or at | |
174 | L<https://www.openssl.org/source/license.html>. | |
175 | ||
176 | =cut |