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