STUN Authentication

STUN authentication helper. More...

Data Structures
struct	pj_stun_auth_cred
struct	pj_stun_req_cred_info

Enumerations
enum	pj_stun_auth_type {   PJ_STUN_AUTH_NONE = 0 ,   PJ_STUN_AUTH_SHORT_TERM = 1 ,   PJ_STUN_AUTH_LONG_TERM = 2 }
enum	pj_stun_auth_cred_type {   PJ_STUN_AUTH_CRED_STATIC ,   PJ_STUN_AUTH_CRED_DYNAMIC }
enum	pj_stun_passwd_type {   PJ_STUN_PASSWD_PLAIN = 0 ,   PJ_STUN_PASSWD_HASHED = 1 }

Functions
void	pj_stun_auth_cred_dup (pj_pool_t *pool, pj_stun_auth_cred *dst, const pj_stun_auth_cred *src)
void	pj_stun_req_cred_info_dup (pj_pool_t *pool, pj_stun_req_cred_info *dst, const pj_stun_req_cred_info *src)
void	pj_stun_create_key (pj_pool_t *pool, pj_str_t *key, const pj_str_t *realm, const pj_str_t *username, pj_stun_passwd_type data_type, const pj_str_t *data)
pj_status_t	pj_stun_authenticate_request (const pj_uint8_t *pkt, unsigned pkt_len, const pj_stun_msg *msg, pj_stun_auth_cred *cred, pj_pool_t *pool, pj_stun_req_cred_info *info, pj_stun_msg **p_response)
pj_bool_t	pj_stun_auth_valid_for_msg (const pj_stun_msg *msg)
pj_status_t	pj_stun_authenticate_response (const pj_uint8_t *pkt, unsigned pkt_len, const pj_stun_msg *msg, const pj_str_t *key)

Detailed Description

Enumeration Type Documentation

pj_stun_auth_cred_type

enum pj_stun_auth_cred_type

Type of authentication data in the credential.

Enumerator
PJ_STUN_AUTH_CRED_STATIC	The credential data contains a static credential to be matched against the credential in the message. A static credential can be used as both client side or server side authentication.
PJ_STUN_AUTH_CRED_DYNAMIC	The credential data contains callbacks to be called to verify the credential in the message. A dynamic credential is suitable when performing server side authentication where server does not know in advance the identity of the user requesting authentication.

pj_stun_auth_type

enum pj_stun_auth_type

Type of authentication.

Enumerator
PJ_STUN_AUTH_NONE	No authentication.
PJ_STUN_AUTH_SHORT_TERM	Authentication using short term credential.
PJ_STUN_AUTH_LONG_TERM	Authentication using long term credential.

pj_stun_passwd_type

enum pj_stun_passwd_type

Type of encoding applied to the password stored in the credential.

Enumerator
PJ_STUN_PASSWD_PLAIN	Plain text password.
PJ_STUN_PASSWD_HASHED	Hashed password, valid for long term credential only. The hash value of the password is calculated as MD5(USERNAME ":" REALM ":" PASSWD) with all quotes removed from the username and realm values.

Function Documentation

pj_stun_auth_cred_dup()

void pj_stun_auth_cred_dup	(	pj_pool_t *	pool,
		pj_stun_auth_cred *	dst,
		const pj_stun_auth_cred *	src
	)

Duplicate authentication credential.

Parameters

pool	Pool to be used to allocate memory.
dst	Destination credential.
src	Source credential.

pj_stun_auth_valid_for_msg()

pj_bool_t pj_stun_auth_valid_for_msg

(

const pj_stun_msg *

msg

)

Determine if STUN message can be authenticated. Some STUN error responses cannot be authenticated since they cannot contain STUN MESSAGE-INTEGRITY attribute. STUN Indication messages also cannot be authenticated.

Parameters

msg	The STUN message.

Returns

Non-zero if the STUN message can be authenticated.

pj_stun_authenticate_request()

pj_status_t pj_stun_authenticate_request	(	const pj_uint8_t *	pkt,
		unsigned	pkt_len,
		const pj_stun_msg *	msg,
		pj_stun_auth_cred *	cred,
		pj_pool_t *	pool,
		pj_stun_req_cred_info *	info,
		pj_stun_msg **	p_response
	)

Verify credential in the STUN request. Note that before calling this function, application must have checked that the message contains PJ_STUN_ATTR_MESSAGE_INTEGRITY attribute by calling pj_stun_msg_find_attr() function, because this function will reject the message with 401 error if it doesn't contain PJ_STUN_ATTR_MESSAGE_INTEGRITY attribute.

Parameters

pkt	The original packet which has been parsed into the message. This packet MUST NOT have been modified after the parsing.
pkt_len	The length of the packet.
msg	The parsed message to be verified.
cred	Pointer to credential to be used to authenticate the message.
pool	If response is to be created, then memory will be allocated from this pool.
info	Optional pointer to receive authentication information found in the request and the credential that is used to authenticate the request.
p_response	Optional pointer to receive the response message then the credential in the request fails to authenticate.

Returns

PJ_SUCCESS if credential is verified successfully. If the verification fails and p_response is not NULL, an appropriate response will be returned in p_response.

pj_stun_authenticate_response()

pj_status_t pj_stun_authenticate_response	(	const pj_uint8_t *	pkt,
		unsigned	pkt_len,
		const pj_stun_msg *	msg,
		const pj_str_t *	key
	)

Verify credential in the STUN response. Note that before calling this function, application must have checked that the message contains PJ_STUN_ATTR_MESSAGE_INTEGRITY attribute by calling pj_stun_msg_find_attr() function, because otherwise this function will report authentication failure.

Parameters

pkt	The original packet which has been parsed into the message. This packet MUST NOT have been modified after the parsing.
pkt_len	The length of the packet.
msg	The parsed message to be verified.
key	Authentication key to calculate MESSAGE-INTEGRITY value. Application can create this key by using pj_stun_create_key() function.

Returns

PJ_SUCCESS if credential is verified successfully.

References PJ_END_DECL.

pj_stun_create_key()

void pj_stun_create_key	(	pj_pool_t *	pool,
		pj_str_t *	key,
		const pj_str_t *	realm,
		const pj_str_t *	username,
		pj_stun_passwd_type	data_type,
		const pj_str_t *	data
	)

Create authentication key to be used for encoding the message with MESSAGE-INTEGRITY. If short term credential is used (i.e. the realm argument is NULL or empty), the key will be copied from the password. If long term credential is used, the key will be calculated from the MD5 hash of the realm, username, and password.

Parameters

pool	Pool to allocate memory for the key.
key	String to receive the key.
realm	The realm of the credential, if long term credential is to be used. If short term credential is wanted, application can put NULL or empty string here.
username	The username.
data_type	Password encoding.
data	The password.

pj_stun_req_cred_info_dup()

void pj_stun_req_cred_info_dup	(	pj_pool_t *	pool,
		pj_stun_req_cred_info *	dst,
		const pj_stun_req_cred_info *	src
	)

Duplicate request credential.

Parameters

pool	Pool to be used to allocate memory.
dst	Destination credential.
src	Source credential.