]>
Commit | Line | Data |
---|---|---|
99400f97 | 1 | /* |
5af7be07 | 2 | * Copyright (C) 2010-2020 Tobias Brunner |
c96aefe2 | 3 | * Copyright (C) 2005-2007 Martin Willi |
c71d53ba | 4 | * Copyright (C) 2005 Jan Hutter |
19ef2aec TB |
5 | * |
6 | * Copyright (C) secunet Security Networks AG | |
99400f97 JH |
7 | * |
8 | * This program is free software; you can redistribute it and/or modify it | |
9 | * under the terms of the GNU General Public License as published by the | |
10 | * Free Software Foundation; either version 2 of the License, or (at your | |
11 | * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. | |
12 | * | |
13 | * This program is distributed in the hope that it will be useful, but | |
14 | * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY | |
15 | * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
16 | * for more details. | |
552cc11b | 17 | */ |
7daf5226 | 18 | |
552cc11b | 19 | /** |
3af7c6db | 20 | * @defgroup key_exchange key_exchange |
552cc11b | 21 | * @{ @ingroup crypto |
99400f97 JH |
22 | */ |
23 | ||
3af7c6db TB |
24 | #ifndef KEY_EXCHANGE_H_ |
25 | #define KEY_EXCHANGE_H_ | |
99400f97 | 26 | |
3af7c6db TB |
27 | typedef enum key_exchange_method_t key_exchange_method_t; |
28 | typedef struct key_exchange_t key_exchange_t; | |
908d5717 | 29 | typedef struct diffie_hellman_params_t diffie_hellman_params_t; |
8277be60 | 30 | |
db7ef624 | 31 | #include <library.h> |
5af7be07 | 32 | #include <collections/array.h> |
382b4817 MW |
33 | |
34 | /** | |
3af7c6db | 35 | * Key exchange method. |
382b4817 | 36 | * |
8277be60 | 37 | * The modulus (or group) to use for a Diffie-Hellman calculation. |
8a491129 | 38 | * See IKEv2 RFC 3.3.2 and RFC 3526. |
7daf5226 | 39 | * |
346e9c57 | 40 | * ECP groups are defined in RFC 4753 and RFC 5114. |
cca37246 | 41 | * ECC Brainpool groups are defined in RFC 6954. |
a4195d38 | 42 | * Curve25519 and Curve448 groups are defined in RFC 8031. |
8277be60 | 43 | */ |
3af7c6db | 44 | enum key_exchange_method_t { |
b7c167f9 | 45 | KE_NONE = 0, |
0caf2b93 AS |
46 | MODP_768_BIT = 1, |
47 | MODP_1024_BIT = 2, | |
48 | MODP_1536_BIT = 5, | |
8277be60 MW |
49 | MODP_2048_BIT = 14, |
50 | MODP_3072_BIT = 15, | |
51 | MODP_4096_BIT = 16, | |
52 | MODP_6144_BIT = 17, | |
fc1a31d5 | 53 | MODP_8192_BIT = 18, |
0caf2b93 AS |
54 | ECP_256_BIT = 19, |
55 | ECP_384_BIT = 20, | |
56 | ECP_521_BIT = 21, | |
4590260b MW |
57 | MODP_1024_160 = 22, |
58 | MODP_2048_224 = 23, | |
59 | MODP_2048_256 = 24, | |
0caf2b93 AS |
60 | ECP_192_BIT = 25, |
61 | ECP_224_BIT = 26, | |
cca37246 AS |
62 | ECP_224_BP = 27, |
63 | ECP_256_BP = 28, | |
64 | ECP_384_BP = 29, | |
65 | ECP_512_BP = 30, | |
a4195d38 MW |
66 | CURVE_25519 = 31, |
67 | CURVE_448 = 32, | |
a20abb81 MW |
68 | /** insecure NULL diffie hellman group for testing, in PRIVATE USE */ |
69 | MODP_NULL = 1024, | |
10b82be6 | 70 | /** MODP group with custom generator/prime */ |
146ad86b AS |
71 | /** Parameters defined by IEEE 1363.1, in PRIVATE USE */ |
72 | NTRU_112_BIT = 1030, | |
73 | NTRU_128_BIT = 1031, | |
74 | NTRU_192_BIT = 1032, | |
e13ef5c4 | 75 | NTRU_256_BIT = 1033, |
393688ae | 76 | NH_128_BIT = 1040, |
e13ef5c4 TB |
77 | /** internally used DH group with additional parameters g and p, outside |
78 | * of PRIVATE USE (i.e. IKEv2 DH group range) so it can't be negotiated */ | |
79 | MODP_CUSTOM = 65536, | |
8277be60 MW |
80 | }; |
81 | ||
60356f33 | 82 | /** |
3af7c6db | 83 | * enum name for key_exchange_method_t. |
8277be60 | 84 | */ |
3af7c6db | 85 | extern enum_name_t *key_exchange_method_names; |
8277be60 | 86 | |
9514aa2d | 87 | /** |
3af7c6db | 88 | * enum names for key_exchange_method_t (matching proposal keywords). |
9514aa2d | 89 | */ |
3af7c6db | 90 | extern enum_name_t *key_exchange_method_names_short; |
9514aa2d | 91 | |
99400f97 | 92 | /** |
3af7c6db | 93 | * Implementation of a key exchange algorithms (e.g. Diffie-Hellman). |
99400f97 | 94 | */ |
3af7c6db | 95 | struct key_exchange_t { |
7daf5226 | 96 | |
99400f97 | 97 | /** |
3af7c6db | 98 | * Returns the shared secret of this key exchange method. |
7daf5226 | 99 | * |
3af7c6db | 100 | * @param secret shared secret (allocated) |
bace1d64 | 101 | * @return TRUE if shared secret computed successfully |
99400f97 | 102 | */ |
3af7c6db | 103 | bool (*get_shared_secret)(key_exchange_t *this, chunk_t *secret) |
bace1d64 | 104 | __attribute__((warn_unused_result)); |
7daf5226 | 105 | |
99400f97 | 106 | /** |
3af7c6db | 107 | * Sets the public key from the peer. |
7daf5226 | 108 | * |
0351b5af TB |
109 | * @note This operation should be relatively quick. Costly public key |
110 | * validation operations or key derivation should be implemented in | |
111 | * get_shared_secret(). | |
112 | * | |
3af7c6db TB |
113 | * @param value public key of peer |
114 | * @return TRUE if other public key verified and set | |
99400f97 | 115 | */ |
3af7c6db | 116 | bool (*set_public_key)(key_exchange_t *this, chunk_t value) |
a777155f | 117 | __attribute__((warn_unused_result)); |
7daf5226 | 118 | |
99400f97 | 119 | /** |
3af7c6db | 120 | * Gets the own public key to transmit. |
7daf5226 | 121 | * |
3af7c6db TB |
122 | * @param value public key (allocated) |
123 | * @return TRUE if public key retrieved | |
99400f97 | 124 | */ |
3af7c6db | 125 | bool (*get_public_key)(key_exchange_t *this, chunk_t *value) |
42431690 | 126 | __attribute__((warn_unused_result)); |
7daf5226 | 127 | |
3941545f | 128 | /** |
3af7c6db | 129 | * Set an explicit own private key to use. |
3941545f MW |
130 | * |
131 | * Calling this method is usually not required, as the DH backend generates | |
132 | * an appropriate private value itself. It is optional to implement, and | |
3af7c6db TB |
133 | * used mostly for testing purposes. The private key may be the actual key |
134 | * or a seed for a DRBG. | |
3941545f | 135 | * |
3af7c6db | 136 | * @param value private key value to set |
3941545f | 137 | */ |
3af7c6db | 138 | bool (*set_private_key)(key_exchange_t *this, chunk_t value) |
3941545f MW |
139 | __attribute__((warn_unused_result)); |
140 | ||
ce461bbd | 141 | /** |
3af7c6db | 142 | * Get the key exchange method used. |
7daf5226 | 143 | * |
3af7c6db | 144 | * @return key exchange method set in construction |
ce461bbd | 145 | */ |
3af7c6db | 146 | key_exchange_method_t (*get_method)(key_exchange_t *this); |
99400f97 JH |
147 | |
148 | /** | |
3af7c6db | 149 | * Destroys a key_exchange_t object. |
99400f97 | 150 | */ |
3af7c6db | 151 | void (*destroy)(key_exchange_t *this); |
99400f97 JH |
152 | }; |
153 | ||
908d5717 | 154 | /** |
3af7c6db | 155 | * Parameters for a specific Diffie-Hellman group. |
908d5717 TB |
156 | */ |
157 | struct diffie_hellman_params_t { | |
908d5717 TB |
158 | |
159 | /** | |
b34b93db | 160 | * The prime of the group |
908d5717 | 161 | */ |
b34b93db | 162 | const chunk_t prime; |
908d5717 TB |
163 | |
164 | /** | |
b34b93db | 165 | * Generator of the group |
908d5717 | 166 | */ |
b34b93db | 167 | const chunk_t generator; |
908d5717 TB |
168 | |
169 | /** | |
b34b93db | 170 | * Exponent length to use |
908d5717 TB |
171 | */ |
172 | size_t exp_len; | |
4590260b MW |
173 | |
174 | /** | |
175 | * Prime order subgroup; for MODP Groups 22-24 | |
176 | */ | |
177 | const chunk_t subgroup; | |
908d5717 TB |
178 | }; |
179 | ||
46184b07 MW |
180 | /** |
181 | * Initialize diffie hellman parameters during startup. | |
182 | */ | |
183 | void diffie_hellman_init(); | |
184 | ||
908d5717 | 185 | /** |
3af7c6db | 186 | * Get the parameters associated with the specified Diffie-Hellman group. |
908d5717 | 187 | * |
46184b07 MW |
188 | * Before calling this method, use diffie_hellman_init() to initialize the |
189 | * DH group table. This is usually done by library_init(). | |
190 | * | |
3af7c6db | 191 | * @param ke key exchange method (DH group) |
908d5717 TB |
192 | * @return The parameters or NULL, if the group is not supported |
193 | */ | |
3af7c6db | 194 | diffie_hellman_params_t *diffie_hellman_get_params(key_exchange_method_t ke); |
908d5717 | 195 | |
7d7711ab | 196 | /** |
3af7c6db | 197 | * Check if a given key exchange method is an ECDH group. |
7d7711ab | 198 | * |
3af7c6db TB |
199 | * @param ke key exchange method to check |
200 | * @return TRUE if key exchange method is an ECP group | |
7d7711ab | 201 | */ |
3af7c6db | 202 | bool key_exchange_is_ecdh(key_exchange_method_t ke); |
7d7711ab | 203 | |
0356089d | 204 | /** |
3af7c6db | 205 | * Check if a public key is valid for given key exchange method. |
0356089d | 206 | * |
3af7c6db TB |
207 | * @param ke key exchange method |
208 | * @param value public key to check | |
209 | * @return TRUE if value looks valid | |
0356089d | 210 | */ |
3af7c6db | 211 | bool key_exchange_verify_pubkey(key_exchange_method_t ke, chunk_t value); |
0356089d | 212 | |
5af7be07 TB |
213 | /** |
214 | * Return the first shared secret plus the concatenated additional shared | |
215 | * secrets of all the key exchange methods in the given array. | |
216 | * | |
217 | * @param kes array of key_exchange_t* | |
218 | * @param secret first shared secret (allocated) | |
219 | * @param add_secret concatenated additional shared secrets (allocated) | |
220 | * @return TRUE on success | |
221 | */ | |
222 | bool key_exchange_concat_secrets(array_t *kes, chunk_t *secret, | |
223 | chunk_t *add_secret); | |
224 | ||
3af7c6db | 225 | #endif /** KEY_EXCHANGE_H_ @}*/ |