src/eap_peer/eap_i.h

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