www.project-moonshot.org Git - mech_eap.orig/blob - libeap/src/eap_peer/eap_i.h

   1 /*
   2  * EAP peer state machines internal structures (RFC 4137)
   3  * Copyright (c) 2004-2007, Jouni Malinen <j@w1.fi>
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License version 2 as
   7  * published by the Free Software Foundation.
   8  *
   9  * Alternatively, this software may be distributed under the terms of BSD
  10  * license.
  11  *
  12  * See README and COPYING for more details.
  13  */
  14
  15 #ifndef EAP_I_H
  16 #define EAP_I_H
  17
  18 #include "wpabuf.h"
  19 #include "eap_peer/eap.h"
  20 #include "eap_common/eap_common.h"
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 /* RFC 4137 - EAP Peer state machine */
  27
  28 typedef enum {
  29         DECISION_FAIL, DECISION_COND_SUCC, DECISION_UNCOND_SUCC
  30 } EapDecision;
  31
  32 typedef enum {
  33         METHOD_NONE, METHOD_INIT, METHOD_CONT, METHOD_MAY_CONT, METHOD_DONE
  34 } EapMethodState;
  35
  36 /**
  37  * struct eap_method_ret - EAP return values from struct eap_method::process()
  38  *
  39  * These structure contains OUT variables for the interface between peer state
  40  * machine and methods (RFC 4137, Sect. 4.2). eapRespData will be returned as
  41  * the return value of struct eap_method::process() so it is not included in
  42  * this structure.
  43  */
  44 struct eap_method_ret {
  45         /**
  46          * ignore - Whether method decided to drop the current packed (OUT)
  47          */
  48         Boolean ignore;
  49
  50         /**
  51          * methodState - Method-specific state (IN/OUT)
  52          */
  53         EapMethodState methodState;
  54
  55         /**
  56          * decision - Authentication decision (OUT)
  57          */
  58         EapDecision decision;
  59
  60         /**
  61          * allowNotifications - Whether method allows notifications (OUT)
  62          */
  63         Boolean allowNotifications;
  64 };
  65
  66
  67 /**
  68  * struct eap_method - EAP method interface
  69  * This structure defines the EAP method interface. Each method will need to
  70  * register its own EAP type, EAP name, and set of function pointers for method
  71  * specific operations. This interface is based on section 4.4 of RFC 4137.
  72  */
  73 struct eap_method {
  74         /**
  75          * vendor - EAP Vendor-ID (EAP_VENDOR_*) (0 = IETF)
  76          */
  77         int vendor;
  78
  79         /**
  80          * method - EAP type number (EAP_TYPE_*)
  81          */
  82         EapType method;
  83
  84         /**
  85          * name - Name of the method (e.g., "TLS")
  86          */
  87         const char *name;
  88
  89         /**
  90          * init - Initialize an EAP method
  91          * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init()
  92          * Returns: Pointer to allocated private data, or %NULL on failure
  93          *
  94          * This function is used to initialize the EAP method explicitly
  95          * instead of using METHOD_INIT state as specific in RFC 4137. The
  96          * method is expected to initialize it method-specific state and return
  97          * a pointer that will be used as the priv argument to other calls.
  98          */
  99         void * (*init)(struct eap_sm *sm);
 100
 101         /**
 102          * deinit - Deinitialize an EAP method
 103          * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init()
 104          * @priv: Pointer to private EAP method data from eap_method::init()
 105          *
 106          * Deinitialize the EAP method and free any allocated private data.
 107          */
 108         void (*deinit)(struct eap_sm *sm, void *priv);
 109
 110         /**
 111          * process - Process an EAP request
 112          * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init()
 113          * @priv: Pointer to private EAP method data from eap_method::init()
 114          * @ret: Return values from EAP request validation and processing
 115          * @reqData: EAP request to be processed (eapReqData)
 116          * Returns: Pointer to allocated EAP response packet (eapRespData)
 117          *
 118          * This function is a combination of m.check(), m.process(), and
 119          * m.buildResp() procedures defined in section 4.4 of RFC 4137 In other
 120          * words, this function validates the incoming request, processes it,
 121          * and build a response packet. m.check() and m.process() return values
 122          * are returned through struct eap_method_ret *ret variable. Caller is
 123          * responsible for freeing the returned EAP response packet.
 124          */
 125         struct wpabuf * (*process)(struct eap_sm *sm, void *priv,
 126                                    struct eap_method_ret *ret,
 127                                    const struct wpabuf *reqData);
 128
 129         /**
 130          * isKeyAvailable - Find out whether EAP method has keying material
 131          * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init()
 132          * @priv: Pointer to private EAP method data from eap_method::init()
 133          * Returns: %TRUE if key material (eapKeyData) is available
 134          */
 135         Boolean (*isKeyAvailable)(struct eap_sm *sm, void *priv);
 136
 137         /**
 138          * getKey - Get EAP method specific keying material (eapKeyData)
 139          * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init()
 140          * @priv: Pointer to private EAP method data from eap_method::init()
 141          * @len: Pointer to variable to store key length (eapKeyDataLen)
 142          * Returns: Keying material (eapKeyData) or %NULL if not available
 143          *
 144          * This function can be used to get the keying material from the EAP
 145          * method. The key may already be stored in the method-specific private
 146          * data or this function may derive the key.
 147          */
 148         u8 * (*getKey)(struct eap_sm *sm, void *priv, size_t *len);
 149
 150         /**
 151          * get_status - Get EAP method status
 152          * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init()
 153          * @priv: Pointer to private EAP method data from eap_method::init()
 154          * @buf: Buffer for status information
 155          * @buflen: Maximum buffer length
 156          * @verbose: Whether to include verbose status information
 157          * Returns: Number of bytes written to buf
 158          *
 159          * Query EAP method for status information. This function fills in a
 160          * text area with current status information from the EAP method. If
 161          * the buffer (buf) is not large enough, status information will be
 162          * truncated to fit the buffer.
 163          */
 164         int (*get_status)(struct eap_sm *sm, void *priv, char *buf,
 165                           size_t buflen, int verbose);
 166
 167         /**
 168          * has_reauth_data - Whether method is ready for fast reauthentication
 169          * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init()
 170          * @priv: Pointer to private EAP method data from eap_method::init()
 171          * Returns: %TRUE or %FALSE based on whether fast reauthentication is
 172          * possible
 173          *
 174          * This function is an optional handler that only EAP methods
 175          * supporting fast re-authentication need to implement.
 176          */
 177         Boolean (*has_reauth_data)(struct eap_sm *sm, void *priv);
 178
 179         /**
 180          * deinit_for_reauth - Release data that is not needed for fast re-auth
 181          * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init()
 182          * @priv: Pointer to private EAP method data from eap_method::init()
 183          *
 184          * This function is an optional handler that only EAP methods
 185          * supporting fast re-authentication need to implement. This is called
 186          * when authentication has been completed and EAP state machine is
 187          * requesting that enough state information is maintained for fast
 188          * re-authentication
 189          */
 190         void (*deinit_for_reauth)(struct eap_sm *sm, void *priv);
 191
 192         /**
 193          * init_for_reauth - Prepare for start of fast re-authentication
 194          * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init()
 195          * @priv: Pointer to private EAP method data from eap_method::init()
 196          *
 197          * This function is an optional handler that only EAP methods
 198          * supporting fast re-authentication need to implement. This is called
 199          * when EAP authentication is started and EAP state machine is
 200          * requesting fast re-authentication to be used.
 201          */
 202         void * (*init_for_reauth)(struct eap_sm *sm, void *priv);
 203
 204         /**
 205          * get_identity - Get method specific identity for re-authentication
 206          * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init()
 207          * @priv: Pointer to private EAP method data from eap_method::init()
 208          * @len: Length of the returned identity
 209          * Returns: Pointer to the method specific identity or %NULL if default
 210          * identity is to be used
 211          *
 212          * This function is an optional handler that only EAP methods
 213          * that use method specific identity need to implement.
 214          */
 215         const u8 * (*get_identity)(struct eap_sm *sm, void *priv, size_t *len);
 216
 217         /**
 218          * free - Free EAP method data
 219          * @method: Pointer to the method data registered with
 220          * eap_peer_method_register().
 221          *
 222          * This function will be called when the EAP method is being
 223          * unregistered. If the EAP method allocated resources during
 224          * registration (e.g., allocated struct eap_method), they should be
 225          * freed in this function. No other method functions will be called
 226          * after this call. If this function is not defined (i.e., function
 227          * pointer is %NULL), a default handler is used to release the method
 228          * data with free(method). This is suitable for most cases.
 229          */
 230         void (*free)(struct eap_method *method);
 231
 232 #define EAP_PEER_METHOD_INTERFACE_VERSION 1
 233         /**
 234          * version - Version of the EAP peer method interface
 235          *
 236          * The EAP peer method implementation should set this variable to
 237          * EAP_PEER_METHOD_INTERFACE_VERSION. This is used to verify that the
 238          * EAP method is using supported API version when using dynamically
 239          * loadable EAP methods.
 240          */
 241         int version;
 242
 243         /**
 244          * next - Pointer to the next EAP method
 245          *
 246          * This variable is used internally in the EAP method registration code
 247          * to create a linked list of registered EAP methods.
 248          */
 249         struct eap_method *next;
 250
 251 #ifdef CONFIG_DYNAMIC_EAP_METHODS
 252         /**
 253          * dl_handle - Handle for the dynamic library
 254          *
 255          * This variable is used internally in the EAP method registration code
 256          * to store a handle for the dynamic library. If the method is linked
 257          * in statically, this is %NULL.
 258          */
 259         void *dl_handle;
 260 #endif /* CONFIG_DYNAMIC_EAP_METHODS */
 261
 262         /**
 263          * get_emsk - Get EAP method specific keying extended material (EMSK)
 264          * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init()
 265          * @priv: Pointer to private EAP method data from eap_method::init()
 266          * @len: Pointer to a variable to store EMSK length
 267          * Returns: EMSK or %NULL if not available
 268          *
 269          * This function can be used to get the extended keying material from
 270          * the EAP method. The key may already be stored in the method-specific
 271          * private data or this function may derive the key.
 272          */
 273         u8 * (*get_emsk)(struct eap_sm *sm, void *priv, size_t *len);
 274 };
 275
 276
 277 /**
 278  * struct eap_sm - EAP state machine data
 279  */
 280 struct eap_sm {
 281         enum {
 282                 EAP_INITIALIZE, EAP_DISABLED, EAP_IDLE, EAP_RECEIVED,
 283                 EAP_GET_METHOD, EAP_METHOD, EAP_SEND_RESPONSE, EAP_DISCARD,
 284                 EAP_IDENTITY, EAP_NOTIFICATION, EAP_RETRANSMIT, EAP_SUCCESS,
 285                 EAP_FAILURE
 286         } EAP_state;
 287         /* Long-term local variables */
 288         EapType selectedMethod;
 289         EapMethodState methodState;
 290         int lastId;
 291         struct wpabuf *lastRespData;
 292         EapDecision decision;
 293         /* Short-term local variables */
 294         Boolean rxReq;
 295         Boolean rxSuccess;
 296         Boolean rxFailure;
 297         int reqId;
 298         EapType reqMethod;
 299         int reqVendor;
 300         u32 reqVendorMethod;
 301         Boolean ignore;
 302         /* Constants */
 303         int ClientTimeout;
 304
 305         /* Miscellaneous variables */
 306         Boolean allowNotifications; /* peer state machine <-> methods */
 307         struct wpabuf *eapRespData; /* peer to lower layer */
 308         Boolean eapKeyAvailable; /* peer to lower layer */
 309         u8 *eapKeyData; /* peer to lower layer */
 310         size_t eapKeyDataLen; /* peer to lower layer */
 311         const struct eap_method *m; /* selected EAP method */
 312         /* not defined in RFC 4137 */
 313         Boolean changed;
 314         void *eapol_ctx;
 315         struct eapol_callbacks *eapol_cb;
 316         void *eap_method_priv;
 317         int init_phase2;
 318         int fast_reauth;
 319
 320         Boolean rxResp /* LEAP only */;
 321         Boolean leap_done;
 322         Boolean peap_done;
 323         u8 req_md5[16]; /* MD5() of the current EAP packet */
 324         u8 last_md5[16]; /* MD5() of the previously received EAP packet; used
 325                           * in duplicate request detection. */
 326
 327         void *msg_ctx;
 328         void *scard_ctx;
 329         void *ssl_ctx;
 330
 331         unsigned int workaround;
 332
 333         /* Optional challenges generated in Phase 1 (EAP-FAST) */
 334         u8 *peer_challenge, *auth_challenge;
 335
 336         int num_rounds;
 337         int force_disabled;
 338
 339         struct wps_context *wps;
 340
 341         int prev_failure;
 342 };
 343
 344 const u8 * eap_get_config_identity(struct eap_sm *sm, size_t *len);
 345 const u8 * eap_get_config_password(struct eap_sm *sm, size_t *len);
 346 const u8 * eap_get_config_password2(struct eap_sm *sm, size_t *len, int *hash);
 347 const u8 * eap_get_config_new_password(struct eap_sm *sm, size_t *len);
 348 const u8 * eap_get_config_otp(struct eap_sm *sm, size_t *len);
 349 void eap_clear_config_otp(struct eap_sm *sm);
 350 const char * eap_get_config_phase1(struct eap_sm *sm);
 351 const char * eap_get_config_phase2(struct eap_sm *sm);
 352 int eap_get_config_fragment_size(struct eap_sm *sm);
 353 struct eap_peer_config * eap_get_config(struct eap_sm *sm);
 354 void eap_set_config_blob(struct eap_sm *sm, struct wpa_config_blob *blob);
 355 const struct wpa_config_blob *
 356 eap_get_config_blob(struct eap_sm *sm, const char *name);
 357 void eap_notify_pending(struct eap_sm *sm);
 358 int eap_allowed_method(struct eap_sm *sm, int vendor, u32 method);
 359
 360 #ifdef __cplusplus
 361 }
 362 #endif
 363
 364 #endif /* EAP_I_H */