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