contrib/hostapd/src/eap_peer/eap.h

   1 /*
   2  * EAP peer state machine functions (RFC 4137)
   3  * Copyright (c) 2004-2007, Jouni Malinen <j@w1.fi>
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License version 2 as
   7  * published by the Free Software Foundation.
   8  *
   9  * Alternatively, this software may be distributed under the terms of BSD
  10  * license.
  11  *
  12  * See README and COPYING for more details.
  13  */
  14
  15 #ifndef EAP_H
  16 #define EAP_H
  17
  18 #include "defs.h"
  19 #include "eap_common/eap_defs.h"
  20 #include "eap_peer/eap_methods.h"
  21
  22 struct eap_sm;
  23 struct wpa_config_blob;
  24 struct wpabuf;
  25
  26 struct eap_method_type {
  27         int vendor;
  28         u32 method;
  29 };
  30
  31 #ifdef IEEE8021X_EAPOL
  32
  33 /**
  34  * enum eapol_bool_var - EAPOL boolean state variables for EAP state machine
  35  *
  36  * These variables are used in the interface between EAP peer state machine and
  37  * lower layer. These are defined in RFC 4137, Sect. 4.1. Lower layer code is
  38  * expected to maintain these variables and register a callback functions for
  39  * EAP state machine to get and set the variables.
  40  */
  41 enum eapol_bool_var {
  42         /**
  43          * EAPOL_eapSuccess - EAP SUCCESS state reached
  44          *
  45          * EAP state machine reads and writes this value.
  46          */
  47         EAPOL_eapSuccess,
  48
  49         /**
  50          * EAPOL_eapRestart - Lower layer request to restart authentication
  51          *
  52          * Set to TRUE in lower layer, FALSE in EAP state machine.
  53          */
  54         EAPOL_eapRestart,
  55
  56         /**
  57          * EAPOL_eapFail - EAP FAILURE state reached
  58          *
  59          * EAP state machine writes this value.
  60          */
  61         EAPOL_eapFail,
  62
  63         /**
  64          * EAPOL_eapResp - Response to send
  65          *
  66          * Set to TRUE in EAP state machine, FALSE in lower layer.
  67          */
  68         EAPOL_eapResp,
  69
  70         /**
  71          * EAPOL_eapNoResp - Request has been process; no response to send
  72          *
  73          * Set to TRUE in EAP state machine, FALSE in lower layer.
  74          */
  75         EAPOL_eapNoResp,
  76
  77         /**
  78          * EAPOL_eapReq - EAP request available from lower layer
  79          *
  80          * Set to TRUE in lower layer, FALSE in EAP state machine.
  81          */
  82         EAPOL_eapReq,
  83
  84         /**
  85          * EAPOL_portEnabled - Lower layer is ready for communication
  86          *
  87          * EAP state machines reads this value.
  88          */
  89         EAPOL_portEnabled,
  90
  91         /**
  92          * EAPOL_altAccept - Alternate indication of success (RFC3748)
  93          *
  94          * EAP state machines reads this value.
  95          */
  96         EAPOL_altAccept,
  97
  98         /**
  99          * EAPOL_altReject - Alternate indication of failure (RFC3748)
 100          *
 101          * EAP state machines reads this value.
 102          */
 103         EAPOL_altReject
 104 };
 105
 106 /**
 107  * enum eapol_int_var - EAPOL integer state variables for EAP state machine
 108  *
 109  * These variables are used in the interface between EAP peer state machine and
 110  * lower layer. These are defined in RFC 4137, Sect. 4.1. Lower layer code is
 111  * expected to maintain these variables and register a callback functions for
 112  * EAP state machine to get and set the variables.
 113  */
 114 enum eapol_int_var {
 115         /**
 116          * EAPOL_idleWhile - Outside time for EAP peer timeout
 117          *
 118          * This integer variable is used to provide an outside timer that the
 119          * external (to EAP state machine) code must decrement by one every
 120          * second until the value reaches zero. This is used in the same way as
 121          * EAPOL state machine timers. EAP state machine reads and writes this
 122          * value.
 123          */
 124         EAPOL_idleWhile
 125 };
 126
 127 /**
 128  * struct eapol_callbacks - Callback functions from EAP to lower layer
 129  *
 130  * This structure defines the callback functions that EAP state machine
 131  * requires from the lower layer (usually EAPOL state machine) for updating
 132  * state variables and requesting information. eapol_ctx from
 133  * eap_peer_sm_init() call will be used as the ctx parameter for these
 134  * callback functions.
 135  */
 136 struct eapol_callbacks {
 137         /**
 138          * get_config - Get pointer to the current network configuration
 139          * @ctx: eapol_ctx from eap_peer_sm_init() call
 140          */
 141         struct eap_peer_config * (*get_config)(void *ctx);
 142
 143         /**
 144          * get_bool - Get a boolean EAPOL state variable
 145          * @variable: EAPOL boolean variable to get
 146          * Returns: Value of the EAPOL variable
 147          */
 148         Boolean (*get_bool)(void *ctx, enum eapol_bool_var variable);
 149
 150         /**
 151          * set_bool - Set a boolean EAPOL state variable
 152          * @ctx: eapol_ctx from eap_peer_sm_init() call
 153          * @variable: EAPOL boolean variable to set
 154          * @value: Value for the EAPOL variable
 155          */
 156         void (*set_bool)(void *ctx, enum eapol_bool_var variable,
 157                          Boolean value);
 158
 159         /**
 160          * get_int - Get an integer EAPOL state variable
 161          * @ctx: eapol_ctx from eap_peer_sm_init() call
 162          * @variable: EAPOL integer variable to get
 163          * Returns: Value of the EAPOL variable
 164          */
 165         unsigned int (*get_int)(void *ctx, enum eapol_int_var variable);
 166
 167         /**
 168          * set_int - Set an integer EAPOL state variable
 169          * @ctx: eapol_ctx from eap_peer_sm_init() call
 170          * @variable: EAPOL integer variable to set
 171          * @value: Value for the EAPOL variable
 172          */
 173         void (*set_int)(void *ctx, enum eapol_int_var variable,
 174                         unsigned int value);
 175
 176         /**
 177          * get_eapReqData - Get EAP-Request data
 178          * @ctx: eapol_ctx from eap_peer_sm_init() call
 179          * @len: Pointer to variable that will be set to eapReqDataLen
 180          * Returns: Reference to eapReqData (EAP state machine will not free
 181          * this) or %NULL if eapReqData not available.
 182          */
 183         struct wpabuf * (*get_eapReqData)(void *ctx);
 184
 185         /**
 186          * set_config_blob - Set named configuration blob
 187          * @ctx: eapol_ctx from eap_peer_sm_init() call
 188          * @blob: New value for the blob
 189          *
 190          * Adds a new configuration blob or replaces the current value of an
 191          * existing blob.
 192          */
 193         void (*set_config_blob)(void *ctx, struct wpa_config_blob *blob);
 194
 195         /**
 196          * get_config_blob - Get a named configuration blob
 197          * @ctx: eapol_ctx from eap_peer_sm_init() call
 198          * @name: Name of the blob
 199          * Returns: Pointer to blob data or %NULL if not found
 200          */
 201         const struct wpa_config_blob * (*get_config_blob)(void *ctx,
 202                                                           const char *name);
 203
 204         /**
 205          * notify_pending - Notify that a pending request can be retried
 206          * @ctx: eapol_ctx from eap_peer_sm_init() call
 207          *
 208          * An EAP method can perform a pending operation (e.g., to get a
 209          * response from an external process). Once the response is available,
 210          * this callback function can be used to request EAPOL state machine to
 211          * retry delivering the previously received (and still unanswered) EAP
 212          * request to EAP state machine.
 213          */
 214         void (*notify_pending)(void *ctx);
 215
 216         /**
 217          * eap_param_needed - Notify that EAP parameter is needed
 218          * @ctx: eapol_ctx from eap_peer_sm_init() call
 219          * @field: Field name (e.g., "IDENTITY")
 220          * @txt: User readable text describing the required parameter
 221          */
 222         void (*eap_param_needed)(void *ctx, const char *field,
 223                                  const char *txt);
 224 };
 225
 226 /**
 227  * struct eap_config - Configuration for EAP state machine
 228  */
 229 struct eap_config {
 230         /**
 231          * opensc_engine_path - OpenSC engine for OpenSSL engine support
 232          *
 233          * Usually, path to engine_opensc.so.
 234          */
 235         const char *opensc_engine_path;
 236         /**
 237          * pkcs11_engine_path - PKCS#11 engine for OpenSSL engine support
 238          *
 239          * Usually, path to engine_pkcs11.so.
 240          */
 241         const char *pkcs11_engine_path;
 242         /**
 243          * pkcs11_module_path - OpenSC PKCS#11 module for OpenSSL engine
 244          *
 245          * Usually, path to opensc-pkcs11.so.
 246          */
 247         const char *pkcs11_module_path;
 248         /**
 249          * wps - WPS context data
 250          *
 251          * This is only used by EAP-WSC and can be left %NULL if not available.
 252          */
 253         struct wps_context *wps;
 254 };
 255
 256 struct eap_sm * eap_peer_sm_init(void *eapol_ctx,
 257                                  struct eapol_callbacks *eapol_cb,
 258                                  void *msg_ctx, struct eap_config *conf);
 259 void eap_peer_sm_deinit(struct eap_sm *sm);
 260 int eap_peer_sm_step(struct eap_sm *sm);
 261 void eap_sm_abort(struct eap_sm *sm);
 262 int eap_sm_get_status(struct eap_sm *sm, char *buf, size_t buflen,
 263                       int verbose);
 264 struct wpabuf * eap_sm_buildIdentity(struct eap_sm *sm, int id, int encrypted);
 265 void eap_sm_request_identity(struct eap_sm *sm);
 266 void eap_sm_request_password(struct eap_sm *sm);
 267 void eap_sm_request_new_password(struct eap_sm *sm);
 268 void eap_sm_request_pin(struct eap_sm *sm);
 269 void eap_sm_request_otp(struct eap_sm *sm, const char *msg, size_t msg_len);
 270 void eap_sm_request_passphrase(struct eap_sm *sm);
 271 void eap_sm_notify_ctrl_attached(struct eap_sm *sm);
 272 u32 eap_get_phase2_type(const char *name, int *vendor);
 273 struct eap_method_type * eap_get_phase2_types(struct eap_peer_config *config,
 274                                               size_t *count);
 275 void eap_set_fast_reauth(struct eap_sm *sm, int enabled);
 276 void eap_set_workaround(struct eap_sm *sm, unsigned int workaround);
 277 void eap_set_force_disabled(struct eap_sm *sm, int disabled);
 278 int eap_key_available(struct eap_sm *sm);
 279 void eap_notify_success(struct eap_sm *sm);
 280 void eap_notify_lower_layer_success(struct eap_sm *sm);
 281 const u8 * eap_get_eapKeyData(struct eap_sm *sm, size_t *len);
 282 struct wpabuf * eap_get_eapRespData(struct eap_sm *sm);
 283 void eap_register_scard_ctx(struct eap_sm *sm, void *ctx);
 284 void eap_invalidate_cached_session(struct eap_sm *sm);
 285
 286 int eap_is_wps_pbc_enrollee(struct eap_peer_config *conf);
 287 int eap_is_wps_pin_enrollee(struct eap_peer_config *conf);
 288
 289 #endif /* IEEE8021X_EAPOL */
 290
 291 #endif /* EAP_H */