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