1 /*

     2 * Copyright (c) 2001-2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  EAP and WLAN authentication protocols.

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #if !defined(_EAP_SESSION_CORE_H_)

    22 #define _EAP_SESSION_CORE_H_

    23 

    24 #include "eap_tools.h"

    25 #include "eap_am_export.h"

    26 #include "abs_eap_core.h"

    27 #include "eap_core_map.h"

    28 #include "abs_eap_stack_interface.h"

    29 

    30 class eap_core_c;

    31 class eap_network_id_selector_c;

    32 

    33 

    34 /**

    35  * This is the timer ID used with abs_eap_am_tools_c::set_timer() and abs_eap_am_tools_c::cancel_timer().

    36  */

    37 enum eap_session_core_timer_id

    38 {

    39 	EAP_SESSION_CORE_REMOVE_SESSION_ID, ///< See EAP_SESSION_CORE_REMOVE_SESSION_TIMEOUT.

    40 };

    41 

    42 /**

    43  * This is time after a EAP session is removed. This must be zero.

    44  */

    45 const u32_t EAP_SESSION_CORE_REMOVE_SESSION_TIMEOUT = 0u;

    46 

    47 

    48 /// A eap_session_core_c class implements mapping of EAP authentication sessions.

    49 /// Network identity separates parallel EAP authentication sessions.

    50 class EAP_EXPORT eap_session_core_c

    51 : public abs_eap_core_c

    52 , public abs_eap_core_map_c

    53 , public abs_eap_base_timer_c

    54 , public abs_eap_stack_interface_c

    55 {

    56 private:

    57 	//--------------------------------------------------

    58 

    59 	/// This is back pointer to object which created this object.

    60 	/// Packets are sent to the partner.

    61 	abs_eap_core_c * const m_partner;

    62 

    63 	/// This is pointer to the tools class.

    64 	abs_eap_am_tools_c * const m_am_tools;

    65 

    66 	/// This stores EAP authentication session objects using eap_variable_data selector.

    67 	eap_core_map_c<eap_core_c, abs_eap_core_map_c, eap_variable_data_c> m_session_map;

    68 

    69 	u32_t m_remove_session_timeout;

    70 

    71 	/// This indicates whether this object is client (true) or server (false).

    72 	/// In terms of EAP-protocol whether this network entity is EAP-supplicant (true) or EAP-authenticator (false).

    73 	bool m_is_client;

    74 

    75 	/// This indicates whether this object was generated successfully.

    76 	bool m_is_valid;

    77 

    78 	bool m_use_eap_session_core_reset_session;

    79 

    80 	bool m_shutdown_was_called;

    81 

    82 

    83 	/**

    84 	 * Function creates a new session.

    85 	 */

    86 	EAP_FUNC_IMPORT eap_core_c * create_new_session(

    87 		const eap_am_network_id_c * const receive_network_id);

    88 

    89 	EAP_FUNC_IMPORT eap_status_e reset_or_remove_session(

    90 		eap_core_c ** const session,

    91 		const eap_network_id_selector_c * const selector,

    92 		const bool reset_immediately);

    93 

    94 

    95 	EAP_FUNC_IMPORT static eap_status_e shutdown_operation(

    96 		eap_core_c * const core,

    97 		abs_eap_am_tools_c * const m_am_tools);

    98 

    99 	//--------------------------------------------------

   100 protected:

   101 	//--------------------------------------------------

   102 

   103 	//--------------------------------------------------

   104 public:

   105 	//--------------------------------------------------

   106 

   107 	/**

   108 	 * The destructor of the eap_core class does nothing special.

   109 	 */

   110 	EAP_FUNC_IMPORT virtual ~eap_session_core_c();

   111 

   112 	/**

   113 	 * The constructor initializes member attributes using parameters passed to it.

   114 	 * @param tools is pointer to the tools class. @see abs_eap_am_tools_c.

   115 	 * @param partner is back pointer to object which created this object.

   116 	 * @param is_client_when_true indicates whether the network entity should act

   117 	 * as a client (true) or server (false), in terms of EAP-protocol

   118 	 * whether this network entity is EAP-supplicant (true) or EAP-authenticator (false).

   119 	 */

   120 	EAP_FUNC_IMPORT eap_session_core_c(

   121 		abs_eap_am_tools_c * const tools,

   122 		abs_eap_core_c * const partner,

   123 		const bool is_client_when_true);

   124 

   125 	/**

   126 	 * This function must reset the state of object to same as 

   127 	 * state was after the configure() function call.

   128 	 * If object reset succeeds this function must return eap_status_ok.

   129 	 * If object reset fails this function must return corresponding error status.

   130 	 * @return This function returns the status of reset operation.

   131 	 */

   132 	EAP_FUNC_IMPORT eap_status_e reset();

   133 

   134 	/**

   135 	 * This function cancels all EAP-sessions.

   136 	 * If this succeeds this function must return eap_status_ok.

   137 	 * If this fails this function must return corresponding error status.

   138 	 * @return This function returns the status of operation.

   139 	 */

   140 	EAP_FUNC_IMPORT eap_status_e synchronous_cancel_all_eap_sessions();

   141 

   142 	// This is documented in abs_eap_stack_interface_c::packet_process().

   143 	EAP_FUNC_IMPORT eap_status_e packet_process(

   144 		const eap_am_network_id_c * const receive_network_id,

   145 		eap_general_header_base_c * const packet_data,

   146 		const u32_t packet_length); 

   147 

   148 	/**

   149 	 * The class could send packets to partner class with this function.

   150 	 * @param send_network_id carries the addresses (network identity) and type of the packet.

   151 	 * @param sent_packet includes the buffer for the whole packet and initialized 

   152 	 * EAP-packet in correct offset.

   153 	 * @param header_offset is offset of the EAP-header within the sent_packet.

   154 	 * @param data_length is length in bytes of the EAP-packet.

   155 	 * @param buffer_length is length in bytes of the whole packet buffer.

   156 	 */

   157 	EAP_FUNC_IMPORT eap_status_e packet_send(

   158 		const eap_am_network_id_c * const send_network_id,

   159 		eap_buf_chain_wr_c * const sent_packet,

   160 		const u32_t header_offset,

   161 		const u32_t data_length,

   162 		const u32_t buffer_length); 

   163 

   164 	/**

   165 	 * The get_partner() function returns pointer to partner class.

   166 	 */

   167 	EAP_FUNC_IMPORT abs_eap_core_c * get_partner();

   168 

   169 	/**

   170 	 * The get_header_offset() function obtains the header offset of EAP-packet.

   171 	 * @param MTU_length is pointer to variable to store the maximum transfer unit (MTU).

   172 	 * MTU is the maximum EAP-packet length in bytes

   173 	 * @param trailer_length is pointer to the variable to store length

   174 	 * of trailer needed by lower levels.

   175 	 * @return Function returns the offset of EAP-header.

   176 	 * @see abs_eap_base_type_c::get_header_offset().

   177 	 */

   178 	EAP_FUNC_IMPORT u32_t get_header_offset(

   179 		u32_t * const MTU,

   180 		u32_t * const trailer_length);

   181 

   182 	/**

   183 	 * The unload_module() function initializes un-load of desired EAP-type.

   184 	 * After the EAP-type is not needed this function should be called.

   185 	 */

   186 	EAP_FUNC_IMPORT eap_status_e unload_module(

   187 		const eap_type_value_e type); 

   188 

   189 	/**

   190 	 * The adaptation module calls the eap_acknowledge() function after

   191 	 * any Network Protocol packet is received. This is used as a success indication.

   192 	 * This is described in RFC 2284 "PPP Extensible Authentication Protocol (EAP)".

   193 	 * @param connection_handle separates the context of the acknowledged session.

   194 	 * Mostly there is only one session in the client.

   195 	 * The server does not need eap_acknowledge() function because

   196 	 * server (EAP-authenticator) sends the EAP-success message.

   197 	 */

   198 	EAP_FUNC_IMPORT eap_status_e eap_acknowledge(

   199 		const eap_am_network_id_c * const receive_network_id); 

   200 

   201 	/**

   202 	 * This function restarts authentication using current object.

   203 	 * This is used for testing.

   204 	 */

   205 	EAP_FUNC_IMPORT eap_status_e restart_authentication(

   206 		const eap_am_network_id_c * const send_network_id,

   207 		const bool is_client_when_true);

   208 

   209 #if defined(USE_EAP_CORE_SERVER)

   210 	/**

   211 	 * The EAP Core calls the send_eap_identity_request() function

   212 	 * when EAP-authentication is needed with another peer.

   213 	 * @param network_id includes the addresses (network identity) and packet type.

   214 	 */

   215 	EAP_FUNC_IMPORT eap_status_e send_eap_identity_request(

   216 		const eap_am_network_id_c * const network_id);

   217 #endif //#if defined(USE_EAP_CORE_SERVER)

   218 

   219 	/**

   220 	 * The EAP Core calls the send_eap_nak_response() function

   221 	 * when EAP-authentication with requested EAP type is not possible.

   222 	 * @param network_id includes the addresses (network identity) and packet type.

   223 	 * @param eap_identifier is the EAP-Identifier to be used with EAP-Nak message.

   224 	 * @param preferred_eap_type is the acceptable EAP-Type to be informed with an other peer.

   225 	 */

   226 	EAP_FUNC_IMPORT eap_status_e send_eap_nak_response(

   227 		const eap_am_network_id_c * const receive_network_id,

   228 		const u8_t eap_identifier,

   229 		const eap_type_value_e preferred_eap_type);

   230 

   231 	/**

   232 	 * Note this function is just an example. Parameters will change later.

   233 	 * The packet_data_crypto_keys() function gives the generated keys to lower level.

   234 	 * After EAP-authentication has generated the keys it calls this function

   235 	 * to offer the keys to lower level.

   236 	 * @param authentication_key is pointer to the first byte of the authentication key.

   237 	 * @param auth_key_length is count of bytes in the authentication key.

   238 	 * @param encryption_key is pointer to the first byte of the encryption key.

   239 	 * @param encr_key_length is count of bytes in the encryption key.

   240 	 */

   241 	EAP_FUNC_IMPORT eap_status_e packet_data_crypto_keys(

   242 		const eap_am_network_id_c * const send_network_id,

   243 		const eap_master_session_key_c * const master_session_key

   244 		);

   245 

   246 	// This is documented in abs_eap_stack_interface_c::configure().

   247 	EAP_FUNC_IMPORT eap_status_e configure();

   248 

   249 	// This is documented in abs_eap_stack_interface_c::shutdown().

   250 	EAP_FUNC_IMPORT eap_status_e shutdown();

   251 

   252 	/**

   253 	 * The read_configure() function reads the configuration data identified

   254 	 * by the field string of field_length bytes length. Adaptation module must direct

   255 	 * the query to some persistent store.

   256 	 * @param field is generic configure string idenfying the required configure data.

   257 	 * @param field_length is length of the field string.

   258 	 * @param data is pointer to existing eap_variable_data object.

   259 	 */

   260 	EAP_FUNC_IMPORT virtual eap_status_e read_configure(

   261 		const eap_configuration_field_c * const field,

   262 		eap_variable_data_c * const data);

   263 

   264 	/**

   265 	 * The write_configure() function writes the configuration data identified

   266 	 * by the field string of field_length bytes length. Adaptation module must direct

   267 	 * the action to some persistent store.

   268 	 * @param field is generic configure string idenfying the required configure data.

   269 	 * @param field_length is length of the field string.

   270 	 * @param data is pointer to existing eap_variable_data object.

   271 	 */

   272 	EAP_FUNC_IMPORT virtual eap_status_e write_configure(

   273 		const eap_configuration_field_c * const field,

   274 		eap_variable_data_c * const data);

   275 

   276 	// This is documented in abs_eap_stack_interface_c::set_is_valid().

   277 	EAP_FUNC_IMPORT void set_is_valid();

   278 

   279 	// This is documented in abs_eap_stack_interface_c::get_is_valid().

   280 	EAP_FUNC_IMPORT bool get_is_valid();

   281 

   282 	// See abs_eap_base_type_c::state_notification().

   283 	EAP_FUNC_IMPORT void state_notification(

   284 		const abs_eap_state_notification_c * const state);

   285 

   286 	// See abs_eap_base_timer_c::timer_expired().

   287 	EAP_FUNC_IMPORT eap_status_e timer_expired(

   288 		const u32_t id, void *data);

   289 

   290 	// See abs_eap_base_timer_c::timer_delete_data().

   291 	EAP_FUNC_IMPORT eap_status_e timer_delete_data(

   292 		const u32_t id, void *data);

   293 

   294 	/**

   295 	 * The load_module() function function indicates the lower level to

   296 	 * load new module of EAP-type.

   297 	 * @see abs_eap_core_c::load_module().

   298 	 */

   299 	EAP_FUNC_IMPORT eap_status_e load_module(

   300 		const eap_type_value_e type,

   301 		const eap_type_value_e /* tunneling_type */,

   302 		abs_eap_base_type_c * const partner,

   303 		eap_base_type_c ** const eap_type,

   304 		const bool is_client_when_true,

   305 		const eap_am_network_id_c * const receive_network_id);

   306 

   307 	/**

   308 	 * The adaptation module calls the restart_authentication() function

   309 	 * when EAP-authentication is needed with another peer.

   310 	 * @see abs_eap_core_c::restart_authentication().

   311 	 */

   312 	EAP_FUNC_IMPORT eap_status_e restart_authentication(

   313 		const eap_am_network_id_c * const receive_network_id,

   314 		const bool is_client_when_true,

   315 		const bool force_clean_restart,

   316 		const bool from_timer = false);

   317 

   318 #if defined(USE_EAPOL_KEY_STATE_OPTIMIZED_4_WAY_HANDSHAKE)

   319 	/**

   320 	 * This function creates EAP session object synchronously.

   321 	 * @param receive_network_id identifies the removed EAP session.

   322 	 */

   323 	EAP_FUNC_IMPORT eap_status_e synchronous_create_eap_session(

   324 		const eap_am_network_id_c * const receive_network_id);

   325 #endif //#if defined(USE_EAPOL_KEY_STATE_OPTIMIZED_4_WAY_HANDSHAKE)

   326 

   327 	/**

   328 	 * This function removes EAP session object synchronously.

   329 	 * @param receive_network_id identifies the removed EAP session.

   330 	 */

   331 	EAP_FUNC_IMPORT eap_status_e synchronous_remove_eap_session(

   332 		const eap_am_network_id_c * const receive_network_id);

   333 

   334 	/**

   335 	 * This function removes EAP session object asynchronously.

   336 	 * @param send_network_id identifies the removed EAP session.

   337 	 */

   338 	eap_status_e asynchronous_init_remove_eap_session(

   339 		const eap_am_network_id_c * const send_network_id);

   340 

   341 	/**

   342 	 * This function tells lower layer to remove EAP session object asynchronously.

   343 	 * @param eap_type is pointer to selector that identifies the removed EAP session.

   344 	 */

   345 	EAP_FUNC_IMPORT eap_status_e asynchronous_init_remove_eap_session(

   346 		const eap_network_id_selector_c * const state_selector);

   347 

   348 	//

   349 	EAP_FUNC_IMPORT eap_status_e set_timer(

   350 		abs_eap_base_timer_c * const p_initializer, 

   351 		const u32_t p_id, 

   352 		void * const p_data,

   353 		const u32_t p_time_ms);

   354 

   355 	EAP_FUNC_IMPORT eap_status_e cancel_timer(

   356 		abs_eap_base_timer_c * const p_initializer, 

   357 		const u32_t p_id);

   358 

   359 	//

   360 	EAP_FUNC_IMPORT eap_status_e cancel_all_timers();

   361 

   362 	//

   363 	EAP_FUNC_IMPORT eap_status_e check_is_valid_eap_type(const eap_type_value_e eap_type);

   364 

   365 	/// @see abs_eap_core_c::get_eap_type_list().

   366 	EAP_FUNC_IMPORT eap_status_e get_eap_type_list(

   367 		eap_array_c<eap_type_value_e> * const eap_type_list);

   368 

   369 	/// @see abs_eap_core_c::add_rogue_ap().

   370 	EAP_FUNC_IMPORT eap_status_e add_rogue_ap(eap_array_c<eap_rogue_ap_entry_c> & rogue_ap_list);

   371 

   372 	// This is documented in abs_eap_core_c::set_session_timeout().

   373 	EAP_FUNC_IMPORT eap_status_e set_session_timeout(

   374 		const u32_t session_timeout_ms);

   375 

   376 	//--------------------------------------------------

   377 }; // class eap_session_core_c

   378 

   379 #endif //#if !defined(_EAP_SESSION_CORE_H_)

   380 

   381 //--------------------------------------------------

   382 

   383 

   384 

   385 // End.