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