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
Defines
#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_SIM_DB_FAILURE   -1
#define	EAP_SIM_DB_PENDING   -2
Functions
void *	eap_sim_db_init (const char *config, void(*get_complete_cb)(void *ctx, void *session_ctx), void *ctx)
	Initialize EAP-SIM DB / authentication gateway interface.
void	eap_sim_db_deinit (void *priv)
	Deinitialize EAP-SIM DB/authentication gw interface.
int	eap_sim_db_get_gsm_triplets (void *priv, const u8 *identity, size_t identity_len, int max_chal, u8 *_rand, u8 *kc, u8 *sres, void *cb_session_ctx)
	Get GSM triplets.
int	eap_sim_db_identity_known (void *priv, const u8 *identity, size_t identity_len)
	Verify whether the given identity is known.
char *	eap_sim_db_get_next_pseudonym (void *priv, int aka)
	EAP-SIM DB: Get next pseudonym.
char *	eap_sim_db_get_next_reauth_id (void *priv, int aka)
	EAP-SIM DB: Get next reauth_id.
int	eap_sim_db_add_pseudonym (void *priv, const u8 *identity, size_t identity_len, char *pseudonym)
	EAP-SIM DB: Add new pseudonym.
int	eap_sim_db_add_reauth (void *priv, const u8 *identity, size_t identity_len, char *reauth_id, u16 counter, const u8 *mk)
	EAP-SIM DB: Add new re-authentication entry.
int	eap_sim_db_add_reauth_prime (void *priv, const u8 *identity, size_t identity_len, char *reauth_id, u16 counter, const u8 *k_encr, const u8 *k_aut, const u8 *k_re)
const u8 *	eap_sim_db_get_permanent (void *priv, const u8 *identity, size_t identity_len, size_t *len)
	EAP-SIM DB: Get permanent identity.
struct eap_sim_reauth *	eap_sim_db_get_reauth_entry (void *priv, const u8 *identity, size_t identity_len)
	EAP-SIM DB: Get re-authentication entry.
void	eap_sim_db_remove_reauth (void *priv, struct eap_sim_reauth *reauth)
	EAP-SIM DB: Remove re-authentication entry.
int	eap_sim_db_get_aka_auth (void *priv, const u8 *identity, size_t identity_len, u8 *_rand, u8 *autn, u8 *ik, u8 *ck, u8 *res, size_t *res_len, void *cb_session_ctx)
	Get AKA authentication values.
int	eap_sim_db_resynchronize (void *priv, const u8 *identity, size_t identity_len, const u8 *auts, const u8 *_rand)
	Resynchronize AKA AUTN.

---

Detailed Description

hostapd / EAP-SIM database/authenticator gateway

Copyright

Copyright (c) 2005-2007, Jouni Malinen <j@w1.fi>

This software may be distributed under the terms of the BSD license. See README for more details.

---

Function Documentation

int eap_sim_db_add_pseudonym	(	void *	priv,
		const u8 *	identity,
		size_t	identity_len,
		char *	pseudonym
	)

EAP-SIM DB: Add new pseudonym.

Parameters:

priv	Private data pointer from eap_sim_db_init()
identity	Identity of the user (may be permanent identity or pseudonym)
identity_len	Length of identity
pseudonym	Pseudonym 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	(	void *	priv,
		const u8 *	identity,
		size_t	identity_len,
		char *	reauth_id,
		u16	counter,
		const u8 *	mk
	)

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

Parameters:

priv	Private data pointer from eap_sim_db_init()
identity	Identity of the user (may be permanent identity or pseudonym)
identity_len	Length of identity
reauth_id	reauth_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.
counter	AT_COUNTER value for fast re-authentication
mk	16-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:

priv	Private data pointer from eap_sim_db_init()

int eap_sim_db_get_aka_auth	(	void *	priv,
		const u8 *	identity,
		size_t	identity_len,
		u8 *	_rand,
		u8 *	autn,
		u8 *	ik,
		u8 *	ck,
		u8 *	res,
		size_t *	res_len,
		void *	cb_session_ctx
	)

Get AKA authentication values.

Parameters:

priv	Private data pointer from eap_sim_db_init()
identity	User name identity
identity_len	Length of identity in bytes
_rand	Buffer for RAND value
autn	Buffer for AUTN value
ik	Buffer for IK value
ck	Buffer for CK value
res	Buffer for RES value
res_len	Buffer for RES length
cb_session_ctx	Session 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.

In most cases, the user name is '0' | IMSI, i.e., 0 followed by the IMSI in ASCII format.

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	(	void *	priv,
		const u8 *	identity,
		size_t	identity_len,
		int	max_chal,
		u8 *	_rand,
		u8 *	kc,
		u8 *	sres,
		void *	cb_session_ctx
	)

Get GSM triplets.

Parameters:

priv	Private data pointer from eap_sim_db_init()
identity	User name identity
identity_len	Length of identity in bytes
max_chal	Maximum number of triplets
_rand	Buffer for RAND values
kc	Buffer for Kc values
sres	Buffer for SRES values
cb_session_ctx	Session 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.

In most cases, the user name is '1' | IMSI, i.e., 1 followed by the IMSI in ASCII format.

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	(	void *	priv,
		int	aka
	)

EAP-SIM DB: Get next pseudonym.

Parameters:

priv	Private data pointer from eap_sim_db_init()
aka	Using EAP-AKA instead of EAP-SIM

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	(	void *	priv,
		int	aka
	)

EAP-SIM DB: Get next reauth_id.

Parameters:

priv	Private data pointer from eap_sim_db_init()
aka	Using EAP-AKA instead of EAP-SIM

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 u8* eap_sim_db_get_permanent	(	void *	priv,
		const u8 *	identity,
		size_t	identity_len,
		size_t *	len
	)

EAP-SIM DB: Get permanent identity.

Parameters:

priv	Private data pointer from eap_sim_db_init()
identity	Identity of the user (may be permanent identity or pseudonym)
identity_len	Length of identity
len	Buffer for length of the returned permanent identity

Returns:

Pointer to the permanent identity, or NULL if not found

struct eap_sim_reauth* eap_sim_db_get_reauth_entry	(	void *	priv,
		const u8 *	identity,
		size_t	identity_len
	)		[read]

EAP-SIM DB: Get re-authentication entry.

Parameters:

priv	Private data pointer from eap_sim_db_init()
identity	Identity of the user (may be permanent identity, pseudonym, or reauth_id)
identity_len	Length of identity

Returns:

Pointer to the re-auth entry, or NULL if not found

int eap_sim_db_identity_known	(	void *	priv,
		const u8 *	identity,
		size_t	identity_len
	)

Verify whether the given identity is known.

Parameters:

priv	Private data pointer from eap_sim_db_init()
identity	User name identity
identity_len	Length of identity in bytes

Returns:

0 if the user is found or -1 on failure

In most cases, the user name is ['0','1'] | IMSI, i.e., 1 followed by the IMSI in ASCII format, ['2','3'] | pseudonym, or ['4','5'] | reauth_id.

void* 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:

config	Configuration data (e.g., file name)
get_complete_cb	Callback function for reporting availability of triplets
ctx	Context pointer for get_complete_cb

Returns:

Pointer to a private data structure or NULL on failure

void eap_sim_db_remove_reauth	(	void *	priv,
		struct eap_sim_reauth *	reauth
	)

EAP-SIM DB: Remove re-authentication entry.

Parameters:

priv	Private data pointer from eap_sim_db_init()
reauth	Pointer to re-authentication entry from eap_sim_db_get_reauth_entry()

int eap_sim_db_resynchronize	(	void *	priv,
		const u8 *	identity,
		size_t	identity_len,
		const u8 *	auts,
		const u8 *	_rand
	)

Resynchronize AKA AUTN.

Parameters:

priv	Private data pointer from eap_sim_db_init()
identity	User name identity
identity_len	Length of identity in bytes
auts	AUTS value from the peer
_rand	RAND 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.