wpa_supplicant / hostapd  2.5
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Data Structures | Macros | Enumerations | Functions
eap_sim_db.h File Reference

hostapd / EAP-SIM database/authenticator gateway More...

#include "eap_common/eap_sim_common.h"

Go to the source code of this file.

Data Structures

struct  eap_sim_reauth
 

Macros

#define EAP_SIM_PERMANENT_PREFIX   '1'
 
#define EAP_SIM_PSEUDONYM_PREFIX   '3'
 
#define EAP_SIM_REAUTH_ID_PREFIX   '5'
 
#define EAP_AKA_PERMANENT_PREFIX   '0'
 
#define EAP_AKA_PSEUDONYM_PREFIX   '2'
 
#define EAP_AKA_REAUTH_ID_PREFIX   '4'
 
#define EAP_AKA_PRIME_PERMANENT_PREFIX   '6'
 
#define EAP_AKA_PRIME_PSEUDONYM_PREFIX   '7'
 
#define EAP_AKA_PRIME_REAUTH_ID_PREFIX   '8'
 
#define EAP_SIM_DB_FAILURE   -1
 
#define EAP_SIM_DB_PENDING   -2
 

Enumerations

enum  eap_sim_db_method { EAP_SIM_DB_SIM, EAP_SIM_DB_AKA, EAP_SIM_DB_AKA_PRIME }
 

Functions

struct eap_sim_db_dataeap_sim_db_init (const char *config, void(*get_complete_cb)(void *ctx, void *session_ctx), void *ctx)
 Initialize EAP-SIM DB / authentication gateway interface. More...
 
void eap_sim_db_deinit (void *priv)
 Deinitialize EAP-SIM DB/authentication gw interface. More...
 
int eap_sim_db_get_gsm_triplets (struct eap_sim_db_data *data, const char *username, int max_chal, u8 *_rand, u8 *kc, u8 *sres, void *cb_session_ctx)
 Get GSM triplets. More...
 
char * eap_sim_db_get_next_pseudonym (struct eap_sim_db_data *data, enum eap_sim_db_method method)
 EAP-SIM DB: Get next pseudonym. More...
 
char * eap_sim_db_get_next_reauth_id (struct eap_sim_db_data *data, enum eap_sim_db_method method)
 EAP-SIM DB: Get next reauth_id. More...
 
int eap_sim_db_add_pseudonym (struct eap_sim_db_data *data, const char *permanent, char *pseudonym)
 EAP-SIM DB: Add new pseudonym. More...
 
int eap_sim_db_add_reauth (struct eap_sim_db_data *data, const char *permanent, char *reauth_id, u16 counter, const u8 *mk)
 EAP-SIM DB: Add new re-authentication entry. More...
 
int eap_sim_db_add_reauth_prime (struct eap_sim_db_data *data, const char *permanent, char *reauth_id, u16 counter, const u8 *k_encr, const u8 *k_aut, const u8 *k_re)
 
const char * eap_sim_db_get_permanent (struct eap_sim_db_data *data, const char *pseudonym)
 EAP-SIM DB: Get permanent identity. More...
 
struct eap_sim_reautheap_sim_db_get_reauth_entry (struct eap_sim_db_data *data, const char *reauth_id)
 EAP-SIM DB: Get re-authentication entry. More...
 
void eap_sim_db_remove_reauth (struct eap_sim_db_data *data, struct eap_sim_reauth *reauth)
 EAP-SIM DB: Remove re-authentication entry. More...
 
int eap_sim_db_get_aka_auth (struct eap_sim_db_data *data, const char *username, u8 *_rand, u8 *autn, u8 *ik, u8 *ck, u8 *res, size_t *res_len, void *cb_session_ctx)
 Get AKA authentication values. More...
 
int eap_sim_db_resynchronize (struct eap_sim_db_data *data, const char *username, const u8 *auts, const u8 *_rand)
 Resynchronize AKA AUTN. More...
 
char * sim_get_username (const u8 *identity, size_t identity_len)
 Extract username from SIM identity. More...
 

Detailed Description

hostapd / EAP-SIM database/authenticator gateway

Function Documentation

int eap_sim_db_add_pseudonym ( struct eap_sim_db_data data,
const char *  permanent,
char *  pseudonym 
)

EAP-SIM DB: Add new pseudonym.

Parameters
dataPrivate data pointer from eap_sim_db_init()
permanentPermanent username
pseudonymPseudonym for this user. This needs to be an allocated buffer, e.g., return value from eap_sim_db_get_next_pseudonym(). Caller must not free it.
Returns
0 on success, -1 on failure

This function adds a new pseudonym for EAP-SIM user. EAP-SIM DB is responsible of freeing pseudonym buffer once it is not needed anymore.

int eap_sim_db_add_reauth ( struct eap_sim_db_data data,
const char *  permanent,
char *  reauth_id,
u16  counter,
const u8 *  mk 
)

EAP-SIM DB: Add new re-authentication entry.

Parameters
privPrivate data pointer from eap_sim_db_init()
permanentPermanent username
identity_lenLength of identity
reauth_idreauth_id for this user. This needs to be an allocated buffer, e.g., return value from eap_sim_db_get_next_reauth_id(). Caller must not free it.
counterAT_COUNTER value for fast re-authentication
mk16-byte MK from the previous full authentication or NULL
Returns
0 on success, -1 on failure

This function adds a new re-authentication entry for an EAP-SIM user. EAP-SIM DB is responsible of freeing reauth_id buffer once it is not needed anymore.

void eap_sim_db_deinit ( void *  priv)

Deinitialize EAP-SIM DB/authentication gw interface.

Parameters
privPrivate data pointer from eap_sim_db_init()
int eap_sim_db_get_aka_auth ( struct eap_sim_db_data data,
const char *  username,
u8 *  _rand,
u8 *  autn,
u8 *  ik,
u8 *  ck,
u8 *  res,
size_t *  res_len,
void *  cb_session_ctx 
)

Get AKA authentication values.

Parameters
dataPrivate data pointer from eap_sim_db_init()
usernamePermanent username (prefix | IMSI)
_randBuffer for RAND value
autnBuffer for AUTN value
ikBuffer for IK value
ckBuffer for CK value
resBuffer for RES value
res_lenBuffer for RES length
cb_session_ctxSession callback context for get_complete_cb()
Returns
0 on success, -1 (EAP_SIM_DB_FAILURE) on error (e.g., user not found), or -2 (EAP_SIM_DB_PENDING) if results are not yet available. In this case, the callback function registered with eap_sim_db_init() will be called once the results become available.

When using an external server for AKA authentication, this function can always start a request and return EAP_SIM_DB_PENDING immediately if authentication triplets are not available. Once the authentication data are received, callback function registered with eap_sim_db_init() is called to notify EAP state machine to reprocess the message. This eap_sim_db_get_aka_auth() function will then be called again and the newly received triplets will then be given to the caller.

int eap_sim_db_get_gsm_triplets ( struct eap_sim_db_data data,
const char *  username,
int  max_chal,
u8 *  _rand,
u8 *  kc,
u8 *  sres,
void *  cb_session_ctx 
)

Get GSM triplets.

Parameters
dataPrivate data pointer from eap_sim_db_init()
usernamePermanent username (prefix | IMSI)
max_chalMaximum number of triplets
_randBuffer for RAND values
kcBuffer for Kc values
sresBuffer for SRES values
cb_session_ctxSession callback context for get_complete_cb()
Returns
Number of triplets received (has to be less than or equal to max_chal), -1 (EAP_SIM_DB_FAILURE) on error (e.g., user not found), or -2 (EAP_SIM_DB_PENDING) if results are not yet available. In this case, the callback function registered with eap_sim_db_init() will be called once the results become available.

When using an external server for GSM triplets, this function can always start a request and return EAP_SIM_DB_PENDING immediately if authentication triplets are not available. Once the triplets are received, callback function registered with eap_sim_db_init() is called to notify EAP state machine to reprocess the message. This eap_sim_db_get_gsm_triplets() function will then be called again and the newly received triplets will then be given to the caller.

char* eap_sim_db_get_next_pseudonym ( struct eap_sim_db_data data,
enum eap_sim_db_method  method 
)

EAP-SIM DB: Get next pseudonym.

Parameters
dataPrivate data pointer from eap_sim_db_init()
methodEAP method (SIM/AKA/AKA')
Returns
Next pseudonym (allocated string) or NULL on failure

This function is used to generate a pseudonym for EAP-SIM. The returned pseudonym is not added to database at this point; it will need to be added with eap_sim_db_add_pseudonym() once the authentication has been completed successfully. Caller is responsible for freeing the returned buffer.

char* eap_sim_db_get_next_reauth_id ( struct eap_sim_db_data data,
enum eap_sim_db_method  method 
)

EAP-SIM DB: Get next reauth_id.

Parameters
dataPrivate data pointer from eap_sim_db_init()
methodEAP method (SIM/AKA/AKA')
Returns
Next reauth_id (allocated string) or NULL on failure

This function is used to generate a fast re-authentication identity for EAP-SIM. The returned reauth_id is not added to database at this point; it will need to be added with eap_sim_db_add_reauth() once the authentication has been completed successfully. Caller is responsible for freeing the returned buffer.

const char* eap_sim_db_get_permanent ( struct eap_sim_db_data data,
const char *  pseudonym 
)

EAP-SIM DB: Get permanent identity.

Parameters
dataPrivate data pointer from eap_sim_db_init()
pseudonymPseudonym username
Returns
Pointer to permanent username or NULL if not found
struct eap_sim_reauth* eap_sim_db_get_reauth_entry ( struct eap_sim_db_data data,
const char *  reauth_id 
)

EAP-SIM DB: Get re-authentication entry.

Parameters
dataPrivate data pointer from eap_sim_db_init()
reauth_idFast re-authentication username
Returns
Pointer to the re-auth entry, or NULL if not found
struct eap_sim_db_data* eap_sim_db_init ( const char *  config,
void(*)(void *ctx, void *session_ctx)  get_complete_cb,
void *  ctx 
)

Initialize EAP-SIM DB / authentication gateway interface.

Parameters
configConfiguration data (e.g., file name)
get_complete_cbCallback function for reporting availability of triplets
ctxContext pointer for get_complete_cb
Returns
Pointer to a private data structure or NULL on failure
void eap_sim_db_remove_reauth ( struct eap_sim_db_data data,
struct eap_sim_reauth reauth 
)

EAP-SIM DB: Remove re-authentication entry.

Parameters
dataPrivate data pointer from eap_sim_db_init()
reauthPointer to re-authentication entry from eap_sim_db_get_reauth_entry()
int eap_sim_db_resynchronize ( struct eap_sim_db_data data,
const char *  username,
const u8 *  auts,
const u8 *  _rand 
)

Resynchronize AKA AUTN.

Parameters
dataPrivate data pointer from eap_sim_db_init()
usernamePermanent username
autsAUTS value from the peer
_randRAND value used in the rejected message
Returns
0 on success, -1 on failure

This function is called when the peer reports synchronization failure in the AUTN value by sending AUTS. The AUTS and RAND values should be sent to HLR/AuC to allow it to resynchronize with the peer. After this, eap_sim_db_get_aka_auth() will be called again to to fetch updated RAND/AUTN values for the next challenge.

char* sim_get_username ( const u8 *  identity,
size_t  identity_len 
)

Extract username from SIM identity.

Parameters
identityIdentity
identity_lenIdentity length
Returns
Allocated buffer with the username part of the identity

Caller is responsible for freeing the returned buffer with os_free().