contrib/wpa/src/eap_peer/eap.h

   1 /*
   2  * EAP peer state machine functions (RFC 4137)
   3  * Copyright (c) 2004-2012, 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_H
  10 #define EAP_H
  11
  12 #include "common/defs.h"
  13 #include "eap_common/eap_defs.h"
  14 #include "eap_peer/eap_methods.h"
  15
  16 struct eap_sm;
  17 struct wpa_config_blob;
  18 struct wpabuf;
  19 struct tls_cert_data;
  20
  21 struct eap_method_type {
  22         int vendor;
  23         u32 method;
  24 };
  25
  26 #ifdef IEEE8021X_EAPOL
  27
  28 /**
  29  * enum eapol_bool_var - EAPOL boolean state variables for EAP state machine
  30  *
  31  * These variables are used in the interface between EAP peer state machine and
  32  * lower layer. These are defined in RFC 4137, Sect. 4.1. Lower layer code is
  33  * expected to maintain these variables and register a callback functions for
  34  * EAP state machine to get and set the variables.
  35  */
  36 enum eapol_bool_var {
  37         /**
  38          * EAPOL_eapSuccess - EAP SUCCESS state reached
  39          *
  40          * EAP state machine reads and writes this value.
  41          */
  42         EAPOL_eapSuccess,
  43
  44         /**
  45          * EAPOL_eapRestart - Lower layer request to restart authentication
  46          *
  47          * Set to TRUE in lower layer, FALSE in EAP state machine.
  48          */
  49         EAPOL_eapRestart,
  50
  51         /**
  52          * EAPOL_eapFail - EAP FAILURE state reached
  53          *
  54          * EAP state machine writes this value.
  55          */
  56         EAPOL_eapFail,
  57
  58         /**
  59          * EAPOL_eapResp - Response to send
  60          *
  61          * Set to TRUE in EAP state machine, FALSE in lower layer.
  62          */
  63         EAPOL_eapResp,
  64
  65         /**
  66          * EAPOL_eapNoResp - Request has been process; no response to send
  67          *
  68          * Set to TRUE in EAP state machine, FALSE in lower layer.
  69          */
  70         EAPOL_eapNoResp,
  71
  72         /**
  73          * EAPOL_eapReq - EAP request available from lower layer
  74          *
  75          * Set to TRUE in lower layer, FALSE in EAP state machine.
  76          */
  77         EAPOL_eapReq,
  78
  79         /**
  80          * EAPOL_portEnabled - Lower layer is ready for communication
  81          *
  82          * EAP state machines reads this value.
  83          */
  84         EAPOL_portEnabled,
  85
  86         /**
  87          * EAPOL_altAccept - Alternate indication of success (RFC3748)
  88          *
  89          * EAP state machines reads this value.
  90          */
  91         EAPOL_altAccept,
  92
  93         /**
  94          * EAPOL_altReject - Alternate indication of failure (RFC3748)
  95          *
  96          * EAP state machines reads this value.
  97          */
  98         EAPOL_altReject,
  99
 100         /**
 101          * EAPOL_eapTriggerStart - EAP-based trigger to send EAPOL-Start
 102          *
 103          * EAP state machine writes this value.
 104          */
 105         EAPOL_eapTriggerStart
 106 };
 107
 108 /**
 109  * enum eapol_int_var - EAPOL integer state variables for EAP state machine
 110  *
 111  * These variables are used in the interface between EAP peer state machine and
 112  * lower layer. These are defined in RFC 4137, Sect. 4.1. Lower layer code is
 113  * expected to maintain these variables and register a callback functions for
 114  * EAP state machine to get and set the variables.
 115  */
 116 enum eapol_int_var {
 117         /**
 118          * EAPOL_idleWhile - Outside time for EAP peer timeout
 119          *
 120          * This integer variable is used to provide an outside timer that the
 121          * external (to EAP state machine) code must decrement by one every
 122          * second until the value reaches zero. This is used in the same way as
 123          * EAPOL state machine timers. EAP state machine reads and writes this
 124          * value.
 125          */
 126         EAPOL_idleWhile
 127 };
 128
 129 /**
 130  * struct eapol_callbacks - Callback functions from EAP to lower layer
 131  *
 132  * This structure defines the callback functions that EAP state machine
 133  * requires from the lower layer (usually EAPOL state machine) for updating
 134  * state variables and requesting information. eapol_ctx from
 135  * eap_peer_sm_init() call will be used as the ctx parameter for these
 136  * callback functions.
 137  */
 138 struct eapol_callbacks {
 139         /**
 140          * get_config - Get pointer to the current network configuration
 141          * @ctx: eapol_ctx from eap_peer_sm_init() call
 142          */
 143         struct eap_peer_config * (*get_config)(void *ctx);
 144
 145         /**
 146          * get_bool - Get a boolean EAPOL state variable
 147          * @variable: EAPOL boolean variable to get
 148          * Returns: Value of the EAPOL variable
 149          */
 150         Boolean (*get_bool)(void *ctx, enum eapol_bool_var variable);
 151
 152         /**
 153          * set_bool - Set a boolean EAPOL state variable
 154          * @ctx: eapol_ctx from eap_peer_sm_init() call
 155          * @variable: EAPOL boolean variable to set
 156          * @value: Value for the EAPOL variable
 157          */
 158         void (*set_bool)(void *ctx, enum eapol_bool_var variable,
 159                          Boolean value);
 160
 161         /**
 162          * get_int - Get an integer EAPOL state variable
 163          * @ctx: eapol_ctx from eap_peer_sm_init() call
 164          * @variable: EAPOL integer variable to get
 165          * Returns: Value of the EAPOL variable
 166          */
 167         unsigned int (*get_int)(void *ctx, enum eapol_int_var variable);
 168
 169         /**
 170          * set_int - Set an integer EAPOL state variable
 171          * @ctx: eapol_ctx from eap_peer_sm_init() call
 172          * @variable: EAPOL integer variable to set
 173          * @value: Value for the EAPOL variable
 174          */
 175         void (*set_int)(void *ctx, enum eapol_int_var variable,
 176                         unsigned int value);
 177
 178         /**
 179          * get_eapReqData - Get EAP-Request data
 180          * @ctx: eapol_ctx from eap_peer_sm_init() call
 181          * @len: Pointer to variable that will be set to eapReqDataLen
 182          * Returns: Reference to eapReqData (EAP state machine will not free
 183          * this) or %NULL if eapReqData not available.
 184          */
 185         struct wpabuf * (*get_eapReqData)(void *ctx);
 186
 187         /**
 188          * set_config_blob - Set named configuration blob
 189          * @ctx: eapol_ctx from eap_peer_sm_init() call
 190          * @blob: New value for the blob
 191          *
 192          * Adds a new configuration blob or replaces the current value of an
 193          * existing blob.
 194          */
 195         void (*set_config_blob)(void *ctx, struct wpa_config_blob *blob);
 196
 197         /**
 198          * get_config_blob - Get a named configuration blob
 199          * @ctx: eapol_ctx from eap_peer_sm_init() call
 200          * @name: Name of the blob
 201          * Returns: Pointer to blob data or %NULL if not found
 202          */
 203         const struct wpa_config_blob * (*get_config_blob)(void *ctx,
 204                                                           const char *name);
 205
 206         /**
 207          * notify_pending - Notify that a pending request can be retried
 208          * @ctx: eapol_ctx from eap_peer_sm_init() call
 209          *
 210          * An EAP method can perform a pending operation (e.g., to get a
 211          * response from an external process). Once the response is available,
 212          * this callback function can be used to request EAPOL state machine to
 213          * retry delivering the previously received (and still unanswered) EAP
 214          * request to EAP state machine.
 215          */
 216         void (*notify_pending)(void *ctx);
 217
 218         /**
 219          * eap_param_needed - Notify that EAP parameter is needed
 220          * @ctx: eapol_ctx from eap_peer_sm_init() call
 221          * @field: Field indicator (e.g., WPA_CTRL_REQ_EAP_IDENTITY)
 222          * @txt: User readable text describing the required parameter
 223          */
 224         void (*eap_param_needed)(void *ctx, enum wpa_ctrl_req_type field,
 225                                  const char *txt);
 226
 227         /**
 228          * notify_cert - Notification of a peer certificate
 229          * @ctx: eapol_ctx from eap_peer_sm_init() call
 230          * @cert: Certificate information
 231          * @cert_hash: SHA-256 hash of the certificate
 232          */
 233         void (*notify_cert)(void *ctx, struct tls_cert_data *cert,
 234                             const char *cert_hash);
 235
 236         /**
 237          * notify_status - Notification of the current EAP state
 238          * @ctx: eapol_ctx from eap_peer_sm_init() call
 239          * @status: Step in the process of EAP authentication
 240          * @parameter: Step-specific parameter, e.g., EAP method name
 241          */
 242         void (*notify_status)(void *ctx, const char *status,
 243                               const char *parameter);
 244
 245         /**
 246          * notify_eap_error - Report EAP method error code
 247          * @ctx: eapol_ctx from eap_peer_sm_init() call
 248          * @error_code: Error code from the used EAP method
 249          */
 250         void (*notify_eap_error)(void *ctx, int error_code);
 251
 252 #ifdef CONFIG_EAP_PROXY
 253         /**
 254          * eap_proxy_cb - Callback signifying any updates from eap_proxy
 255          * @ctx: eapol_ctx from eap_peer_sm_init() call
 256          */
 257         void (*eap_proxy_cb)(void *ctx);
 258
 259         /**
 260          * eap_proxy_notify_sim_status - Notification of SIM status change
 261          * @ctx: eapol_ctx from eap_peer_sm_init() call
 262          * @sim_state: One of enum value from sim_state
 263          */
 264         void (*eap_proxy_notify_sim_status)(void *ctx,
 265                                             enum eap_proxy_sim_state sim_state);
 266
 267         /**
 268          * get_imsi - Get the IMSI value from eap_proxy
 269          * @ctx: eapol_ctx from eap_peer_sm_init() call
 270          * @sim_num: SIM/USIM number to get the IMSI value for
 271          * @imsi: Buffer for IMSI value
 272          * @len: Buffer for returning IMSI length in octets
 273          * Returns: MNC length (2 or 3) or -1 on error
 274          */
 275         int (*get_imsi)(void *ctx, int sim_num, char *imsi, size_t *len);
 276 #endif /* CONFIG_EAP_PROXY */
 277
 278         /**
 279          * set_anon_id - Set or add anonymous identity
 280          * @ctx: eapol_ctx from eap_peer_sm_init() call
 281          * @id: Anonymous identity (e.g., EAP-SIM pseudonym) or %NULL to clear
 282          * @len: Length of anonymous identity in octets
 283          */
 284         void (*set_anon_id)(void *ctx, const u8 *id, size_t len);
 285 };
 286
 287 /**
 288  * struct eap_config - Configuration for EAP state machine
 289  */
 290 struct eap_config {
 291         /**
 292          * opensc_engine_path - OpenSC engine for OpenSSL engine support
 293          *
 294          * Usually, path to engine_opensc.so.
 295          */
 296         const char *opensc_engine_path;
 297         /**
 298          * pkcs11_engine_path - PKCS#11 engine for OpenSSL engine support
 299          *
 300          * Usually, path to engine_pkcs11.so.
 301          */
 302         const char *pkcs11_engine_path;
 303         /**
 304          * pkcs11_module_path - OpenSC PKCS#11 module for OpenSSL engine
 305          *
 306          * Usually, path to opensc-pkcs11.so.
 307          */
 308         const char *pkcs11_module_path;
 309         /**
 310          * openssl_ciphers - OpenSSL cipher string
 311          *
 312          * This is an OpenSSL specific configuration option for configuring the
 313          * default ciphers. If not set, "DEFAULT:!EXP:!LOW" is used as the
 314          * default.
 315          */
 316         const char *openssl_ciphers;
 317         /**
 318          * wps - WPS context data
 319          *
 320          * This is only used by EAP-WSC and can be left %NULL if not available.
 321          */
 322         struct wps_context *wps;
 323
 324         /**
 325          * cert_in_cb - Include server certificates in callback
 326          */
 327         int cert_in_cb;
 328 };
 329
 330 struct eap_sm * eap_peer_sm_init(void *eapol_ctx,
 331                                  const struct eapol_callbacks *eapol_cb,
 332                                  void *msg_ctx, struct eap_config *conf);
 333 void eap_peer_sm_deinit(struct eap_sm *sm);
 334 int eap_peer_sm_step(struct eap_sm *sm);
 335 void eap_sm_abort(struct eap_sm *sm);
 336 int eap_sm_get_status(struct eap_sm *sm, char *buf, size_t buflen,
 337                       int verbose);
 338 const char * eap_sm_get_method_name(struct eap_sm *sm);
 339 struct wpabuf * eap_sm_buildIdentity(struct eap_sm *sm, int id, int encrypted);
 340 void eap_sm_request_identity(struct eap_sm *sm);
 341 void eap_sm_request_password(struct eap_sm *sm);
 342 void eap_sm_request_new_password(struct eap_sm *sm);
 343 void eap_sm_request_pin(struct eap_sm *sm);
 344 void eap_sm_request_otp(struct eap_sm *sm, const char *msg, size_t msg_len);
 345 void eap_sm_request_passphrase(struct eap_sm *sm);
 346 void eap_sm_request_sim(struct eap_sm *sm, const char *req);
 347 void eap_sm_notify_ctrl_attached(struct eap_sm *sm);
 348 u32 eap_get_phase2_type(const char *name, int *vendor);
 349 struct eap_method_type * eap_get_phase2_types(struct eap_peer_config *config,
 350                                               size_t *count);
 351 void eap_set_fast_reauth(struct eap_sm *sm, int enabled);
 352 void eap_set_workaround(struct eap_sm *sm, unsigned int workaround);
 353 void eap_set_force_disabled(struct eap_sm *sm, int disabled);
 354 void eap_set_external_sim(struct eap_sm *sm, int external_sim);
 355 int eap_key_available(struct eap_sm *sm);
 356 void eap_notify_success(struct eap_sm *sm);
 357 void eap_notify_lower_layer_success(struct eap_sm *sm);
 358 const u8 * eap_get_eapSessionId(struct eap_sm *sm, size_t *len);
 359 const u8 * eap_get_eapKeyData(struct eap_sm *sm, size_t *len);
 360 struct wpabuf * eap_get_eapRespData(struct eap_sm *sm);
 361 void eap_register_scard_ctx(struct eap_sm *sm, void *ctx);
 362 void eap_invalidate_cached_session(struct eap_sm *sm);
 363
 364 int eap_is_wps_pbc_enrollee(struct eap_peer_config *conf);
 365 int eap_is_wps_pin_enrollee(struct eap_peer_config *conf);
 366
 367 struct ext_password_data;
 368 void eap_sm_set_ext_pw_ctx(struct eap_sm *sm, struct ext_password_data *ext);
 369 void eap_set_anon_id(struct eap_sm *sm, const u8 *id, size_t len);
 370 int eap_peer_was_failure_expected(struct eap_sm *sm);
 371 void eap_peer_erp_free_keys(struct eap_sm *sm);
 372 struct wpabuf * eap_peer_build_erp_reauth_start(struct eap_sm *sm, u8 eap_id);
 373 void eap_peer_finish(struct eap_sm *sm, const struct eap_hdr *hdr, size_t len);
 374 int eap_peer_get_erp_info(struct eap_sm *sm, struct eap_peer_config *config,
 375                           const u8 **username, size_t *username_len,
 376                           const u8 **realm, size_t *realm_len, u16 *erp_seq_num,
 377                           const u8 **rrk, size_t *rrk_len);
 378 int eap_peer_update_erp_next_seq_num(struct eap_sm *sm, u16 seq_num);
 379 void eap_peer_erp_init(struct eap_sm *sm, u8 *ext_session_id,
 380                        size_t ext_session_id_len, u8 *ext_emsk,
 381                        size_t ext_emsk_len);
 382
 383 #endif /* IEEE8021X_EAPOL */
 384
 385 #endif /* EAP_H */