d8d747afdae713af1adff79bddc516af95cda95f
[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 /**
97 * Interface for a triplet/quintuplet provider (used as EAP server).
98 *
99 * A SIM provider hands out triplets for SIM authentication and quintuplets
100 * for AKA authentication. Multiple SIM provider instances can serve as
101 * authentication backend to authenticate clients using SIM/AKA.
102 * An implementation supporting only one of SIM/AKA authentication may
103 * implement the other methods with return_false().
104 */
105 struct sim_provider_t {
106
107 /**
108 * Create a challenge for SIM authentication.
109 *
110 * @param imsi client identity
111 * @param rand RAND output buffer, fixed size 16 bytes
112 * @param sres SRES output buffer, fixed size 4 byte
113 * @param kc KC output buffer, fixed size 8 bytes
114 * @return TRUE if triplet received, FALSE otherwise
115 */
116 bool (*get_triplet)(sim_provider_t *this, identification_t *imsi,
117 char rand[SIM_RAND_LEN], char sres[SIM_SRES_LEN],
118 char kc[SIM_KC_LEN]);
119
120 /**
121 * Create a challenge for AKA authentication.
122 *
123 * @param imsi peer identity to create challenge for
124 * @param rand buffer receiving random value rand
125 * @param xres buffer receiving expected authentication result xres
126 * @param ck buffer receiving encryption key ck
127 * @param ik buffer receiving integrity key ik
128 * @param autn authentication token autn
129 * @return TRUE if quintuplet generated successfully
130 */
131 bool (*get_quintuplet)(sim_provider_t *this, identification_t *imsi,
132 char rand[AKA_RAND_LEN], char xres[AKA_RES_LEN],
133 char ck[AKA_CK_LEN], char ik[AKA_IK_LEN],
134 char autn[AKA_AUTN_LEN]);
135
136 /**
137 * Process AKA resynchroniusation request of a peer.
138 *
139 * @param imsi peer identity requesting resynchronisation
140 * @param rand random value rand
141 * @param auts synchronization parameter auts
142 * @return TRUE if resynchronized successfully
143 */
144 bool (*resync)(sim_provider_t *this, identification_t *imsi,
145 char rand[AKA_RAND_LEN], char auts[AKA_AUTS_LEN]);
146 };
147
148 /**
149 * The SIM manager handles multiple (U)SIM cards and providers.
150 */
151 struct sim_manager_t {
152
153 /**
154 * Register a SIM card (client) at the manager.
155 *
156 * @param card sim card to register
157 */
158 void (*add_card)(sim_manager_t *this, sim_card_t *card);
159
160 /**
161 * Unregister a previously registered card from the manager.
162 *
163 * @param card sim card to unregister
164 */
165 void (*remove_card)(sim_manager_t *this, sim_card_t *card);
166
167 /**
168 * Create an enumerator over all registered cards.
169 *
170 * @return enumerator over sim_card_t's
171 */
172 enumerator_t* (*create_card_enumerator)(sim_manager_t *this);
173
174 /**
175 * Register a triplet provider (server) at the manager.
176 *
177 * @param card sim card to register
178 */
179 void (*add_provider)(sim_manager_t *this, sim_provider_t *provider);
180
181 /**
182 * Unregister a previously registered provider from the manager.
183 *
184 * @param card sim card to unregister
185 */
186 void (*remove_provider)(sim_manager_t *this, sim_provider_t *provider);
187
188 /**
189 * Create an enumerator over all registered provider.
190 *
191 * @return enumerator over sim_provider_t's
192 */
193 enumerator_t* (*create_provider_enumerator)(sim_manager_t *this);
194
195 /**
196 * Destroy a manager instance.
197 */
198 void (*destroy)(sim_manager_t *this);
199 };
200
201 /**
202 * Create an SIM manager to handle multiple (U)SIM cards/providers.
203 *
204 * @return sim_t object
205 */
206 sim_manager_t *sim_manager_create();
207
208 #endif /** SIM_MANAGER_H_ @}*/