sim_card_t API gained support for pseudonym/fast reauthentication
[strongswan.git] / src / charon / sa / authenticators / eap / sim_manager.h
1 /*
2 * Copyright (C) 2008-2009 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 sim_manager sim_manager
18 * @{ @ingroup eap
19 */
20
21 #ifndef SIM_MANAGER_H_
22 #define SIM_MANAGER_H_
23
24 #include <utils/identification.h>
25 #include <utils/enumerator.h>
26
27 typedef struct sim_manager_t sim_manager_t;
28 typedef struct sim_card_t sim_card_t;
29 typedef struct sim_provider_t sim_provider_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_LEN 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 /**
43 * Interface for a (U)SIM card (used as EAP client).
44 *
45 * The SIM card completes triplets/quintuplets requested in a challenge
46 * received from the server.
47 * An implementation supporting only one of SIM/AKA authentication may
48 * implement the other methods with return_false()/return NOT_SUPPORTED.
49 */
50 struct sim_card_t {
51
52 /**
53 * Calculate SRES/KC from a RAND for SIM authentication.
54 *
55 * @param imsi identity to get a triplet for
56 * @param rand RAND input buffer, fixed size 16 bytes
57 * @param sres SRES output buffer, fixed size 4 byte
58 * @param kc KC output buffer, fixed size 8 bytes
59 * @return TRUE if SRES/KC calculated, FALSE on error/wrong identity
60 */
61 bool (*get_triplet)(sim_card_t *this, identification_t *imsi,
62 char rand[SIM_RAND_LEN], char sres[SIM_SRES_LEN],
63 char kc[SIM_KC_LEN]);
64
65 /**
66 * Calculate CK/IK/RES from RAND/AUTN for AKA authentication.
67 *
68 * If the received sequence number (in autn) is out of sync, INVALID_STATE
69 * is returned.
70 *
71 * @param imsi peer identity requesting quintuplet for
72 * @param rand random value rand
73 * @param autn authentication token autn
74 * @param ck buffer receiving encryption key ck
75 * @param ik buffer receiving integrity key ik
76 * @param res buffer receiving authentication result res
77 * @return SUCCESS, FAILED, or INVALID_STATE if out of sync
78 */
79 status_t (*get_quintuplet)(sim_card_t *this, identification_t *imsi,
80 char rand[AKA_RAND_LEN], char autn[AKA_AUTN_LEN],
81 char ck[AKA_CK_LEN], char ik[AKA_IK_LEN],
82 char res[AKA_RES_LEN]);
83
84 /**
85 * Calculate AUTS from RAND for AKA resynchronization.
86 *
87 * @param imsi peer identity requesting quintuplet for
88 * @param rand random value rand
89 * @param auts resynchronization parameter auts
90 * @return TRUE if parameter generated successfully
91 */
92 bool (*resync)(sim_card_t *this, identification_t *imsi,
93 char rand[AKA_RAND_LEN], char auts[AKA_AUTS_LEN]);
94
95 /**
96 * Set the pseudonym to use for next authentication.
97 *
98 * @param perm permanent identity of the peer (imsi)
99 * @param pseudo pseudonym identity received from the server
100 */
101 void (*set_pseudonym)(sim_card_t *this, identification_t *perm,
102 identification_t *pseudo);
103
104 /**
105 * Get the pseudonym previously stored via set_pseudonym().
106 *
107 * @param perm permanent identity of the peer (imsi)
108 * @return associated pseudonym identity, NULL if none stored
109 */
110 identification_t* (*get_pseudonym)(sim_card_t *this, identification_t *perm);
111
112 /**
113 * Store parameters to use for the next fast reauthentication.
114 *
115 * @param perm permanent identity of the peer (imsi)
116 * @param next next fast reauthentication identity to use
117 * @param mk master key MK to store for reauthentication
118 * @param counter counter value to store, host order
119 */
120 void (*set_reauth)(sim_card_t *this, identification_t *perm,
121 identification_t *next, char mk[HASH_SIZE_SHA1],
122 u_int16_t counter);
123
124 /**
125 * Retrieve parameters for fast reauthentication stored via set_reauth().
126 *
127 * @param perm permanent identity of the peer (imsi)
128 * @param mk buffer receiving master key MK
129 * @param counter pointer receiving counter value, in host order
130 */
131 identification_t* (*get_reauth)(sim_card_t *this, identification_t *perm,
132 char mk[HASH_SIZE_SHA1], u_int16_t *counter);
133 };
134
135 /**
136 * Interface for a triplet/quintuplet provider (used as EAP server).
137 *
138 * A SIM provider hands out triplets for SIM authentication and quintuplets
139 * for AKA authentication. Multiple SIM provider instances can serve as
140 * authentication backend to authenticate clients using SIM/AKA.
141 * An implementation supporting only one of SIM/AKA authentication may
142 * implement the other methods with return_false().
143 */
144 struct sim_provider_t {
145
146 /**
147 * Create a challenge for SIM authentication.
148 *
149 * @param imsi client identity
150 * @param rand RAND output buffer, fixed size 16 bytes
151 * @param sres SRES output buffer, fixed size 4 byte
152 * @param kc KC output buffer, fixed size 8 bytes
153 * @return TRUE if triplet received, FALSE otherwise
154 */
155 bool (*get_triplet)(sim_provider_t *this, identification_t *imsi,
156 char rand[SIM_RAND_LEN], char sres[SIM_SRES_LEN],
157 char kc[SIM_KC_LEN]);
158
159 /**
160 * Create a challenge for AKA authentication.
161 *
162 * @param imsi peer identity to create challenge for
163 * @param rand buffer receiving random value rand
164 * @param xres buffer receiving expected authentication result xres
165 * @param ck buffer receiving encryption key ck
166 * @param ik buffer receiving integrity key ik
167 * @param autn authentication token autn
168 * @return TRUE if quintuplet generated successfully
169 */
170 bool (*get_quintuplet)(sim_provider_t *this, identification_t *imsi,
171 char rand[AKA_RAND_LEN], char xres[AKA_RES_LEN],
172 char ck[AKA_CK_LEN], char ik[AKA_IK_LEN],
173 char autn[AKA_AUTN_LEN]);
174
175 /**
176 * Process AKA resynchroniusation request of a peer.
177 *
178 * @param imsi peer identity requesting resynchronisation
179 * @param rand random value rand
180 * @param auts synchronization parameter auts
181 * @return TRUE if resynchronized successfully
182 */
183 bool (*resync)(sim_provider_t *this, identification_t *imsi,
184 char rand[AKA_RAND_LEN], char auts[AKA_AUTS_LEN]);
185 };
186
187 /**
188 * The SIM manager handles multiple (U)SIM cards and providers.
189 */
190 struct sim_manager_t {
191
192 /**
193 * Register a SIM card (client) at the manager.
194 *
195 * @param card sim card to register
196 */
197 void (*add_card)(sim_manager_t *this, sim_card_t *card);
198
199 /**
200 * Unregister a previously registered card from the manager.
201 *
202 * @param card sim card to unregister
203 */
204 void (*remove_card)(sim_manager_t *this, sim_card_t *card);
205
206 /**
207 * Create an enumerator over all registered cards.
208 *
209 * @return enumerator over sim_card_t's
210 */
211 enumerator_t* (*create_card_enumerator)(sim_manager_t *this);
212
213 /**
214 * Register a triplet provider (server) at the manager.
215 *
216 * @param card sim card to register
217 */
218 void (*add_provider)(sim_manager_t *this, sim_provider_t *provider);
219
220 /**
221 * Unregister a previously registered provider from the manager.
222 *
223 * @param card sim card to unregister
224 */
225 void (*remove_provider)(sim_manager_t *this, sim_provider_t *provider);
226
227 /**
228 * Create an enumerator over all registered provider.
229 *
230 * @return enumerator over sim_provider_t's
231 */
232 enumerator_t* (*create_provider_enumerator)(sim_manager_t *this);
233
234 /**
235 * Destroy a manager instance.
236 */
237 void (*destroy)(sim_manager_t *this);
238 };
239
240 /**
241 * Create an SIM manager to handle multiple (U)SIM cards/providers.
242 *
243 * @return sim_t object
244 */
245 sim_manager_t *sim_manager_create();
246
247 #endif /** SIM_MANAGER_H_ @}*/