1: /*
2: * Copyright (C) 2008-2011 Martin Willi
3: * HSR 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 <collections/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 quintuplets 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 number 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 matching 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: uint16_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: uint16_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 resynchronization
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: uint16_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: * Create an SIM/AKA manager to handle multiple (U)SIM cards/providers.
283: *
284: * @return simaka_t object
285: */
286: simaka_manager_t *simaka_manager_create();
287:
288: /**
289: * Callback for the simaka_manager_register_cb_t, provides backend to register.
290: *
291: * @param plugin plugin registering a backend (card or provider)
292: * @return a simaka_card_t* or simaka_provider_t*, NULL on failure
293: */
294: typedef void* (*simaka_manager_register_cb_t)(plugin_t *plugin);
295:
296: /**
297: * Helper function to (un-)register SIM/AKA backend plugin features.
298: *
299: * This function is a plugin_feature_callback_t and can be used with the
300: * PLUGIN_CALLBACK macro to register a SIM/AKA backend.
301: *
302: * @param plugin plugin registering the SIM/AKA backend
303: * @param feature associated plugin feature
304: * @param reg TRUE to register, FALSE to unregister.
305: * @param data data passed to callback, an simaka_manager_register_cb_t
306: */
307: bool simaka_manager_register(plugin_t *plugin, plugin_feature_t *feature,
308: bool reg, void *data);
309:
310: /**
311: * @}
312: * @addtogroup libsimaka
313: * @{
314: *
315: * Dummy libsimaka initialization function needed for integrity test
316: */
317: void libsimaka_init(void);
318:
319: #endif /** SIMAKA_MANAGER_H_ @}*/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>