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_RADIUS_SESSION_H_)

    22 #define _EAP_RADIUS_SESSION_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 #include "eap_core.h"

    30 #include "eap_radius_payloads.h"

    31 #include "abs_eap_radius_session.h"

    32 #include "eap_protocol_layer.h"

    33 #include "eap_master_session_key.h"

    34 

    35 

    36 class eap_core_c;

    37 class eap_network_id_selector_c;

    38 

    39 

    40 /**

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

    42  */

    43 enum eap_radius_session_timer_id

    44 {

    45 	EAP_RADIUS_SESSION_REMOVE_SESSION_ID, ///< See EAP_RADIUS_SESSION_REMOVE_SESSION_TIMEOUT.

    46 };

    47 

    48 /**

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

    50  */

    51 const u32_t EAP_RADIUS_SESSION_REMOVE_SESSION_TIMEOUT = 0u;

    52 

    53 

    54 /// A eap_radius_session_c class implements mapping of EAP authentication sessions.

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

    56 class EAP_EXPORT eap_radius_session_c

    57 : public abs_eap_core_c

    58 , public abs_eap_core_map_c

    59 , public abs_eap_base_timer_c

    60 , public abs_eap_stack_interface_c

    61 {

    62 private:

    63 	//--------------------------------------------------

    64 

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

    66 	/// Packets are sent to the partner.

    67 	abs_eap_radius_session_c * const m_partner;

    68 

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

    70 	abs_eap_am_tools_c * const m_am_tools;

    71 

    72 	/// This is EAP core for this session.

    73 	eap_core_c * m_eap_core;

    74 

    75 	/// m_master_session_key includes also EAP-type.

    76 	/// Note the LEAP type uses different key than other EAP-types.

    77 	eap_master_session_key_c m_master_session_key;

    78 

    79 	eap_variable_data_c m_request_authenticator;

    80 

    81 	eap_variable_data_c m_shared_secret;

    82 

    83 	u8_t m_identifier;

    84 

    85 	eap_radius_variable_data_c * m_user_name;

    86 

    87 	eap_radius_variable_data_c * m_nas_ip_address;

    88 

    89 	eap_state_variable_e m_state;

    90 

    91 	u32_t m_remove_session_timeout;

    92 

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

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

    95 	bool m_is_client;

    96 

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

    98 	bool m_is_valid;

    99 

   100 	bool m_shutdown_was_called;

   101 

   102 

   103 	/**

   104 	 * Function creates a new session.

   105 	 */

   106 	EAP_FUNC_IMPORT eap_core_c * create_new_session(

   107 		const eap_am_network_id_c * const receive_network_id);

   108 

   109 	EAP_FUNC_IMPORT static eap_status_e shutdown_operation(

   110 		eap_core_c * const core,

   111 		abs_eap_am_tools_c * const m_am_tools);

   112 

   113 	EAP_FUNC_IMPORT eap_status_e reset();

   114 

   115 	//--------------------------------------------------

   116 protected:

   117 	//--------------------------------------------------

   118 

   119 	//--------------------------------------------------

   120 public:

   121 	//--------------------------------------------------

   122 

   123 	/**

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

   125 	 */

   126 	EAP_FUNC_IMPORT virtual ~eap_radius_session_c();

   127 

   128 	/**

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

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

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

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

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

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

   135 	 */

   136 	EAP_FUNC_IMPORT eap_radius_session_c(

   137 		abs_eap_am_tools_c * const tools,

   138 		abs_eap_radius_session_c * const partner,

   139 		const bool is_client_when_true,

   140 		const eap_radius_variable_data_c * const user_name,

   141 		const eap_radius_variable_data_c * const nas_ip_address);

   142 

   143 	EAP_FUNC_IMPORT eap_status_e save_request_data(

   144 		const void * const data,

   145 		const u32_t data_length,

   146 		const u8_t identifier);

   147 

   148 	EAP_FUNC_IMPORT u8_t get_identifier();

   149 

   150 	EAP_FUNC_IMPORT const eap_variable_data_c * get_shared_secret() const;

   151 

   152 	EAP_FUNC_IMPORT const eap_variable_data_c * get_request_authenticator();

   153 

   154 	EAP_FUNC_IMPORT const eap_radius_variable_data_c * get_user_name();

   155 

   156 	EAP_FUNC_IMPORT eap_state_variable_e get_state();

   157 

   158 	EAP_FUNC_IMPORT eap_variable_data_c * get_master_session_key();

   159 

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

   161 	EAP_FUNC_IMPORT eap_status_e packet_process(

   162 		const eap_am_network_id_c * const receive_network_id,

   163 		eap_general_header_base_c * const packet_data,

   164 		const u32_t packet_length); 

   165 

   166 	/**

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

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

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

   170 	 * EAP-packet in correct offset.

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

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

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

   174 	 */

   175 	EAP_FUNC_IMPORT eap_status_e packet_send(

   176 		const eap_am_network_id_c * const send_network_id,

   177 		eap_buf_chain_wr_c * const sent_packet,

   178 		const u32_t header_offset,

   179 		const u32_t data_length,

   180 		const u32_t buffer_length); 

   181 

   182 	EAP_FUNC_IMPORT void object_increase_reference_count();

   183 

   184 	EAP_FUNC_IMPORT u32_t object_decrease_reference_count();

   185 

   186 	/**

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

   188 	 */

   189 	EAP_FUNC_IMPORT abs_eap_radius_session_c * get_partner();

   190 

   191 	/**

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

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

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

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

   196 	 * of trailer needed by lower levels.

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

   198 	 * @see abs_eap_base_type_c::get_header_offset().

   199 	 */

   200 	EAP_FUNC_IMPORT u32_t get_header_offset(

   201 		u32_t * const MTU,

   202 		u32_t * const trailer_length);

   203 

   204 	/**

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

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

   207 	 */

   208 	EAP_FUNC_IMPORT eap_status_e unload_module(

   209 		const eap_type_value_e type); 

   210 

   211 	/**

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

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

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

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

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

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

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

   219 	 */

   220 	EAP_FUNC_IMPORT eap_status_e eap_acknowledge(

   221 		const eap_am_network_id_c * const receive_network_id); 

   222 

   223 	/**

   224 	 * This function restarts authentication using current object.

   225 	 * This is used for testing.

   226 	 */

   227 	EAP_FUNC_IMPORT eap_status_e restart_authentication(

   228 		const eap_am_network_id_c * const send_network_id,

   229 		const bool is_client_when_true);

   230 

   231 #if defined(USE_EAP_CORE_SERVER)

   232 	/**

   233 	 * The EAP Core calls the send_eap_identity_request() function

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

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

   236 	 */

   237 	EAP_FUNC_IMPORT eap_status_e send_eap_identity_request(

   238 		const eap_am_network_id_c * const network_id);

   239 #endif //#if defined(USE_EAP_CORE_SERVER)

   240 

   241 	/**

   242 	 * The EAP Core calls the send_eap_nak_response() function

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

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

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

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

   247 	 */

   248 	EAP_FUNC_IMPORT eap_status_e send_eap_nak_response(

   249 		const eap_am_network_id_c * const receive_network_id,

   250 		const u8_t eap_identifier,

   251 		const eap_type_value_e preferred_eap_type);

   252 

   253 	/**

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

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

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

   257 	 * to offer the keys to lower level.

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

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

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

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

   262 	 */

   263 	EAP_FUNC_IMPORT eap_status_e packet_data_crypto_keys(

   264 		const eap_am_network_id_c * const send_network_id,

   265 		const eap_master_session_key_c * const master_session_key

   266 		);

   267 

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

   269 	EAP_FUNC_IMPORT eap_status_e configure();

   270 

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

   272 	EAP_FUNC_IMPORT eap_status_e shutdown();

   273 

   274 	/**

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

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

   277 	 * the query to some persistent store.

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

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

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

   281 	 */

   282 	EAP_FUNC_IMPORT virtual eap_status_e read_configure(

   283 		const eap_configuration_field_c * const field,

   284 		eap_variable_data_c * const data);

   285 

   286 	/**

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

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

   289 	 * the action to some persistent store.

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

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

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

   293 	 */

   294 	EAP_FUNC_IMPORT virtual eap_status_e write_configure(

   295 		const eap_configuration_field_c * const field,

   296 		eap_variable_data_c * const data);

   297 

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

   299 	EAP_FUNC_IMPORT void set_is_valid();

   300 

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

   302 	EAP_FUNC_IMPORT bool get_is_valid();

   303 

   304 	// See abs_eap_base_type_c::state_notification().

   305 	EAP_FUNC_IMPORT void state_notification(

   306 		const abs_eap_state_notification_c * const state);

   307 

   308 	// See abs_eap_base_timer_c::timer_expired().

   309 	EAP_FUNC_IMPORT eap_status_e timer_expired(

   310 		const u32_t id, void *data);

   311 

   312 	// See abs_eap_base_timer_c::timer_delete_data().

   313 	EAP_FUNC_IMPORT eap_status_e timer_delete_data(

   314 		const u32_t id, void *data);

   315 

   316 	/**

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

   318 	 * load new module of EAP-type.

   319 	 * @see abs_eap_core_c::load_module().

   320 	 */

   321 	EAP_FUNC_IMPORT eap_status_e load_module(

   322 		const eap_type_value_e type,

   323 		const eap_type_value_e /* tunneling_type */,

   324 		abs_eap_base_type_c * const partner,

   325 		eap_base_type_c ** const eap_type,

   326 		const bool is_client_when_true,

   327 		const eap_am_network_id_c * const receive_network_id);

   328 

   329 	/**

   330 	 * The adaptation module calls the restart_authentication() function

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

   332 	 * @see abs_eap_core_c::restart_authentication().

   333 	 */

   334 	EAP_FUNC_IMPORT eap_status_e restart_authentication(

   335 		const eap_am_network_id_c * const receive_network_id,

   336 		const bool is_client_when_true,

   337 		const bool force_clean_restart,

   338 		const bool from_timer = false);

   339 

   340 	/**

   341 	 * This function removes EAP session object synchronously.

   342 	 * @param receive_network_id identifies the removed EAP session.

   343 	 */

   344 	EAP_FUNC_IMPORT eap_status_e synchronous_remove_eap_session(

   345 		const eap_am_network_id_c * const receive_network_id);

   346 

   347 	/**

   348 	 * This function removes EAP session object asynchronously.

   349 	 * @param send_network_id identifies the removed EAP session.

   350 	 */

   351 	eap_status_e asynchronous_init_remove_eap_session(

   352 		const eap_am_network_id_c * const send_network_id);

   353 

   354 	/**

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

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

   357 	 */

   358 	EAP_FUNC_IMPORT eap_status_e asynchronous_init_remove_eap_session(

   359 		const eap_network_id_selector_c * const state_selector);

   360 

   361 	//

   362 	EAP_FUNC_IMPORT eap_status_e set_timer(

   363 		abs_eap_base_timer_c * const p_initializer, 

   364 		const u32_t p_id, 

   365 		void * const p_data,

   366 		const u32_t p_time_ms);

   367 

   368 	EAP_FUNC_IMPORT eap_status_e cancel_timer(

   369 		abs_eap_base_timer_c * const p_initializer, 

   370 		const u32_t p_id);

   371 

   372 	//

   373 	EAP_FUNC_IMPORT eap_status_e cancel_all_timers();

   374 

   375 	//

   376 	EAP_FUNC_IMPORT eap_status_e check_is_valid_eap_type(const eap_type_value_e eap_type);

   377 

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

   379 	EAP_FUNC_IMPORT eap_status_e get_eap_type_list(

   380 		eap_array_c<eap_type_value_e> * const eap_type_list);

   381 

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

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

   384 

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

   386 	EAP_FUNC_IMPORT eap_status_e set_session_timeout(

   387 		const u32_t session_timeout_ms);

   388 

   389 	//--------------------------------------------------

   390 }; // class eap_radius_session_c

   391 

   392 #endif //#if !defined(_EAP_RADIUS_SESSION_H_)

   393 

   394 //--------------------------------------------------

   395 

   396 

   397 

   398 // End.