src/libsimaka/simaka_manager.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_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 <utils/enumerator.h>
  27
  28 typedef struct simaka_manager_t simaka_manager_t;
  29
  30 #define SIM_RAND_LEN    16
  31 #define SIM_SRES_LEN     4
  32 #define SIM_KC_LEN               8
  33
  34 #define AKA_RAND_LEN    16
  35 #define AKA_RES_MAX             16
  36 #define AKA_CK_LEN              16
  37 #define AKA_IK_LEN              16
  38 #define AKA_AUTN_LEN    16
  39 #define AKA_AUTS_LEN    14
  40
  41 #include "simaka_card.h"
  42 #include "simaka_provider.h"
  43 #include "simaka_hooks.h"
  44
  45 /**
  46  * The SIM manager handles multiple (U)SIM cards/providers and hooks.
  47  */
  48 struct simaka_manager_t {
  49
  50         /**
  51          * Register a SIM card (client) at the manager.
  52          *
  53          * @param card          sim card to register
  54          */
  55         void (*add_card)(simaka_manager_t *this, simaka_card_t *card);
  56
  57         /**
  58          * Unregister a previously registered card from the manager.
  59          *
  60          * @param card          sim card to unregister
  61          */
  62         void (*remove_card)(simaka_manager_t *this, simaka_card_t *card);
  63
  64         /**
  65          * Calculate SIM triplets on one of the registered SIM cards.
  66          *
  67          * @param id            permanent identity to get a triplet for
  68          * @param rand          RAND input buffer, fixed size 16 bytes
  69          * @param sres          SRES output buffer, fixed size 4 byte
  70          * @param kc            KC output buffer, fixed size 8 bytes
  71          * @return                      TRUE if calculated, FALSE if no matching card found
  72          */
  73         bool (*card_get_triplet)(simaka_manager_t *this, identification_t *id,
  74                                                          char rand[SIM_RAND_LEN], char sres[SIM_SRES_LEN],
  75                                                          char kc[SIM_KC_LEN]);
  76
  77         /**
  78          * Calculate AKA quitpulets on one of the registered SIM cards.
  79          *
  80          * @param id            permanent identity to request quintuplet for
  81          * @param rand          random value rand
  82          * @param autn          authentication token autn
  83          * @param ck            buffer receiving encryption key ck
  84          * @param ik            buffer receiving integrity key ik
  85          * @param res           buffer receiving authentication result res
  86          * @param res_len       nubmer of bytes written to res buffer
  87          * @return                      SUCCESS, FAILED, or INVALID_STATE if out of sync
  88          */
  89         status_t (*card_get_quintuplet)(simaka_manager_t *this, identification_t *id,
  90                                                                 char rand[AKA_RAND_LEN], char autn[AKA_AUTN_LEN],
  91                                                                 char ck[AKA_CK_LEN], char ik[AKA_IK_LEN],
  92                                                                 char res[AKA_RES_MAX], int *res_len);
  93
  94         /**
  95          * Calculate resynchronization data on one of the registered SIM cards.
  96          *
  97          * @param id            permanent identity to request quintuplet for
  98          * @param rand          random value rand
  99          * @param auts          resynchronization parameter auts
 100          * @return                      TRUE if calculated, FALSE if no matcing card found
 101          */
 102         bool (*card_resync)(simaka_manager_t *this, identification_t *id,
 103                                                 char rand[AKA_RAND_LEN], char auts[AKA_AUTS_LEN]);
 104
 105         /**
 106          * Store a received pseudonym on one of the registered SIM cards.
 107          *
 108          * @param id            permanent identity of the peer
 109          * @param pseudonym     pseudonym identity received from the server
 110          */
 111         void (*card_set_pseudonym)(simaka_manager_t *this, identification_t *id,
 112                                                            identification_t *pseudonym);
 113
 114         /**
 115          * Get a stored pseudonym from one of the registerd SIM cards.
 116          *
 117          * @param id            permanent identity of the peer
 118          * @return                      associated pseudonym identity, NULL if none found
 119          */
 120         identification_t* (*card_get_pseudonym)(simaka_manager_t *this,
 121                                                                                         identification_t *id);
 122
 123         /**
 124          * Store fast reauthentication parameters on one of the registered cards.
 125          *
 126          * @param id            permanent identity of the peer
 127          * @param next          next fast reauthentication identity to use
 128          * @param mk            master key MK to store for reauthentication
 129          * @param counter       counter value to store, host order
 130          */
 131         void (*card_set_reauth)(simaka_manager_t *this, identification_t *id,
 132                                                         identification_t *next, char mk[HASH_SIZE_SHA1],
 133                                                         u_int16_t counter);
 134
 135         /**
 136          * Retrieve fast reauthentication parameters from one of the registerd cards.
 137          *
 138          * @param id            permanent identity of the peer
 139          * @param mk            buffer receiving master key MK
 140          * @param counter       pointer receiving counter value, in host order
 141          * @return                      fast reauthentication identity, NULL if none found
 142          */
 143         identification_t* (*card_get_reauth)(simaka_manager_t *this,
 144                                                                 identification_t *id, char mk[HASH_SIZE_SHA1],
 145                                                                 u_int16_t *counter);
 146
 147         /**
 148          * Register a triplet provider (server) at the manager.
 149          *
 150          * @param card          sim card to register
 151          */
 152         void (*add_provider)(simaka_manager_t *this, simaka_provider_t *provider);
 153
 154         /**
 155          * Unregister a previously registered provider from the manager.
 156          *
 157          * @param card          sim card to unregister
 158          */
 159         void (*remove_provider)(simaka_manager_t *this, simaka_provider_t *provider);
 160
 161         /**
 162          * Get a SIM triplet from one of the registered providers.
 163          *
 164          * @param id            permanent identity of peer to gen triplet for
 165          * @param rand          RAND output buffer, fixed size 16 bytes
 166          * @param sres          SRES output buffer, fixed size 4 byte
 167          * @param kc            KC output buffer, fixed size 8 bytes
 168          * @return                      TRUE if triplet received, FALSE if no match found
 169          */
 170         bool (*provider_get_triplet)(simaka_manager_t *this, identification_t *id,
 171                                                         char rand[SIM_RAND_LEN], char sres[SIM_SRES_LEN],
 172                                                         char kc[SIM_KC_LEN]);
 173
 174         /**
 175          * Get a AKA quintuplet from one of the registered providers.
 176          *
 177          * @param id            permanent identity of peer to create challenge for
 178          * @param rand          buffer receiving random value rand
 179          * @param xres          buffer receiving expected authentication result xres
 180          * @param ck            buffer receiving encryption key ck
 181          * @param ik            buffer receiving integrity key ik
 182          * @param autn          authentication token autn
 183          * @return                      TRUE if quintuplet received, FALSE if no match found
 184          */
 185         bool (*provider_get_quintuplet)(simaka_manager_t *this, identification_t *id,
 186                                                         char rand[AKA_RAND_LEN],
 187                                                         char xres[AKA_RES_MAX], int *xres_len,
 188                                                         char ck[AKA_CK_LEN], char ik[AKA_IK_LEN],
 189                                                         char autn[AKA_AUTN_LEN]);
 190
 191         /**
 192          * Pass AKA resynchronization data to one of the registered providers.
 193          *
 194          * @param id            permanent identity of peer requesting resynchronisation
 195          * @param rand          random value rand
 196          * @param auts          synchronization parameter auts
 197          * @return                      TRUE if resynchronized, FALSE if not handled
 198          */
 199         bool (*provider_resync)(simaka_manager_t *this, identification_t *id,
 200                                                         char rand[AKA_RAND_LEN], char auts[AKA_AUTS_LEN]);
 201
 202         /**
 203          * Check if a peer uses a pseudonym using one of the registered providers.
 204          *
 205          * @param id            pseudonym identity candidate
 206          * @return                      permanent identity, NULL if id not a pseudonym
 207          */
 208         identification_t* (*provider_is_pseudonym)(simaka_manager_t *this,
 209                                                                                            identification_t *id);
 210
 211         /**
 212          * Generate a new pseudonym using one of the registered providers.
 213          *
 214          * @param id            permanent identity to generate a pseudonym for
 215          * @return                      generated pseudonym, NULL to not use a pseudonym identity
 216          */
 217         identification_t* (*provider_gen_pseudonym)(simaka_manager_t *this,
 218                                                                                                 identification_t *id);
 219
 220         /**
 221          * Check if a peer uses a reauth id using one of the registered providers.
 222          *
 223          * @param id            reauthentication identity (candidate)
 224          * @param mk            buffer receiving master key MK
 225          * @param counter       pointer receiving current counter value, host order
 226          * @return                      permanent identity, NULL if not a known reauth identity
 227          */
 228         identification_t* (*provider_is_reauth)(simaka_manager_t *this,
 229                                                                 identification_t *id, char mk[HASH_SIZE_SHA1],
 230                                                                 u_int16_t *counter);
 231
 232         /**
 233          * Generate a fast reauth id using one of the registered providers.
 234          *
 235          * @param id            permanent peer identity
 236          * @param mk            master key to store along with generated identity
 237          * @return                      fast reauthentication identity, NULL to not use reauth
 238          */
 239         identification_t* (*provider_gen_reauth)(simaka_manager_t *this,
 240                                                                 identification_t *id, char mk[HASH_SIZE_SHA1]);
 241
 242         /**
 243          * Register a set of hooks to the manager.
 244          *
 245          * @param hooks         hook interface implementation to register
 246          */
 247         void (*add_hooks)(simaka_manager_t *this, simaka_hooks_t *hooks);
 248
 249         /**
 250          * Unregister a set of hooks from the manager.
 251          *
 252          * @param hooks         hook interface implementation to unregister
 253          */
 254         void (*remove_hooks)(simaka_manager_t *this, simaka_hooks_t *hooks);
 255
 256         /**
 257          * Invoke SIM/AKA message hook.
 258          *
 259          * @param message       SIM message
 260          * @param inbound       TRUE for incoming messages, FALSE for outgoing
 261          * @param decrypted     TRUE if AT_ENCR_DATA has been decrypted
 262          */
 263         void (*message_hook)(simaka_manager_t *this, simaka_message_t *message,
 264                                                  bool inbound, bool decrypted);
 265
 266         /**
 267          * Invoke SIM/AKA key hook.
 268          *
 269          * @param k_encr        SIM/AKA encryption key k_encr
 270          * @param k_auth        SIM/AKA authentication key k_auth
 271          */
 272         void (*key_hook)(simaka_manager_t *this, chunk_t k_encr, chunk_t k_auth);
 273
 274         /**
 275          * Destroy a manager instance.
 276          */
 277         void (*destroy)(simaka_manager_t *this);
 278 };
 279
 280 /**
 281  * Create an SIM/AKA manager to handle multiple (U)SIM cards/providers.
 282  *
 283  * @return                      simaka_t object
 284  */
 285 simaka_manager_t *simaka_manager_create();
 286
 287 #endif /** SIMAKA_MANAGER_H_ @}*/