Add a return value to simaka_message_t.generate()
[strongswan.git] / src / libsimaka / simaka_manager.h
1 /*
2 * Copyright (C) 2008-2011 Martin Willi
3 * Hochschule fuer Technik Rapperswil
4 *
5 * This program is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License as published by the
7 * Free Software Foundation; either version 2 of the License, or (at your
8 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
9 *
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * for more details.
14 */
15
16 /**
17 * @defgroup simaka_manager simaka_manager
18 * @{ @ingroup libsimaka
19 */
20
21 #ifndef SIMAKA_MANAGER_H_
22 #define SIMAKA_MANAGER_H_
23
24 #include <crypto/hashers/hasher.h>
25 #include <utils/identification.h>
26 #include <utils/enumerator.h>
27 #include <plugins/plugin.h>
28
29 typedef struct simaka_manager_t simaka_manager_t;
30
31 #define SIM_RAND_LEN 16
32 #define SIM_SRES_LEN 4
33 #define SIM_KC_LEN 8
34
35 #define AKA_RAND_LEN 16
36 #define AKA_RES_MAX 16
37 #define AKA_CK_LEN 16
38 #define AKA_IK_LEN 16
39 #define AKA_AUTN_LEN 16
40 #define AKA_AUTS_LEN 14
41
42 #include "simaka_card.h"
43 #include "simaka_provider.h"
44 #include "simaka_hooks.h"
45
46 /**
47 * The SIM manager handles multiple (U)SIM cards/providers and hooks.
48 */
49 struct simaka_manager_t {
50
51 /**
52 * Register a SIM card (client) at the manager.
53 *
54 * @param card sim card to register
55 */
56 void (*add_card)(simaka_manager_t *this, simaka_card_t *card);
57
58 /**
59 * Unregister a previously registered card from the manager.
60 *
61 * @param card sim card to unregister
62 */
63 void (*remove_card)(simaka_manager_t *this, simaka_card_t *card);
64
65 /**
66 * Calculate SIM triplets on one of the registered SIM cards.
67 *
68 * @param id permanent identity to get a triplet for
69 * @param rand RAND input buffer, fixed size 16 bytes
70 * @param sres SRES output buffer, fixed size 4 byte
71 * @param kc KC output buffer, fixed size 8 bytes
72 * @return TRUE if calculated, FALSE if no matching card found
73 */
74 bool (*card_get_triplet)(simaka_manager_t *this, identification_t *id,
75 char rand[SIM_RAND_LEN], char sres[SIM_SRES_LEN],
76 char kc[SIM_KC_LEN]);
77
78 /**
79 * Calculate AKA quitpulets on one of the registered SIM cards.
80 *
81 * @param id permanent identity to request quintuplet for
82 * @param rand random value rand
83 * @param autn authentication token autn
84 * @param ck buffer receiving encryption key ck
85 * @param ik buffer receiving integrity key ik
86 * @param res buffer receiving authentication result res
87 * @param res_len nubmer of bytes written to res buffer
88 * @return SUCCESS, FAILED, or INVALID_STATE if out of sync
89 */
90 status_t (*card_get_quintuplet)(simaka_manager_t *this, identification_t *id,
91 char rand[AKA_RAND_LEN], char autn[AKA_AUTN_LEN],
92 char ck[AKA_CK_LEN], char ik[AKA_IK_LEN],
93 char res[AKA_RES_MAX], int *res_len);
94
95 /**
96 * Calculate resynchronization data on one of the registered SIM cards.
97 *
98 * @param id permanent identity to request quintuplet for
99 * @param rand random value rand
100 * @param auts resynchronization parameter auts
101 * @return TRUE if calculated, FALSE if no matcing card found
102 */
103 bool (*card_resync)(simaka_manager_t *this, identification_t *id,
104 char rand[AKA_RAND_LEN], char auts[AKA_AUTS_LEN]);
105
106 /**
107 * Store a received pseudonym on one of the registered SIM cards.
108 *
109 * @param id permanent identity of the peer
110 * @param pseudonym pseudonym identity received from the server
111 */
112 void (*card_set_pseudonym)(simaka_manager_t *this, identification_t *id,
113 identification_t *pseudonym);
114
115 /**
116 * Get a stored pseudonym from one of the registered SIM cards.
117 *
118 * @param id permanent identity of the peer
119 * @return associated pseudonym identity, NULL if none found
120 */
121 identification_t* (*card_get_pseudonym)(simaka_manager_t *this,
122 identification_t *id);
123
124 /**
125 * Store fast reauthentication parameters on one of the registered cards.
126 *
127 * @param id permanent identity of the peer
128 * @param next next fast reauthentication identity to use
129 * @param mk master key MK to store for reauthentication
130 * @param counter counter value to store, host order
131 */
132 void (*card_set_reauth)(simaka_manager_t *this, identification_t *id,
133 identification_t *next, char mk[HASH_SIZE_SHA1],
134 u_int16_t counter);
135
136 /**
137 * Retrieve fast reauthentication parameters from one of the registered cards.
138 *
139 * @param id permanent identity of the peer
140 * @param mk buffer receiving master key MK
141 * @param counter pointer receiving counter value, in host order
142 * @return fast reauthentication identity, NULL if none found
143 */
144 identification_t* (*card_get_reauth)(simaka_manager_t *this,
145 identification_t *id, char mk[HASH_SIZE_SHA1],
146 u_int16_t *counter);
147
148 /**
149 * Register a triplet provider (server) at the manager.
150 *
151 * @param card sim card to register
152 */
153 void (*add_provider)(simaka_manager_t *this, simaka_provider_t *provider);
154
155 /**
156 * Unregister a previously registered provider from the manager.
157 *
158 * @param card sim card to unregister
159 */
160 void (*remove_provider)(simaka_manager_t *this, simaka_provider_t *provider);
161
162 /**
163 * Get a SIM triplet from one of the registered providers.
164 *
165 * @param id permanent identity of peer to gen triplet for
166 * @param rand RAND output buffer, fixed size 16 bytes
167 * @param sres SRES output buffer, fixed size 4 byte
168 * @param kc KC output buffer, fixed size 8 bytes
169 * @return TRUE if triplet received, FALSE if no match found
170 */
171 bool (*provider_get_triplet)(simaka_manager_t *this, identification_t *id,
172 char rand[SIM_RAND_LEN], char sres[SIM_SRES_LEN],
173 char kc[SIM_KC_LEN]);
174
175 /**
176 * Get a AKA quintuplet from one of the registered providers.
177 *
178 * @param id permanent identity of peer to create challenge for
179 * @param rand buffer receiving random value rand
180 * @param xres buffer receiving expected authentication result xres
181 * @param ck buffer receiving encryption key ck
182 * @param ik buffer receiving integrity key ik
183 * @param autn authentication token autn
184 * @return TRUE if quintuplet received, FALSE if no match found
185 */
186 bool (*provider_get_quintuplet)(simaka_manager_t *this, identification_t *id,
187 char rand[AKA_RAND_LEN],
188 char xres[AKA_RES_MAX], int *xres_len,
189 char ck[AKA_CK_LEN], char ik[AKA_IK_LEN],
190 char autn[AKA_AUTN_LEN]);
191
192 /**
193 * Pass AKA resynchronization data to one of the registered providers.
194 *
195 * @param id permanent identity of peer requesting resynchronisation
196 * @param rand random value rand
197 * @param auts synchronization parameter auts
198 * @return TRUE if resynchronized, FALSE if not handled
199 */
200 bool (*provider_resync)(simaka_manager_t *this, identification_t *id,
201 char rand[AKA_RAND_LEN], char auts[AKA_AUTS_LEN]);
202
203 /**
204 * Check if a peer uses a pseudonym using one of the registered providers.
205 *
206 * @param id pseudonym identity candidate
207 * @return permanent identity, NULL if id not a pseudonym
208 */
209 identification_t* (*provider_is_pseudonym)(simaka_manager_t *this,
210 identification_t *id);
211
212 /**
213 * Generate a new pseudonym using one of the registered providers.
214 *
215 * @param id permanent identity to generate a pseudonym for
216 * @return generated pseudonym, NULL to not use a pseudonym identity
217 */
218 identification_t* (*provider_gen_pseudonym)(simaka_manager_t *this,
219 identification_t *id);
220
221 /**
222 * Check if a peer uses a reauth id using one of the registered providers.
223 *
224 * @param id reauthentication identity (candidate)
225 * @param mk buffer receiving master key MK
226 * @param counter pointer receiving current counter value, host order
227 * @return permanent identity, NULL if not a known reauth identity
228 */
229 identification_t* (*provider_is_reauth)(simaka_manager_t *this,
230 identification_t *id, char mk[HASH_SIZE_SHA1],
231 u_int16_t *counter);
232
233 /**
234 * Generate a fast reauth id using one of the registered providers.
235 *
236 * @param id permanent peer identity
237 * @param mk master key to store along with generated identity
238 * @return fast reauthentication identity, NULL to not use reauth
239 */
240 identification_t* (*provider_gen_reauth)(simaka_manager_t *this,
241 identification_t *id, char mk[HASH_SIZE_SHA1]);
242
243 /**
244 * Register a set of hooks to the manager.
245 *
246 * @param hooks hook interface implementation to register
247 */
248 void (*add_hooks)(simaka_manager_t *this, simaka_hooks_t *hooks);
249
250 /**
251 * Unregister a set of hooks from the manager.
252 *
253 * @param hooks hook interface implementation to unregister
254 */
255 void (*remove_hooks)(simaka_manager_t *this, simaka_hooks_t *hooks);
256
257 /**
258 * Invoke SIM/AKA message hook.
259 *
260 * @param message SIM message
261 * @param inbound TRUE for incoming messages, FALSE for outgoing
262 * @param decrypted TRUE if AT_ENCR_DATA has been decrypted
263 */
264 void (*message_hook)(simaka_manager_t *this, simaka_message_t *message,
265 bool inbound, bool decrypted);
266
267 /**
268 * Invoke SIM/AKA key hook.
269 *
270 * @param k_encr SIM/AKA encryption key k_encr
271 * @param k_auth SIM/AKA authentication key k_auth
272 */
273 void (*key_hook)(simaka_manager_t *this, chunk_t k_encr, chunk_t k_auth);
274
275 /**
276 * Destroy a manager instance.
277 */
278 void (*destroy)(simaka_manager_t *this);
279 };
280
281 /**
282 * Dummy libsimaka initialization function needed for integrity test
283 */
284 void libsimaka_init(void);
285
286 /**
287 * Create an SIM/AKA manager to handle multiple (U)SIM cards/providers.
288 *
289 * @return simaka_t object
290 */
291 simaka_manager_t *simaka_manager_create();
292
293 /**
294 * Callback for the simaka_manager_register_cb_t, provides backend to register.
295 *
296 * @param plugin plugin registering a backend (card or provider)
297 * @return a simaka_card_t* or simaka_provider_t*, NULL on failure
298 */
299 typedef void* (*simaka_manager_register_cb_t)(plugin_t *plugin);
300
301 /**
302 * Helper function to (un-)register SIM/AKA backend plugin features.
303 *
304 * This function is a plugin_feature_callback_t and can be used with the
305 * PLUGIN_CALLBACK macro to register a SIM/AKA backend.
306 *
307 * @param plugin plugin registering the SIM/AKA backend
308 * @param feature associated plugin feature
309 * @param reg TRUE to register, FALSE to unregister.
310 * @param data data passed to callback, an simaka_manager_register_cb_t
311 */
312 bool simaka_manager_register(plugin_t *plugin, plugin_feature_t *feature,
313 bool reg, void *data);
314
315 #endif /** SIMAKA_MANAGER_H_ @}*/