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