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