ce01bb34633a869b9ef9a2d0c6b377ce3738bebc
[strongswan.git] / src / libstrongswan / crypto / diffie_hellman.h
1 /*
2 * Copyright (C) 2010 Tobias Brunner
3 * Copyright (C) 2005-2007 Martin Willi
4 * Copyright (C) 2005 Jan Hutter
5 * HSR Hochschule fuer Technik Rapperswil
6 *
7 * This program is free software; you can redistribute it and/or modify it
8 * under the terms of the GNU General Public License as published by the
9 * Free Software Foundation; either version 2 of the License, or (at your
10 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
11 *
12 * This program is distributed in the hope that it will be useful, but
13 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
14 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15 * for more details.
16 */
17
18 /**
19 * @defgroup diffie_hellman diffie_hellman
20 * @{ @ingroup crypto
21 */
22
23 #ifndef DIFFIE_HELLMAN_H_
24 #define DIFFIE_HELLMAN_H_
25
26 typedef enum diffie_hellman_group_t diffie_hellman_group_t;
27 typedef struct diffie_hellman_t diffie_hellman_t;
28 typedef struct diffie_hellman_params_t diffie_hellman_params_t;
29
30 #include <library.h>
31
32 /**
33 * Diffie-Hellman group.
34 *
35 * The modulus (or group) to use for a Diffie-Hellman calculation.
36 * See IKEv2 RFC 3.3.2 and RFC 3526.
37 *
38 * ECP groups are defined in RFC 4753 and RFC 5114.
39 * ECC Brainpool groups are defined in RFC 6954.
40 * Curve25519 and Curve448 groups are defined in RFC 8031.
41 */
42 enum diffie_hellman_group_t {
43 MODP_NONE = 0,
44 MODP_768_BIT = 1,
45 MODP_1024_BIT = 2,
46 MODP_1536_BIT = 5,
47 MODP_2048_BIT = 14,
48 MODP_3072_BIT = 15,
49 MODP_4096_BIT = 16,
50 MODP_6144_BIT = 17,
51 MODP_8192_BIT = 18,
52 ECP_256_BIT = 19,
53 ECP_384_BIT = 20,
54 ECP_521_BIT = 21,
55 MODP_1024_160 = 22,
56 MODP_2048_224 = 23,
57 MODP_2048_256 = 24,
58 ECP_192_BIT = 25,
59 ECP_224_BIT = 26,
60 ECP_224_BP = 27,
61 ECP_256_BP = 28,
62 ECP_384_BP = 29,
63 ECP_512_BP = 30,
64 CURVE_25519 = 31,
65 CURVE_448 = 32,
66 /** insecure NULL diffie hellman group for testing, in PRIVATE USE */
67 MODP_NULL = 1024,
68 /** MODP group with custom generator/prime */
69 /** Parameters defined by IEEE 1363.1, in PRIVATE USE */
70 NTRU_112_BIT = 1030,
71 NTRU_128_BIT = 1031,
72 NTRU_192_BIT = 1032,
73 NTRU_256_BIT = 1033,
74 NH_128_BIT = 1040,
75 /** internally used DH group with additional parameters g and p, outside
76 * of PRIVATE USE (i.e. IKEv2 DH group range) so it can't be negotiated */
77 MODP_CUSTOM = 65536,
78 };
79
80 /**
81 * enum name for diffie_hellman_group_t.
82 */
83 extern enum_name_t *diffie_hellman_group_names;
84
85 /**
86 * Implementation of the Diffie-Hellman algorithm, as in RFC2631.
87 */
88 struct diffie_hellman_t {
89
90 /**
91 * Returns the shared secret of this diffie hellman exchange.
92 *
93 * Space for returned secret is allocated and must be freed by the caller.
94 *
95 * @param secret shared secret will be written into this chunk
96 * @return TRUE if shared secret computed successfully
97 */
98 bool (*get_shared_secret)(diffie_hellman_t *this, chunk_t *secret)
99 __attribute__((warn_unused_result));
100
101 /**
102 * Sets the public value of partner.
103 *
104 * Chunk gets cloned and can be destroyed afterwards.
105 *
106 * @param value public value of partner
107 * @return TRUE if other public value verified and set
108 */
109 bool (*set_other_public_value)(diffie_hellman_t *this, chunk_t value)
110 __attribute__((warn_unused_result));
111
112 /**
113 * Gets the own public value to transmit.
114 *
115 * Space for returned chunk is allocated and must be freed by the caller.
116 *
117 * @param value public value of caller is stored at this location
118 * @return TRUE if public value retrieved
119 */
120 bool (*get_my_public_value) (diffie_hellman_t *this, chunk_t *value)
121 __attribute__((warn_unused_result));
122
123 /**
124 * Set an explicit own private value to use.
125 *
126 * Calling this method is usually not required, as the DH backend generates
127 * an appropriate private value itself. It is optional to implement, and
128 * used mostly for testing purposes.
129 *
130 * @param value private value to set
131 */
132 bool (*set_private_value)(diffie_hellman_t *this, chunk_t value)
133 __attribute__((warn_unused_result));
134
135 /**
136 * Get the DH group used.
137 *
138 * @return DH group set in construction
139 */
140 diffie_hellman_group_t (*get_dh_group) (diffie_hellman_t *this);
141
142 /**
143 * Destroys a diffie_hellman_t object.
144 */
145 void (*destroy) (diffie_hellman_t *this);
146 };
147
148 /**
149 * Parameters for a specific diffie hellman group.
150 */
151 struct diffie_hellman_params_t {
152
153 /**
154 * The prime of the group
155 */
156 const chunk_t prime;
157
158 /**
159 * Generator of the group
160 */
161 const chunk_t generator;
162
163 /**
164 * Exponent length to use
165 */
166 size_t exp_len;
167
168 /**
169 * Prime order subgroup; for MODP Groups 22-24
170 */
171 const chunk_t subgroup;
172 };
173
174 /**
175 * Initialize diffie hellman parameters during startup.
176 */
177 void diffie_hellman_init();
178
179 /**
180 * Get the parameters associated with the specified diffie hellman group.
181 *
182 * Before calling this method, use diffie_hellman_init() to initialize the
183 * DH group table. This is usually done by library_init().
184 *
185 * @param group DH group
186 * @return The parameters or NULL, if the group is not supported
187 */
188 diffie_hellman_params_t *diffie_hellman_get_params(diffie_hellman_group_t group);
189
190 /**
191 * Check if a given DH group is an ECDH group
192 *
193 * @param group group to check
194 * @return TRUE if group is an ECP group
195 */
196 bool diffie_hellman_group_is_ec(diffie_hellman_group_t group);
197
198 /**
199 * Check if a diffie hellman public value is valid for given group.
200 *
201 * @param group group the value is used in
202 * @param value public DH value to check
203 * @return TRUE if value looks valid for group
204 */
205 bool diffie_hellman_verify_value(diffie_hellman_group_t group, chunk_t value);
206
207 #endif /** DIFFIE_HELLMAN_H_ @}*/