src/libsimaka/simaka_message.h

   1 /*
   2  * Copyright (C) 2009 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 libsimaka libsimaka
  18  *
  19  * @addtogroup libsimaka
  20  * Library providing functions shared between EAP-SIM and EAP-AKA plugins.
  21  *
  22  * @defgroup simaka_message simaka_message
  23  * @{ @ingroup libsimaka
  24  */
  25
  26 #ifndef SIMAKA_MESSAGE_H_
  27 #define SIMAKA_MESSAGE_H_
  28
  29 #include <enum.h>
  30 #include <eap/eap.h>
  31
  32 #include "simaka_crypto.h"
  33
  34 typedef enum simaka_attribute_t simaka_attribute_t;
  35 typedef enum simaka_subtype_t simaka_subtype_t;
  36 typedef enum simaka_notification_t simaka_notification_t;
  37 typedef enum simaka_client_error_t simaka_client_error_t;
  38 typedef struct simaka_message_t simaka_message_t;
  39
  40 /**
  41  * Subtypes of EAP-SIM/AKA messages
  42  */
  43 enum simaka_subtype_t {
  44         AKA_CHALLENGE = 1,
  45         AKA_AUTHENTICATION_REJECT = 2,
  46         AKA_SYNCHRONIZATION_FAILURE = 4,
  47         AKA_IDENTITY = 5,
  48         SIM_START = 10,
  49         SIM_CHALLENGE = 11,
  50         SIM_NOTIFICATION = 12,
  51         AKA_NOTIFICATION = 12,
  52         SIM_REAUTHENTICATION = 13,
  53         AKA_REAUTHENTICATION = 13,
  54         SIM_CLIENT_ERROR = 14,
  55         AKA_CLIENT_ERROR = 14,
  56 };
  57
  58 /**
  59  * Enum names for simaka_subtype_t
  60  */
  61 extern enum_name_t *simaka_subtype_names;
  62
  63 /**
  64  * Attributes in EAP-SIM/AKA messages
  65  */
  66 enum simaka_attribute_t {
  67         AT_RAND = 1,
  68         AT_AUTN = 2,
  69         AT_RES = 3,
  70         AT_AUTS = 4,
  71         AT_PADDING = 6,
  72         AT_NONCE_MT = 7,
  73         AT_PERMANENT_ID_REQ = 10,
  74         AT_MAC = 11,
  75         AT_NOTIFICATION = 12,
  76         AT_ANY_ID_REQ = 13,
  77         AT_IDENTITY = 14,
  78         AT_VERSION_LIST = 15,
  79         AT_SELECTED_VERSION = 16,
  80         AT_FULLAUTH_ID_REQ = 17,
  81         AT_COUNTER = 19,
  82         AT_COUNTER_TOO_SMALL = 20,
  83         AT_NONCE_S = 21,
  84         AT_CLIENT_ERROR_CODE = 22,
  85         AT_IV = 129,
  86         AT_ENCR_DATA = 130,
  87         AT_NEXT_PSEUDONYM = 132,
  88         AT_NEXT_REAUTH_ID = 133,
  89         AT_CHECKCODE = 134,
  90         AT_RESULT_IND = 135,
  91 };
  92
  93 /**
  94  * Enum names for simaka_attribute_t
  95  */
  96 extern enum_name_t *simaka_attribute_names;
  97
  98 /**
  99  * Notification codes used within AT_NOTIFICATION attribute.
 100  */
 101 enum simaka_notification_t {
 102         /** SIM General failure after authentication. (Implies failure) */
 103         SIM_GENERAL_FAILURE_AA = 0,
 104         /** AKA General failure after authentication. (Implies failure) */
 105         AKA_GENERAL_FAILURE_AA = 0,
 106         /** SIM General failure. (Implies failure, used before authentication) */
 107         SIM_GENERAL_FAILURE = 16384,
 108         /** AKA General failure. (Implies failure, used before authentication) */
 109         AKA_GENERAL_FAILURE = 16384,
 110         /** SIM User has been temporarily denied access to the requested service. */
 111         SIM_TEMP_DENIED = 1026,
 112         /** AKA User has been temporarily denied access to the requested service. */
 113         AKA_TEMP_DENIED = 1026,
 114         /** SIM User has not subscribed to the requested service. */
 115         SIM_NOT_SUBSCRIBED = 1031,
 116         /** AKA User has not subscribed to the requested service. */
 117         AKA_NOT_SUBSCRIBED = 1031,
 118         /** SIM Success. User has been successfully authenticated. */
 119         SIM_SUCCESS = 32768,
 120         /** AKA Success. User has been successfully authenticated. */
 121         AKA_SUCCESS = 32768,
 122 };
 123
 124 /**
 125  * Enum names for simaka_notification_t
 126  */
 127 extern enum_name_t *simaka_notification_names;
 128
 129 /**
 130  * Error codes sent in AT_CLIENT_ERROR_CODE attribute
 131  */
 132 enum simaka_client_error_t {
 133         /** AKA unable to process packet */
 134         AKA_UNABLE_TO_PROCESS = 0,
 135         /** SIM unable to process packet */
 136         SIM_UNABLE_TO_PROCESS = 0,
 137         /** SIM unsupported version */
 138         SIM_UNSUPPORTED_VERSION = 1,
 139         /** SIM insufficient number of challenges */
 140         SIM_INSUFFICIENT_CHALLENGES = 2,
 141         /** SIM RANDs are not fresh */
 142         SIM_RANDS_NOT_FRESH = 3,
 143 };
 144
 145 /**
 146  * Enum names for simaka_client_error_t
 147  */
 148 extern enum_name_t *simaka_client_error_names;
 149
 150 /**
 151  * Check if an EAP-SIM/AKA attribute is "skippable".
 152  *
 153  * @param attribute             attribute to check
 154  * @return                              TRUE if attribute skippable, FALSE if non-skippable
 155  */
 156 bool simaka_attribute_skippable(simaka_attribute_t attribute);
 157
 158 /**
 159  * EAP-SIM and EAP-AKA message abstraction.
 160  *
 161  * Messages for EAP-SIM and EAP-AKA share a common format, this class
 162  * abstracts such a message and provides encoding/encryption/signing
 163  * functionality.
 164  */
 165 struct simaka_message_t {
 166
 167         /**
 168          * Check if the given message is a request or response.
 169          *
 170          * @return                      TRUE if request, FALSE if response
 171          */
 172         bool (*is_request)(simaka_message_t *this);
 173
 174         /**
 175          * Get the EAP message identifier.
 176          *
 177          * @return                      EAP message identifier
 178          */
 179         u_int8_t (*get_identifier)(simaka_message_t *this);
 180
 181         /**
 182          * Get the EAP type of the message.
 183          *
 184          * @return                      EAP type: EAP-SIM or EAP-AKA
 185          */
 186         eap_type_t (*get_type)(simaka_message_t *this);
 187
 188         /**
 189          * Get the subtype of an EAP-SIM message.
 190          *
 191          * @return                      subtype of message
 192          */
 193         simaka_subtype_t (*get_subtype)(simaka_message_t *this);
 194
 195         /**
 196          * Create an enumerator over message attributes.
 197          *
 198          * @return                      enumerator over (simaka_attribute_t, chunk_t)
 199          */
 200         enumerator_t* (*create_attribute_enumerator)(simaka_message_t *this);
 201
 202         /**
 203          * Append an attribute to the EAP-SIM message.
 204          *
 205          * Make sure to pass only data of correct length for the given attribute.
 206          *
 207          * @param type          type of attribute to add to message
 208          * @param data          unpadded attribute data to add
 209          */
 210         void (*add_attribute)(simaka_message_t *this, simaka_attribute_t type,
 211                                                   chunk_t data);
 212
 213         /**
 214          * Parse a message, with optional attribute decryption.
 215          *
 216          * This method does not verify message integrity, as the key is available
 217          * only after the payload has been parsed. It might be necessary to call
 218          * parse twice, as key derivation data in EAP-SIM/AKA is in the same
 219          * packet as encrypted data.
 220          *
 221          * @param crypto        EAP-SIM/AKA crypto helper
 222          * @return                      TRUE if message parsed successfully
 223          */
 224         bool (*parse)(simaka_message_t *this);
 225
 226         /**
 227          * Verify the message integrity of a parsed message.
 228          *
 229          * @param crypto        EAP-SIM/AKA crypto helper
 230          * @param sigdata       additional data to include in signature, if any
 231          * @return                      TRUE if message integrity check successful
 232          */
 233         bool (*verify)(simaka_message_t *this, chunk_t sigdata);
 234
 235         /**
 236          * Generate a message, optionally encrypt attributes and create a MAC.
 237          *
 238          * @param sigdata       additional data to include in signature, if any
 239          * @return                      allocated data of generated message
 240          */
 241         chunk_t (*generate)(simaka_message_t *this, chunk_t sigdata);
 242
 243         /**
 244          * Destroy a simaka_message_t.
 245          */
 246         void (*destroy)(simaka_message_t *this);
 247 };
 248
 249 /**
 250  * Create an empty simaka_message.
 251  *
 252  * @param request               TRUE for a request message, FALSE for a response
 253  * @param identifier    EAP message identifier
 254  * @param type                  EAP type: EAP-SIM or EAP-AKA
 255  * @param subtype               subtype of the EAP message
 256  * @param crypto                EAP-SIM/AKA crypto helper
 257  * @return                              empty message of requested kind, NULL on error
 258  */
 259 simaka_message_t *simaka_message_create(bool request, u_int8_t identifier,
 260                                                                         eap_type_t type, simaka_subtype_t subtype,
 261                                                                         simaka_crypto_t *crypto);
 262
 263 /**
 264  * Create an simaka_message from a chunk of data.
 265  *
 266  * @param data                  message data to parse
 267  * @param crypto                EAP-SIM/AKA crypto helper
 268  * @return                              EAP message, NULL on error
 269  */
 270 simaka_message_t *simaka_message_create_from_payload(chunk_t data,
 271                                                                                                          simaka_crypto_t *crypto);
 272
 273 #endif /** SIMAKA_MESSAGE_H_ @}*/