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

    22 #define _EAP_AM_TYPE_GSMSIM_H_

    23 

    24 #include "eap_tools.h"

    25 #include "eap_variable_data.h"

    26 #include "eap_am_export.h"

    27 #include "abs_eap_am_type_gsmsim.h"

    28 #include "eap_sim_triplets.h"

    29 #include "eap_am_network_id.h"

    30 #include "eap_type_gsmsim_types.h"

    31 

    32 

    33 /// This class is interface to adaptation module of GSMSIM.

    34 class EAP_EXPORT eap_am_type_gsmsim_c

    35 {

    36 private:

    37 	//--------------------------------------------------

    38 

    39 	abs_eap_am_type_gsmsim_c *m_am_partner;

    40 	abs_eap_am_tools_c *m_am_tools;

    41 

    42 	bool m_is_valid;

    43 

    44 	//--------------------------------------------------

    45 protected:

    46 	//--------------------------------------------------

    47 

    48 	//--------------------------------------------------

    49 public:

    50 	//--------------------------------------------------

    51 

    52 	// 

    53 	virtual ~eap_am_type_gsmsim_c()

    54 	{

    55 		EAP_TRACE_BEGIN(m_am_tools, TRACE_FLAGS_DEFAULT);

    56 		EAP_TRACE_END(m_am_tools, TRACE_FLAGS_DEFAULT);

    57 	}

    58 

    59 	// 

    60 	eap_am_type_gsmsim_c(abs_eap_am_tools_c * const tools /*, abs_eap_am_type_gsmsim_c * const partner */)

    61 	: m_am_partner(0)

    62 	, m_am_tools(tools)

    63 	, m_is_valid(false)

    64 	{

    65 		EAP_TRACE_BEGIN(m_am_tools, TRACE_FLAGS_DEFAULT);

    66 		set_is_valid();

    67 		EAP_TRACE_END(m_am_tools, TRACE_FLAGS_DEFAULT);

    68 	}

    69 

    70 	/** Function returns partner object of adaptation module of GSMSIM.

    71 	 *  Partner object is the GSMSIM object.

    72 	 */

    73 	abs_eap_am_type_gsmsim_c * const get_am_partner()

    74 	{

    75 		EAP_TRACE_BEGIN(m_am_tools, TRACE_FLAGS_DEFAULT);

    76 		EAP_TRACE_END(m_am_tools, TRACE_FLAGS_DEFAULT);

    77 		return m_am_partner;

    78 	}

    79 

    80 	/** Function sets partner object of adaptation module of GSMSIM.

    81 	 *  Partner object is the GSMSIM object.

    82 	 */

    83 	void set_am_partner(abs_eap_am_type_gsmsim_c * const partner)

    84 	{

    85 		EAP_TRACE_BEGIN(m_am_tools, TRACE_FLAGS_DEFAULT);

    86 		EAP_TRACE_END(m_am_tools, TRACE_FLAGS_DEFAULT);

    87 		m_am_partner = partner;

    88 	}

    89 

    90 	void set_is_valid()

    91 	{

    92 		m_is_valid = true;

    93 	}

    94 

    95 	bool get_is_valid()

    96 	{

    97 		return m_is_valid;

    98 	}

    99 

   100 	virtual eap_status_e configure() = 0;

   101 

   102 	virtual eap_status_e reset() = 0;

   103 

   104 	/**

   105 	 * The shutdown() function is called before the destructor of the 

   106 	 * object is executed. During the function call the object 

   107 	 * could shutdown the operations, for example cancel timers.

   108 	 * Each derived class must define this function.

   109 	 */

   110 	virtual eap_status_e shutdown() = 0;

   111 

   112 	/** GSMSIM client calls this function.

   113 	 *  GSMSIM AM could store copy of pseudonym identity to favourite place for future use.

   114 	 *  If parameter pseudonym is NULL pointer, AM should reset the existing pseudonym.

   115 	 */

   116 	virtual eap_status_e store_pseudonym_id(

   117 		const eap_am_network_id_c * const send_network_id,

   118 		const eap_variable_data_c * const pseudonym) = 0;

   119 

   120 	/** GSMSIM client calls this function.

   121 	 *  GSMSIM AM could store copy of reauthentication identity to favourite place for future use.

   122 	 *  If parameter reauthentication_identity is NULL pointer, AM should reset the existing reauthentication identity.

   123 	 */

   124 	virtual eap_status_e store_reauthentication_id(

   125 		const eap_am_network_id_c * const send_network_id,

   126 		const eap_variable_data_c * const reauthentication_identity) = 0;

   127 

   128 	/** GSMSIM server and client calls this function.

   129 	 * In order to use re-authentication, the client and the server need to

   130 	 * store the following values: original XKEY, K_aut, K_encr, latest

   131 	 * counter value and the next re-authentication identity.

   132 	 * This function stores original XKEY, K_aut and K_encr.

   133 	 */

   134 	virtual eap_status_e store_reauth_parameters(

   135 		const eap_variable_data_c * const XKEY,

   136 		const eap_variable_data_c * const K_aut,

   137 		const eap_variable_data_c * const K_encr,

   138 		const u32_t reauth_counter) = 0;

   139 

   140 	/** GSMSIM client calls this function.

   141 	 *  GSMSIM AM could do finishing operations to databases etc. based on authentication status and type.

   142 	 */

   143 	virtual eap_status_e authentication_finished(

   144 		const bool true_when_successfull,

   145 		const eap_gsmsim_authentication_type_e authentication_type,

   146 		const eap_type_gsmsim_identity_type identity_type) = 0;

   147 

   148 	/** GSMSIM server and client calls this function.

   149 	 * In order to use re-authentication, the client and the server need to

   150 	 * store the following values: original XKEY, K_aut, K_encr, latest

   151 	 * counter value and the next re-authentication identity.

   152 	 */

   153 	virtual eap_status_e query_reauth_parameters(

   154 		eap_variable_data_c * const XKEY,

   155 		eap_variable_data_c * const K_aut,

   156 		eap_variable_data_c * const K_encr,

   157 		u32_t * const reauth_counter) = 0;

   158 

   159 	/** GSMSIM server and client calls this function.

   160 	 *  This function increases re-authentication counter after a successfull re-authentication.

   161 	 */

   162 	virtual eap_status_e increase_reauth_counter() = 0;

   163 

   164 	/** GSMSIM client calls this function.

   165 	 *  AM could copy IMSI or pseudonym to output parameters if must_be_synchronous parameter is false.

   166 	 *  AM must copy IMSI or pseudonym to output parameters if must_be_synchronous parameter is true.

   167 	 *  This function could be completed asyncronously with abs_eap_am_type_gsmsim_c::complete_SIM_IMSI_or_pseudonym_or_reauthentication_id_query() function call.

   168 	 */

   169 	virtual eap_status_e query_SIM_IMSI_or_pseudonym_or_reauthentication_id(

   170 		const bool must_be_synchronous,

   171 		eap_variable_data_c * const IMSI,

   172 		eap_variable_data_c * const pseudonym_identity,

   173 		eap_variable_data_c * const reauthentication_identity,

   174 		eap_variable_data_c * const automatic_realm, ///< If this is not used, do not add any data to this parameter.

   175 		u32_t * const length_of_mnc,

   176 		const gsmsim_payload_AT_type_e required_identity, ///< This parameter indicated the type of identity required.

   177 		const eap_type_gsmsim_complete_e required_completion, ///< This parameter tells the required completion after this call is completed, if this is asyncronous. Use this value with abs_eap_am_type_gsmsim_c::complete_SIM_IMSI_or_pseudonym_or_reauthentication_id_query() function call.

   178 		const u8_t received_eap_identifier ///< This is the EAP-identifier of the received EAP-request message. Use this value with abs_eap_am_type_gsmsim_c::complete_SIM_IMSI_or_pseudonym_or_reauthentication_id_query() function call.

   179 		) = 0;

   180 

   181 	/** GSMSIM client calls this function.

   182 	 *  This call cancels asyncronous query_SIM_IMSI_or_pseudonym_or_reauthentication_id() function call.

   183 	 *  AM must not complete query_SIM_IMSI_or_pseudonym_or_reauthentication_id()

   184 	 *  with abs_eap_am_type_gsmsim_c::complete_SIM_IMSI_or_pseudonym_or_reauthentication_id_query() after

   185 	 *  cancel_SIM_IMSI_or_pseudonym_or_reauthentication_id_query() call.

   186 	 */

   187 	virtual eap_status_e cancel_SIM_IMSI_or_pseudonym_or_reauthentication_id_query() = 0;

   188 

   189 

   190 	/** GSMSIM client calls this function.

   191 	 *  Input parameter n_rands includes n RANDs as input to SIM algorithm.

   192 	 *  AM could copy n_kc or n_sres to output parameters.

   193 	 *  This function could be completed asyncronously with abs_eap_am_type_gsmsim_c::complete_SIM_kc_sres() function call.

   194 	 */

   195 	virtual eap_status_e query_SIM_kc_sres(

   196 		const bool must_be_synchronous,

   197 		const eap_variable_data_c * const n_rands,

   198 		eap_variable_data_c * const n_kc,

   199 		eap_variable_data_c * const n_sres) = 0;

   200 

   201 	/** GSMSIM client calls this function.

   202 	 *  This call cancels asyncronous query_SIM_kc_sres() function call.

   203 	 *  AM must not complete query_SIM_kc_sres()

   204 	 *  with abs_eap_am_type_gsmsim_c::complete_SIM_kc_sres() after

   205 	 *  cancel_SIM_kc_sres_query() call.

   206 	 */

   207 	virtual eap_status_e cancel_SIM_kc_sres_query() = 0;

   208 

   209 

   210 	/** GSMSIM client calls this function.

   211 	 *  Received AT_NOTIFICATION is handled in AM of GSMSIM.

   212 	 *  AM could show localized message to user.

   213 	 */

   214 	virtual eap_status_e handle_gsmsim_notification(eap_gsmsim_notification_codes_e gsmsim_notification_code) = 0;

   215 

   216 

   217 #if defined(USE_EAP_TYPE_SERVER_GSMSIM)

   218 	/** GSMSIM server calls this function.

   219 	 *  AM could copy triplets to output parameters.

   220 	 *  This function could be completed asyncronously with abs_eap_am_type_gsmsim_c::complete_SIM_triplets() function call.

   221 	 */

   222 	virtual eap_status_e query_SIM_triplets(

   223 		const bool must_be_synchronous,

   224 		const eap_variable_data_c * const username, ///< // This is payload AT_IDENTITY. If this is uninitialized then imsi must be initialized.

   225 		eap_variable_data_c * const imsi, ///< This is the real IMSI. If this is uninitialized then username must be initialized and imsi will be initialized after this call.

   226 		eap_type_sim_triplet_array_c * const triplets,

   227 		eap_type_gsmsim_identity_type * const type) = 0;

   228 #endif //#if defined(USE_EAP_TYPE_SERVER_GSMSIM)

   229 

   230 

   231 #if defined(USE_EAP_TYPE_SERVER_GSMSIM)

   232 	/** GSMSIM server calls this function.

   233 	 *  This call cancels asyncronous query_SIM_triplets() function call.

   234 	 *  AM must not complete query_SIM_triplets() with abs_eap_am_type_gsmsim_c::complete_SIM_triplets() after

   235 	 *  cancel_SIM_triplets_query() call.

   236 	 */

   237 	virtual eap_status_e cancel_SIM_triplets_query() = 0;

   238 #endif //#if defined(USE_EAP_TYPE_SERVER_GSMSIM)

   239 

   240 	/** GSMSIM server calls this function.

   241 	 *  This function call generates with a good source of

   242 	 *  randomness the initialization vector (AT_IV payload).

   243 	 */

   244 	virtual eap_status_e generate_encryption_IV(

   245 		eap_variable_data_c * const encryption_IV,

   246 		const u32_t IV_length) = 0;

   247 

   248 	/** GSMSIM server calls this function.

   249 	 *  New pseudonym identity is generated for IMSI.

   250 	 *  Algorithm is freely selected. Look at query_imsi_from_username().

   251 	 *  Pseudonym identity is copied to pseudonym_identity parameter.

   252 	 *  Maximum length of pseudonym is maximum_pseudonym_length bytes.

   253 	 */

   254 	virtual eap_status_e generate_pseudonym_id(

   255 		const eap_am_network_id_c * const send_network_id,

   256 		const eap_variable_data_c * const imsi,

   257 		eap_variable_data_c * const pseudonym_identity,

   258 		const u32_t maximum_pseudonym_length) = 0;

   259 

   260 	/** GSMSIM server calls this function.

   261 	 *  New reauthentication identity is generated for IMSI.

   262 	 *  Algorithm is freely selected. Look at query_imsi_from_username().

   263 	 *  Reauthentication identity is copied to pseudonym parameter.

   264 	 *  Maximum length of pseudonym is maximum_reauthentication_identity_length bytes.

   265 	 */

   266 	virtual eap_status_e generate_reauthentication_id(

   267 		const eap_am_network_id_c * const send_network_id,

   268 		const eap_variable_data_c * const imsi,

   269 		eap_variable_data_c * const reauthentication_identity,

   270 		const u32_t maximum_reauthentication_identity_length) = 0;

   271 

   272 

   273 #if defined(USE_EAP_TYPE_SERVER_GSMSIM)

   274 	/** GSMSIM server calls this function.

   275 	 *  Server queries IMSI with username.

   276 	 *  Username could be IMSI, pseudonym or re-authentication identity.

   277 	 *  Adaptation module must verify which username is.

   278 	 *  Adaptation module could map IMSI and username as it wish.

   279 	 *  It can select any algorithm. Look at generate_pseudonym_id() and generate_reauthentication_id().

   280 	 *  Function must return IMSI and set the identity type of received username.

   281 	 */

   282 	virtual eap_status_e query_imsi_from_username(

   283 		const bool must_be_synchronous,

   284 		const u8_t next_eap_identifier,

   285 		const eap_am_network_id_c * const send_network_id,

   286 		const eap_variable_data_c * const username,

   287 		eap_variable_data_c * const imsi,

   288 		eap_type_gsmsim_identity_type * const type,

   289 		const eap_type_gsmsim_complete_e completion_action) = 0;

   290 #endif //#if defined(USE_EAP_TYPE_SERVER_GSMSIM)

   291 

   292 

   293 	/** GSMSIM server calls this function.

   294 	 *  This call cancels asyncronous query_imsi_from_username() function call.

   295 	 *  AM must not complete query_imsi_from_username()

   296 	 *  with abs_eap_am_type_gsmsim_c::complete_imsi_from_username() after

   297 	 *  cancel_imsi_from_username_query() call.

   298 	 */

   299 	virtual eap_status_e cancel_imsi_from_username_query() = 0;

   300 

   301 	/** GSMSIM client calls this function.

   302 	 *  This call could check whether the RANDs are already used.

   303 	 *  For example Bloom algorithm couls be used.

   304 	 *  Function must return eap_status_ok when RAND is not used before.

   305 	 */

   306 	virtual eap_status_e check_is_rand_unused(const eap_variable_data_c * const n_rands) = 0;

   307 

   308 	/** GSMSIM client calls this function.

   309 	 *  This call could set the RANDs used.

   310 	 *  For example Bloom algorithm couls be used.

   311 	 *  Function must return eap_status_ok when operation is successfull.

   312 	 */

   313 	virtual eap_status_e set_rand_is_used(const eap_variable_data_c * const n_rands) = 0;

   314 

   315 	/**

   316 	 * The type_configure_read() function reads the configuration data identified

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

   318 	 * the query to some persistent store.

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

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

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

   322 	 */

   323 	virtual eap_status_e type_configure_read(

   324 		const eap_configuration_field_c * const field,

   325 		eap_variable_data_c * const data) = 0;

   326 

   327 	/**

   328 	 * The type_configure_write() function writes the configuration data identified

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

   330 	 * the action to some persistent store.

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

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

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

   334 	 */

   335 	virtual eap_status_e type_configure_write(

   336 		const eap_configuration_field_c * const field,

   337 		eap_variable_data_c * const data) = 0;

   338 

   339 	//--------------------------------------------------

   340 }; // class eap_am_type_gsmsim_c

   341 

   342 

   343 /** @file */ 

   344 

   345 /**

   346  * This function creates a new instance of adaptation module of GSMSIM EAP-type.

   347  * @param tools is pointer to the abs_eap_am_tools class created by the adaptation module.

   348  * GSMSIM EAP-type will callback caller using the partner pointer.

   349  */

   350 EAP_C_FUNC_IMPORT  eap_am_type_gsmsim_c *new_eap_am_type_gsmsim(

   351 	abs_eap_am_tools_c * const tools,

   352 	abs_eap_base_type_c * const partner,

   353 	const bool is_client_when_true,

   354 	const eap_am_network_id_c * const receive_network_id);

   355 

   356 

   357 #endif //#if !defined(_EAP_AM_TYPE_GSMSIM_H_)

   358 

   359 //--------------------------------------------------

   360 

   361 

   362 

   363 // End.