diff options
Diffstat (limited to 'src/libsimaka/simaka_manager.h')
| -rw-r--r-- | src/libsimaka/simaka_manager.h | 315 |
1 files changed, 315 insertions, 0 deletions
diff --git a/src/libsimaka/simaka_manager.h b/src/libsimaka/simaka_manager.h new file mode 100644 index 000000000..64a67e56c --- /dev/null +++ b/src/libsimaka/simaka_manager.h @@ -0,0 +1,315 @@ +/* + * Copyright (C) 2008-2011 Martin Willi + * Hochschule fuer Technik Rapperswil + * + * This program is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the + * Free Software Foundation; either version 2 of the License, or (at your + * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>. + * + * This program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * for more details. + */ + +/** + * @defgroup simaka_manager simaka_manager + * @{ @ingroup libsimaka + */ + +#ifndef SIMAKA_MANAGER_H_ +#define SIMAKA_MANAGER_H_ + +#include <crypto/hashers/hasher.h> +#include <utils/identification.h> +#include <utils/enumerator.h> +#include <plugins/plugin.h> + +typedef struct simaka_manager_t simaka_manager_t; + +#define SIM_RAND_LEN 16 +#define SIM_SRES_LEN 4 +#define SIM_KC_LEN 8 + +#define AKA_RAND_LEN 16 +#define AKA_RES_MAX 16 +#define AKA_CK_LEN 16 +#define AKA_IK_LEN 16 +#define AKA_AUTN_LEN 16 +#define AKA_AUTS_LEN 14 + +#include "simaka_card.h" +#include "simaka_provider.h" +#include "simaka_hooks.h" + +/** + * The SIM manager handles multiple (U)SIM cards/providers and hooks. + */ +struct simaka_manager_t { + + /** + * Register a SIM card (client) at the manager. + * + * @param card sim card to register + */ + void (*add_card)(simaka_manager_t *this, simaka_card_t *card); + + /** + * Unregister a previously registered card from the manager. + * + * @param card sim card to unregister + */ + void (*remove_card)(simaka_manager_t *this, simaka_card_t *card); + + /** + * Calculate SIM triplets on one of the registered SIM cards. + * + * @param id permanent identity to get a triplet for + * @param rand RAND input buffer, fixed size 16 bytes + * @param sres SRES output buffer, fixed size 4 byte + * @param kc KC output buffer, fixed size 8 bytes + * @return TRUE if calculated, FALSE if no matching card found + */ + bool (*card_get_triplet)(simaka_manager_t *this, identification_t *id, + char rand[SIM_RAND_LEN], char sres[SIM_SRES_LEN], + char kc[SIM_KC_LEN]); + + /** + * Calculate AKA quitpulets on one of the registered SIM cards. + * + * @param id permanent identity to request quintuplet for + * @param rand random value rand + * @param autn authentication token autn + * @param ck buffer receiving encryption key ck + * @param ik buffer receiving integrity key ik + * @param res buffer receiving authentication result res + * @param res_len nubmer of bytes written to res buffer + * @return SUCCESS, FAILED, or INVALID_STATE if out of sync + */ + status_t (*card_get_quintuplet)(simaka_manager_t *this, identification_t *id, + char rand[AKA_RAND_LEN], char autn[AKA_AUTN_LEN], + char ck[AKA_CK_LEN], char ik[AKA_IK_LEN], + char res[AKA_RES_MAX], int *res_len); + + /** + * Calculate resynchronization data on one of the registered SIM cards. + * + * @param id permanent identity to request quintuplet for + * @param rand random value rand + * @param auts resynchronization parameter auts + * @return TRUE if calculated, FALSE if no matcing card found + */ + bool (*card_resync)(simaka_manager_t *this, identification_t *id, + char rand[AKA_RAND_LEN], char auts[AKA_AUTS_LEN]); + + /** + * Store a received pseudonym on one of the registered SIM cards. + * + * @param id permanent identity of the peer + * @param pseudonym pseudonym identity received from the server + */ + void (*card_set_pseudonym)(simaka_manager_t *this, identification_t *id, + identification_t *pseudonym); + + /** + * Get a stored pseudonym from one of the registered SIM cards. + * + * @param id permanent identity of the peer + * @return associated pseudonym identity, NULL if none found + */ + identification_t* (*card_get_pseudonym)(simaka_manager_t *this, + identification_t *id); + + /** + * Store fast reauthentication parameters on one of the registered cards. + * + * @param id permanent identity of the peer + * @param next next fast reauthentication identity to use + * @param mk master key MK to store for reauthentication + * @param counter counter value to store, host order + */ + void (*card_set_reauth)(simaka_manager_t *this, identification_t *id, + identification_t *next, char mk[HASH_SIZE_SHA1], + u_int16_t counter); + + /** + * Retrieve fast reauthentication parameters from one of the registered cards. + * + * @param id permanent identity of the peer + * @param mk buffer receiving master key MK + * @param counter pointer receiving counter value, in host order + * @return fast reauthentication identity, NULL if none found + */ + identification_t* (*card_get_reauth)(simaka_manager_t *this, + identification_t *id, char mk[HASH_SIZE_SHA1], + u_int16_t *counter); + + /** + * Register a triplet provider (server) at the manager. + * + * @param card sim card to register + */ + void (*add_provider)(simaka_manager_t *this, simaka_provider_t *provider); + + /** + * Unregister a previously registered provider from the manager. + * + * @param card sim card to unregister + */ + void (*remove_provider)(simaka_manager_t *this, simaka_provider_t *provider); + + /** + * Get a SIM triplet from one of the registered providers. + * + * @param id permanent identity of peer to gen triplet for + * @param rand RAND output buffer, fixed size 16 bytes + * @param sres SRES output buffer, fixed size 4 byte + * @param kc KC output buffer, fixed size 8 bytes + * @return TRUE if triplet received, FALSE if no match found + */ + bool (*provider_get_triplet)(simaka_manager_t *this, identification_t *id, + char rand[SIM_RAND_LEN], char sres[SIM_SRES_LEN], + char kc[SIM_KC_LEN]); + + /** + * Get a AKA quintuplet from one of the registered providers. + * + * @param id permanent identity of peer to create challenge for + * @param rand buffer receiving random value rand + * @param xres buffer receiving expected authentication result xres + * @param ck buffer receiving encryption key ck + * @param ik buffer receiving integrity key ik + * @param autn authentication token autn + * @return TRUE if quintuplet received, FALSE if no match found + */ + bool (*provider_get_quintuplet)(simaka_manager_t *this, identification_t *id, + char rand[AKA_RAND_LEN], + char xres[AKA_RES_MAX], int *xres_len, + char ck[AKA_CK_LEN], char ik[AKA_IK_LEN], + char autn[AKA_AUTN_LEN]); + + /** + * Pass AKA resynchronization data to one of the registered providers. + * + * @param id permanent identity of peer requesting resynchronisation + * @param rand random value rand + * @param auts synchronization parameter auts + * @return TRUE if resynchronized, FALSE if not handled + */ + bool (*provider_resync)(simaka_manager_t *this, identification_t *id, + char rand[AKA_RAND_LEN], char auts[AKA_AUTS_LEN]); + + /** + * Check if a peer uses a pseudonym using one of the registered providers. + * + * @param id pseudonym identity candidate + * @return permanent identity, NULL if id not a pseudonym + */ + identification_t* (*provider_is_pseudonym)(simaka_manager_t *this, + identification_t *id); + + /** + * Generate a new pseudonym using one of the registered providers. + * + * @param id permanent identity to generate a pseudonym for + * @return generated pseudonym, NULL to not use a pseudonym identity + */ + identification_t* (*provider_gen_pseudonym)(simaka_manager_t *this, + identification_t *id); + + /** + * Check if a peer uses a reauth id using one of the registered providers. + * + * @param id reauthentication identity (candidate) + * @param mk buffer receiving master key MK + * @param counter pointer receiving current counter value, host order + * @return permanent identity, NULL if not a known reauth identity + */ + identification_t* (*provider_is_reauth)(simaka_manager_t *this, + identification_t *id, char mk[HASH_SIZE_SHA1], + u_int16_t *counter); + + /** + * Generate a fast reauth id using one of the registered providers. + * + * @param id permanent peer identity + * @param mk master key to store along with generated identity + * @return fast reauthentication identity, NULL to not use reauth + */ + identification_t* (*provider_gen_reauth)(simaka_manager_t *this, + identification_t *id, char mk[HASH_SIZE_SHA1]); + + /** + * Register a set of hooks to the manager. + * + * @param hooks hook interface implementation to register + */ + void (*add_hooks)(simaka_manager_t *this, simaka_hooks_t *hooks); + + /** + * Unregister a set of hooks from the manager. + * + * @param hooks hook interface implementation to unregister + */ + void (*remove_hooks)(simaka_manager_t *this, simaka_hooks_t *hooks); + + /** + * Invoke SIM/AKA message hook. + * + * @param message SIM message + * @param inbound TRUE for incoming messages, FALSE for outgoing + * @param decrypted TRUE if AT_ENCR_DATA has been decrypted + */ + void (*message_hook)(simaka_manager_t *this, simaka_message_t *message, + bool inbound, bool decrypted); + + /** + * Invoke SIM/AKA key hook. + * + * @param k_encr SIM/AKA encryption key k_encr + * @param k_auth SIM/AKA authentication key k_auth + */ + void (*key_hook)(simaka_manager_t *this, chunk_t k_encr, chunk_t k_auth); + + /** + * Destroy a manager instance. + */ + void (*destroy)(simaka_manager_t *this); +}; + +/** + * Dummy libsimaka initialization function needed for integrity test + */ +void libsimaka_init(void); + +/** + * Create an SIM/AKA manager to handle multiple (U)SIM cards/providers. + * + * @return simaka_t object + */ +simaka_manager_t *simaka_manager_create(); + +/** + * Callback for the simaka_manager_register_cb_t, provides backend to register. + * + * @param plugin plugin registering a backend (card or provider) + * @return a simaka_card_t* or simaka_provider_t*, NULL on failure + */ +typedef void* (*simaka_manager_register_cb_t)(plugin_t *plugin); + +/** + * Helper function to (un-)register SIM/AKA backend plugin features. + * + * This function is a plugin_feature_callback_t and can be used with the + * PLUGIN_CALLBACK macro to register a SIM/AKA backend. + * + * @param plugin plugin registering the SIM/AKA backend + * @param feature associated plugin feature + * @param reg TRUE to register, FALSE to unregister. + * @param data data passed to callback, an simaka_manager_register_cb_t + */ +bool simaka_manager_register(plugin_t *plugin, plugin_feature_t *feature, + bool reg, void *data); + +#endif /** SIMAKA_MANAGER_H_ @}*/ |