libimcv: Moved REST API from imv_swid and imv_swima to libimcv
[strongswan.git] / src / libsimaka / simaka_provider.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_provider simaka_provider
18 * @{ @ingroup libsimaka
19 */
20
21 #ifndef SIMAKA_PROVIDER_H_
22 #define SIMAKA_PROVIDER_H_
23
24 typedef struct simaka_provider_t simaka_provider_t;
25
26 #include "simaka_manager.h"
27
28 #include <utils/identification.h>
29
30 /**
31 * Interface for a triplet/quintuplet provider (used as EAP server).
32 *
33 * A SIM provider hands out triplets for SIM authentication and quintuplets
34 * for AKA authentication. Multiple SIM provider instances can serve as
35 * authentication backend to authenticate clients using SIM/AKA.
36 * An implementation supporting only one of SIM/AKA authentication may
37 * implement the other methods with return_false().
38 */
39 struct simaka_provider_t {
40
41 /**
42 * Create a challenge for SIM authentication.
43 *
44 * @param id permanent identity of peer to gen triplet for
45 * @param rand RAND output buffer, fixed size 16 bytes
46 * @param sres SRES output buffer, fixed size 4 byte
47 * @param kc KC output buffer, fixed size 8 bytes
48 * @return TRUE if triplet received, FALSE otherwise
49 */
50 bool (*get_triplet)(simaka_provider_t *this, identification_t *id,
51 char rand[SIM_RAND_LEN], char sres[SIM_SRES_LEN],
52 char kc[SIM_KC_LEN]);
53
54 /**
55 * Create a challenge for AKA authentication.
56 *
57 * The XRES value is the only one with variable length. Pass a buffer
58 * of at least AKA_RES_MAX, the actual number of bytes is written to the
59 * xres_len value. While the standard would allow any bit length between
60 * 32 and 128 bits, we support only full bytes for now.
61 *
62 * @param id permanent identity of peer to create challenge for
63 * @param rand buffer receiving random value rand
64 * @param xres buffer receiving expected authentication result xres
65 * @param xres_len number of bytes written to xres buffer
66 * @param ck buffer receiving encryption key ck
67 * @param ik buffer receiving integrity key ik
68 * @param autn authentication token autn
69 * @return TRUE if quintuplet generated successfully
70 */
71 bool (*get_quintuplet)(simaka_provider_t *this, identification_t *id,
72 char rand[AKA_RAND_LEN],
73 char xres[AKA_RES_MAX], int *xres_len,
74 char ck[AKA_CK_LEN], char ik[AKA_IK_LEN],
75 char autn[AKA_AUTN_LEN]);
76
77 /**
78 * Process AKA resynchroniusation request of a peer.
79 *
80 * @param id permanent identity of peer requesting resynchronisation
81 * @param rand random value rand
82 * @param auts synchronization parameter auts
83 * @return TRUE if resynchronized successfully
84 */
85 bool (*resync)(simaka_provider_t *this, identification_t *id,
86 char rand[AKA_RAND_LEN], char auts[AKA_AUTS_LEN]);
87
88 /**
89 * Check if peer uses a pseudonym, get permanent identity.
90 *
91 * @param id pseudonym identity candidate
92 * @return permanent identity, NULL if id not a pseudonym
93 */
94 identification_t* (*is_pseudonym)(simaka_provider_t *this,
95 identification_t *id);
96
97 /**
98 * Generate a pseudonym identitiy for a given peer identity.
99 *
100 * @param id permanent identity to generate a pseudonym for
101 * @return generated pseudonym, NULL to not use a pseudonym identity
102 */
103 identification_t* (*gen_pseudonym)(simaka_provider_t *this,
104 identification_t *id);
105
106 /**
107 * Check if peer uses reauthentication, retrieve reauth parameters.
108 *
109 * @param id reauthentication identity (candidate)
110 * @param mk buffer receiving master key MK
111 * @param counter pointer receiving current counter value, host order
112 * @return permanent identity, NULL if id not a reauth identity
113 */
114 identification_t* (*is_reauth)(simaka_provider_t *this, identification_t *id,
115 char mk[HASH_SIZE_SHA1], uint16_t *counter);
116
117 /**
118 * Generate a fast reauthentication identity, associated to a master key.
119 *
120 * @param id permanent peer identity
121 * @param mk master key to store along with generated identity
122 * @return fast reauthentication identity, NULL to not use reauth
123 */
124 identification_t* (*gen_reauth)(simaka_provider_t *this, identification_t *id,
125 char mk[HASH_SIZE_SHA1]);
126 };
127
128 #endif /** SIMAKA_CARD_H_ @}*/