contrib/wpa_supplicant-0.4.9/eap_i.h

   1 /*
   2  * WPA Supplicant / EAP state machines internal structures (RFC 4137)
   3  * Copyright (c) 2004-2005, Jouni Malinen <jkmaline@cc.hut.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 "eap.h"
  19
  20 /* RFC 4137 - EAP Peer state machine */
  21
  22 typedef enum {
  23         DECISION_FAIL, DECISION_COND_SUCC, DECISION_UNCOND_SUCC
  24 } EapDecision;
  25
  26 typedef enum {
  27         METHOD_NONE, METHOD_INIT, METHOD_CONT, METHOD_MAY_CONT, METHOD_DONE
  28 } EapMethodState;
  29
  30 /**
  31  * struct eap_method_ret - EAP return values from struct eap_method::process()
  32  *
  33  * These structure contains OUT variables for the interface between peer state
  34  * machine and methods (RFC 4137, Sect. 4.2). eapRespData will be returned as
  35  * the return value of struct eap_method::process() so it is not included in
  36  * this structure.
  37  */
  38 struct eap_method_ret {
  39         /**
  40          * ignore - Whether method decided to drop the current packed (OUT)
  41          */
  42         Boolean ignore;
  43
  44         /**
  45          * methodState - Method-specific state (IN/OUT)
  46          */
  47         EapMethodState methodState;
  48
  49         /**
  50          * decision - Authentication decision (OUT)
  51          */
  52         EapDecision decision;
  53
  54         /**
  55          * allowNotifications - Whether method allows notifications (OUT)
  56          */
  57         Boolean allowNotifications;
  58 };
  59
  60
  61 /**
  62  * struct eap_method - EAP method interface
  63  * This structure defines the EAP method interface. Each method will need to
  64  * register its own EAP type, EAP name, and set of function pointers for method
  65  * specific operations. This interface is based on section 4.4 of RFC 4137.
  66  */
  67 struct eap_method {
  68         /**
  69          * method - EAP type number (EAP_TYPE_*)
  70          */
  71         EapType method;
  72
  73         /**
  74          * name - Name of the method (e.g., "TLS")
  75          */
  76         const char *name;
  77
  78         /**
  79          * init - Initialize an EAP method
  80          * @sm: Pointer to EAP state machine allocated with eap_sm_init()
  81          * Returns: Pointer to allocated private data, or %NULL on failure
  82          *
  83          * This function is used to initialize the EAP method explicitly
  84          * instead of using METHOD_INIT state as specific in RFC 4137. The
  85          * method is expected to initialize it method-specific state and return
  86          * a pointer that will be used as the priv argument to other calls.
  87          */
  88         void * (*init)(struct eap_sm *sm);
  89
  90         /**
  91          * deinit - Deinitialize an EAP method
  92          * @sm: Pointer to EAP state machine allocated with eap_sm_init()
  93          * @priv: Pointer to private EAP method data from eap_method::init()
  94          *
  95          * Deinitialize the EAP method and free any allocated private data.
  96          */
  97         void (*deinit)(struct eap_sm *sm, void *priv);
  98
  99         /**
 100          * process - Process an EAP request
 101          * @sm: Pointer to EAP state machine allocated with eap_sm_init()
 102          * @priv: Pointer to private EAP method data from eap_method::init()
 103          * @ret: Return values from EAP request validation and processing
 104          * @reqData: EAP request to be processed (eapReqData)
 105          * @reqDataLen: Length of the EAP request
 106          * @respDataLen: Length of the returned EAP response
 107          * Returns: Pointer to allocated EAP response packet (eapRespData)
 108          *
 109          * This function is a combination of m.check(), m.process(), and
 110          * m.buildResp() procedures defined in section 4.4 of RFC 4137 In other
 111          * words, this function validates the incoming request, processes it,
 112          * and build a response packet. m.check() and m.process() return values
 113          * are returned through struct eap_method_ret *ret variable. Caller is
 114          * responsible for freeing the returned EAP response packet.
 115          */
 116         u8 * (*process)(struct eap_sm *sm, void *priv,
 117                         struct eap_method_ret *ret,
 118                         const u8 *reqData, size_t reqDataLen,
 119                         size_t *respDataLen);
 120
 121         /**
 122          * isKeyAvailable - Find out whether EAP method has keying material
 123          * @sm: Pointer to EAP state machine allocated with eap_sm_init()
 124          * @priv: Pointer to private EAP method data from eap_method::init()
 125          * Returns: %TRUE if key material (eapKeyData) is available
 126          */
 127         Boolean (*isKeyAvailable)(struct eap_sm *sm, void *priv);
 128
 129         /**
 130          * getKey - Get EAP method specific keying material (eapKeyData)
 131          * @sm: Pointer to EAP state machine allocated with eap_sm_init()
 132          * @priv: Pointer to private EAP method data from eap_method::init()
 133          * @len: Pointer to variable to store key length (eapKeyDataLen)
 134          * Returns: Keying material (eapKeyData) or %NULL if not available
 135          *
 136          * This function can be used to get the keying material from the EAP
 137          * method. The key may already be stored in the method-specific private
 138          * data or this function may derive the key.
 139          */
 140         u8 * (*getKey)(struct eap_sm *sm, void *priv, size_t *len);
 141
 142         /**
 143          * get_status - Get EAP method status
 144          * @sm: Pointer to EAP state machine allocated with eap_sm_init()
 145          * @priv: Pointer to private EAP method data from eap_method::init()
 146          * @buf: Buffer for status information
 147          * @buflen: Maximum buffer length
 148          * @verbose: Whether to include verbose status information
 149          * Returns: Number of bytes written to buf
 150          *
 151          * Query EAP method for status information. This function fills in a
 152          * text area with current status information from the EAP method. If
 153          * the buffer (buf) is not large enough, status information will be
 154          * truncated to fit the buffer.
 155          */
 156         int (*get_status)(struct eap_sm *sm, void *priv, char *buf,
 157                           size_t buflen, int verbose);
 158
 159         /**
 160          * has_reauth_data - Whether method is ready for fast reauthentication
 161          * @sm: Pointer to EAP state machine allocated with eap_sm_init()
 162          * @priv: Pointer to private EAP method data from eap_method::init()
 163          * Returns: %TRUE or %FALSE based on whether fast reauthentication is
 164          * possible
 165          *
 166          * This function is an optional handler that only EAP methods
 167          * supporting fast re-authentication need to implement.
 168          */
 169         Boolean (*has_reauth_data)(struct eap_sm *sm, void *priv);
 170
 171         /**
 172          * deinit_for_reauth - Release data that is not needed for fast re-auth
 173          * @sm: Pointer to EAP state machine allocated with eap_sm_init()
 174          * @priv: Pointer to private EAP method data from eap_method::init()
 175          *
 176          * This function is an optional handler that only EAP methods
 177          * supporting fast re-authentication need to implement. This is called
 178          * when authentication has been completed and EAP state machine is
 179          * requesting that enough state information is maintained for fast
 180          * re-authentication
 181          */
 182         void (*deinit_for_reauth)(struct eap_sm *sm, void *priv);
 183
 184         /**
 185          * init_for_reauth - Prepare for start of fast re-authentication
 186          * @sm: Pointer to EAP state machine allocated with eap_sm_init()
 187          * @priv: Pointer to private EAP method data from eap_method::init()
 188          *
 189          * This function is an optional handler that only EAP methods
 190          * supporting fast re-authentication need to implement. This is called
 191          * when EAP authentication is started and EAP state machine is
 192          * requesting fast re-authentication to be used.
 193          */
 194         void * (*init_for_reauth)(struct eap_sm *sm, void *priv);
 195
 196         /**
 197          * get_identity - Get method specific identity for re-authentication
 198          * @sm: Pointer to EAP state machine allocated with eap_sm_init()
 199          * @priv: Pointer to private EAP method data from eap_method::init()
 200          * @len: Length of the returned identity
 201          * Returns: Pointer to the method specific identity or %NULL if default
 202          * identity is to be used
 203          *
 204          * This function is an optional handler that only EAP methods
 205          * that use method specific identity need to implement.
 206          */
 207         const u8 * (*get_identity)(struct eap_sm *sm, void *priv, size_t *len);
 208 };
 209
 210
 211 /**
 212  * struct eap_sm - EAP state machine data
 213  */
 214 struct eap_sm {
 215         enum {
 216                 EAP_INITIALIZE, EAP_DISABLED, EAP_IDLE, EAP_RECEIVED,
 217                 EAP_GET_METHOD, EAP_METHOD, EAP_SEND_RESPONSE, EAP_DISCARD,
 218                 EAP_IDENTITY, EAP_NOTIFICATION, EAP_RETRANSMIT, EAP_SUCCESS,
 219                 EAP_FAILURE
 220         } EAP_state;
 221         /* Long-term local variables */
 222         EapType selectedMethod;
 223         EapMethodState methodState;
 224         int lastId;
 225         u8 *lastRespData;
 226         size_t lastRespDataLen;
 227         EapDecision decision;
 228         /* Short-term local variables */
 229         Boolean rxReq;
 230         Boolean rxSuccess;
 231         Boolean rxFailure;
 232         int reqId;
 233         EapType reqMethod;
 234         Boolean ignore;
 235         /* Constants */
 236         int ClientTimeout;
 237
 238         /* Miscellaneous variables */
 239         Boolean allowNotifications; /* peer state machine <-> methods */
 240         u8 *eapRespData; /* peer to lower layer */
 241         size_t eapRespDataLen; /* peer to lower layer */
 242         Boolean eapKeyAvailable; /* peer to lower layer */
 243         u8 *eapKeyData; /* peer to lower layer */
 244         size_t eapKeyDataLen; /* peer to lower layer */
 245         const struct eap_method *m; /* selected EAP method */
 246         /* not defined in RFC 4137 */
 247         Boolean changed;
 248         void *eapol_ctx;
 249         struct eapol_callbacks *eapol_cb;
 250         void *eap_method_priv;
 251         int init_phase2;
 252         int fast_reauth;
 253
 254         Boolean rxResp /* LEAP only */;
 255         Boolean leap_done;
 256         Boolean peap_done;
 257         u8 req_md5[16]; /* MD5() of the current EAP packet */
 258         u8 last_md5[16]; /* MD5() of the previously received EAP packet; used
 259                           * in duplicate request detection. */
 260
 261         void *msg_ctx;
 262         void *scard_ctx;
 263         void *ssl_ctx;
 264
 265         unsigned int workaround;
 266
 267         /* Optional challenges generated in Phase 1 (EAP-FAST) */
 268         u8 *peer_challenge, *auth_challenge;
 269
 270         int num_rounds;
 271         int force_disabled;
 272 };
 273
 274 const u8 * eap_hdr_validate(EapType eap_type, const u8 *msg, size_t msglen,
 275                             size_t *plen);
 276 void eap_set_config_blob(struct eap_sm *sm, struct wpa_config_blob *blob);
 277 const struct wpa_config_blob *
 278 eap_get_config_blob(struct eap_sm *sm, const char *name);
 279
 280 #endif /* EAP_I_H */