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