Migrated simaka_message to INIT/METHOD macros
[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
28 typedef struct simaka_manager_t simaka_manager_t;
29
30 #define SIM_RAND_LEN 16
31 #define SIM_SRES_LEN 4
32 #define SIM_KC_LEN 8
33
34 #define AKA_RAND_LEN 16
35 #define AKA_RES_MAX 16
36 #define AKA_CK_LEN 16
37 #define AKA_IK_LEN 16
38 #define AKA_AUTN_LEN 16
39 #define AKA_AUTS_LEN 14
40
41 #include "simaka_card.h"
42 #include "simaka_provider.h"
43 #include "simaka_hooks.h"
44
45 /**
46 * The SIM manager handles multiple (U)SIM cards/providers and hooks.
47 */
48 struct simaka_manager_t {
49
50 /**
51 * Register a SIM card (client) at the manager.
52 *
53 * @param card sim card to register
54 */
55 void (*add_card)(simaka_manager_t *this, simaka_card_t *card);
56
57 /**
58 * Unregister a previously registered card from the manager.
59 *
60 * @param card sim card to unregister
61 */
62 void (*remove_card)(simaka_manager_t *this, simaka_card_t *card);
63
64 /**
65 * Calculate SIM triplets on one of the registered SIM cards.
66 *
67 * @param id permanent identity to get a triplet for
68 * @param rand RAND input buffer, fixed size 16 bytes
69 * @param sres SRES output buffer, fixed size 4 byte
70 * @param kc KC output buffer, fixed size 8 bytes
71 * @return TRUE if calculated, FALSE if no matching card found
72 */
73 bool (*card_get_triplet)(simaka_manager_t *this, identification_t *id,
74 char rand[SIM_RAND_LEN], char sres[SIM_SRES_LEN],
75 char kc[SIM_KC_LEN]);
76
77 /**
78 * Calculate AKA quitpulets on one of the registered SIM cards.
79 *
80 * @param id permanent identity to request quintuplet for
81 * @param rand random value rand
82 * @param autn authentication token autn
83 * @param ck buffer receiving encryption key ck
84 * @param ik buffer receiving integrity key ik
85 * @param res buffer receiving authentication result res
86 * @param res_len nubmer of bytes written to res buffer
87 * @return SUCCESS, FAILED, or INVALID_STATE if out of sync
88 */
89 status_t (*card_get_quintuplet)(simaka_manager_t *this, identification_t *id,
90 char rand[AKA_RAND_LEN], char autn[AKA_AUTN_LEN],
91 char ck[AKA_CK_LEN], char ik[AKA_IK_LEN],
92 char res[AKA_RES_MAX], int *res_len);
93
94 /**
95 * Calculate resynchronization data on one of the registered SIM cards.
96 *
97 * @param id permanent identity to request quintuplet for
98 * @param rand random value rand
99 * @param auts resynchronization parameter auts
100 * @return TRUE if calculated, FALSE if no matcing card found
101 */
102 bool (*card_resync)(simaka_manager_t *this, identification_t *id,
103 char rand[AKA_RAND_LEN], char auts[AKA_AUTS_LEN]);
104
105 /**
106 * Store a received pseudonym on one of the registered SIM cards.
107 *
108 * @param id permanent identity of the peer
109 * @param pseudonym pseudonym identity received from the server
110 */
111 void (*card_set_pseudonym)(simaka_manager_t *this, identification_t *id,
112 identification_t *pseudonym);
113
114 /**
115 * Get a stored pseudonym from one of the registerd SIM cards.
116 *
117 * @param id permanent identity of the peer
118 * @return associated pseudonym identity, NULL if none found
119 */
120 identification_t* (*card_get_pseudonym)(simaka_manager_t *this,
121 identification_t *id);
122
123 /**
124 * Store fast reauthentication parameters on one of the registered cards.
125 *
126 * @param id permanent identity of the peer
127 * @param next next fast reauthentication identity to use
128 * @param mk master key MK to store for reauthentication
129 * @param counter counter value to store, host order
130 */
131 void (*card_set_reauth)(simaka_manager_t *this, identification_t *id,
132 identification_t *next, char mk[HASH_SIZE_SHA1],
133 u_int16_t counter);
134
135 /**
136 * Retrieve fast reauthentication parameters from one of the registerd cards.
137 *
138 * @param id permanent identity of the peer
139 * @param mk buffer receiving master key MK
140 * @param counter pointer receiving counter value, in host order
141 * @return fast reauthentication identity, NULL if none found
142 */
143 identification_t* (*card_get_reauth)(simaka_manager_t *this,
144 identification_t *id, char mk[HASH_SIZE_SHA1],
145 u_int16_t *counter);
146
147 /**
148 * Register a triplet provider (server) at the manager.
149 *
150 * @param card sim card to register
151 */
152 void (*add_provider)(simaka_manager_t *this, simaka_provider_t *provider);
153
154 /**
155 * Unregister a previously registered provider from the manager.
156 *
157 * @param card sim card to unregister
158 */
159 void (*remove_provider)(simaka_manager_t *this, simaka_provider_t *provider);
160
161 /**
162 * Get a SIM triplet from one of the registered providers.
163 *
164 * @param id permanent identity of peer to gen triplet for
165 * @param rand RAND output buffer, fixed size 16 bytes
166 * @param sres SRES output buffer, fixed size 4 byte
167 * @param kc KC output buffer, fixed size 8 bytes
168 * @return TRUE if triplet received, FALSE if no match found
169 */
170 bool (*provider_get_triplet)(simaka_manager_t *this, identification_t *id,
171 char rand[SIM_RAND_LEN], char sres[SIM_SRES_LEN],
172 char kc[SIM_KC_LEN]);
173
174 /**
175 * Get a AKA quintuplet from one of the registered providers.
176 *
177 * @param id permanent identity of peer to create challenge for
178 * @param rand buffer receiving random value rand
179 * @param xres buffer receiving expected authentication result xres
180 * @param ck buffer receiving encryption key ck
181 * @param ik buffer receiving integrity key ik
182 * @param autn authentication token autn
183 * @return TRUE if quintuplet received, FALSE if no match found
184 */
185 bool (*provider_get_quintuplet)(simaka_manager_t *this, identification_t *id,
186 char rand[AKA_RAND_LEN],
187 char xres[AKA_RES_MAX], int *xres_len,
188 char ck[AKA_CK_LEN], char ik[AKA_IK_LEN],
189 char autn[AKA_AUTN_LEN]);
190
191 /**
192 * Pass AKA resynchronization data to one of the registered providers.
193 *
194 * @param id permanent identity of peer requesting resynchronisation
195 * @param rand random value rand
196 * @param auts synchronization parameter auts
197 * @return TRUE if resynchronized, FALSE if not handled
198 */
199 bool (*provider_resync)(simaka_manager_t *this, identification_t *id,
200 char rand[AKA_RAND_LEN], char auts[AKA_AUTS_LEN]);
201
202 /**
203 * Check if a peer uses a pseudonym using one of the registered providers.
204 *
205 * @param id pseudonym identity candidate
206 * @return permanent identity, NULL if id not a pseudonym
207 */
208 identification_t* (*provider_is_pseudonym)(simaka_manager_t *this,
209 identification_t *id);
210
211 /**
212 * Generate a new pseudonym using one of the registered providers.
213 *
214 * @param id permanent identity to generate a pseudonym for
215 * @return generated pseudonym, NULL to not use a pseudonym identity
216 */
217 identification_t* (*provider_gen_pseudonym)(simaka_manager_t *this,
218 identification_t *id);
219
220 /**
221 * Check if a peer uses a reauth id using one of the registered providers.
222 *
223 * @param id reauthentication identity (candidate)
224 * @param mk buffer receiving master key MK
225 * @param counter pointer receiving current counter value, host order
226 * @return permanent identity, NULL if not a known reauth identity
227 */
228 identification_t* (*provider_is_reauth)(simaka_manager_t *this,
229 identification_t *id, char mk[HASH_SIZE_SHA1],
230 u_int16_t *counter);
231
232 /**
233 * Generate a fast reauth id using one of the registered providers.
234 *
235 * @param id permanent peer identity
236 * @param mk master key to store along with generated identity
237 * @return fast reauthentication identity, NULL to not use reauth
238 */
239 identification_t* (*provider_gen_reauth)(simaka_manager_t *this,
240 identification_t *id, char mk[HASH_SIZE_SHA1]);
241
242 /**
243 * Register a set of hooks to the manager.
244 *
245 * @param hooks hook interface implementation to register
246 */
247 void (*add_hooks)(simaka_manager_t *this, simaka_hooks_t *hooks);
248
249 /**
250 * Unregister a set of hooks from the manager.
251 *
252 * @param hooks hook interface implementation to unregister
253 */
254 void (*remove_hooks)(simaka_manager_t *this, simaka_hooks_t *hooks);
255
256 /**
257 * Invoke SIM/AKA message hook.
258 *
259 * @param message SIM message
260 * @param inbound TRUE for incoming messages, FALSE for outgoing
261 * @param decrypted TRUE if AT_ENCR_DATA has been decrypted
262 */
263 void (*message_hook)(simaka_manager_t *this, simaka_message_t *message,
264 bool inbound, bool decrypted);
265
266 /**
267 * Invoke SIM/AKA key hook.
268 *
269 * @param k_encr SIM/AKA encryption key k_encr
270 * @param k_auth SIM/AKA authentication key k_auth
271 */
272 void (*key_hook)(simaka_manager_t *this, chunk_t k_encr, chunk_t k_auth);
273
274 /**
275 * Destroy a manager instance.
276 */
277 void (*destroy)(simaka_manager_t *this);
278 };
279
280 /**
281 * Create an SIM/AKA manager to handle multiple (U)SIM cards/providers.
282 *
283 * @return simaka_t object
284 */
285 simaka_manager_t *simaka_manager_create();
286
287 #endif /** SIMAKA_MANAGER_H_ @}*/