BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJNATH Reference

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

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.

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.

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

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
poolPool to be used to allocate memory.
dstDestination credential.
srcSource credential.
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
msgThe STUN message.
Returns
Non-zero if the STUN message can be authenticated.
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
pktThe original packet which has been parsed into the message. This packet MUST NOT have been modified after the parsing.
pkt_lenThe length of the packet.
msgThe parsed message to be verified.
credPointer to credential to be used to authenticate the message.
poolIf response is to be created, then memory will be allocated from this pool.
infoOptional pointer to receive authentication information found in the request and the credential that is used to authenticate the request.
p_responseOptional 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_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
pktThe original packet which has been parsed into the message. This packet MUST NOT have been modified after the parsing.
pkt_lenThe length of the packet.
msgThe parsed message to be verified.
keyAuthentication 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.
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
poolPool to allocate memory for the key.
keyString to receive the key.
realmThe 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.
usernameThe username.
data_typePassword encoding.
dataThe password.
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
poolPool to be used to allocate memory.
dstDestination credential.
srcSource credential.

 


PJNATH - Open Source NAT traversal helper library supporting STUN, TURN, and ICE
Copyright (C) 2006-2009 Teluu Inc.