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