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