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_card simaka_card
18: * @{ @ingroup libsimaka
19: */
20:
21: #ifndef SIMAKA_CARD_H_
22: #define SIMAKA_CARD_H_
23:
24: typedef struct simaka_card_t simaka_card_t;
25:
26: #include "simaka_manager.h"
27:
28: #include <utils/identification.h>
29:
30: /**
31: * Interface for a (U)SIM card (used as EAP client).
32: *
33: * The SIM card completes triplets/quintuplets requested in a challenge
34: * received from the server.
35: * An implementation supporting only one of SIM/AKA authentication may
36: * implement the other methods with return_false()/return NOT_SUPPORTED/NULL.
37: */
38: struct simaka_card_t {
39:
40: /**
41: * Calculate SRES/KC from a RAND for SIM authentication.
42: *
43: * @param id permanent identity to get a triplet for
44: * @param rand RAND input buffer, fixed size 16 bytes
45: * @param sres SRES output buffer, fixed size 4 byte
46: * @param kc KC output buffer, fixed size 8 bytes
47: * @return TRUE if SRES/KC calculated, FALSE on error/wrong identity
48: */
49: bool (*get_triplet)(simaka_card_t *this, identification_t *id,
50: char rand[SIM_RAND_LEN], char sres[SIM_SRES_LEN],
51: char kc[SIM_KC_LEN]);
52:
53: /**
54: * Calculate CK/IK/RES from RAND/AUTN for AKA authentication.
55: *
56: * If the received sequence number (in autn) is out of sync, INVALID_STATE
57: * is returned.
58: * The RES value is the only one with variable length. Pass a buffer
59: * of at least AKA_RES_MAX, the actual number of bytes is written to the
60: * res_len value. While the standard would allow any bit length between
61: * 32 and 128 bits, we support only full bytes for now.
62: *
63: * @param id permanent identity to request quintuplet for
64: * @param rand random value rand
65: * @param autn authentication token autn
66: * @param ck buffer receiving encryption key ck
67: * @param ik buffer receiving integrity key ik
68: * @param res buffer receiving authentication result res
69: * @param res_len number of bytes written to res buffer
70: * @return SUCCESS, FAILED, or INVALID_STATE if out of sync
71: */
72: status_t (*get_quintuplet)(simaka_card_t *this, identification_t *id,
73: char rand[AKA_RAND_LEN], char autn[AKA_AUTN_LEN],
74: char ck[AKA_CK_LEN], char ik[AKA_IK_LEN],
75: char res[AKA_RES_MAX], int *res_len);
76:
77: /**
78: * Calculate AUTS from RAND for AKA resynchronization.
79: *
80: * @param id permanent identity to request quintuplet for
81: * @param rand random value rand
82: * @param auts resynchronization parameter auts
83: * @return TRUE if parameter generated successfully
84: */
85: bool (*resync)(simaka_card_t *this, identification_t *id,
86: char rand[AKA_RAND_LEN], char auts[AKA_AUTS_LEN]);
87:
88: /**
89: * Set the pseudonym to use for next authentication.
90: *
91: * @param id permanent identity of the peer
92: * @param pseudonym pseudonym identity received from the server
93: */
94: void (*set_pseudonym)(simaka_card_t *this, identification_t *id,
95: identification_t *pseudonym);
96:
97: /**
98: * Get the pseudonym previously stored via set_pseudonym().
99: *
100: * @param id permanent identity of the peer
101: * @return associated pseudonym identity, NULL if none stored
102: */
103: identification_t* (*get_pseudonym)(simaka_card_t *this, identification_t *id);
104:
105: /**
106: * Store parameters to use for the next fast reauthentication.
107: *
108: * @param id permanent identity of the peer
109: * @param next next fast reauthentication identity to use
110: * @param mk master key MK to store for reauthentication
111: * @param counter counter value to store, host order
112: */
113: void (*set_reauth)(simaka_card_t *this, identification_t *id,
114: identification_t *next, char mk[HASH_SIZE_SHA1],
115: uint16_t counter);
116:
117: /**
118: * Retrieve parameters for fast reauthentication stored via set_reauth().
119: *
120: * @param id permanent identity of the peer
121: * @param mk buffer receiving master key MK
122: * @param counter pointer receiving counter value, in host order
123: * @return fast reauthentication identity, NULL if not found
124: */
125: identification_t* (*get_reauth)(simaka_card_t *this, identification_t *id,
126: char mk[HASH_SIZE_SHA1], uint16_t *counter);
127: };
128:
129: #endif /** SIMAKA_CARD_H_ @}*/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>