Group PJNATH_STUN_AUTH¶

group PJNATH_STUN_AUTH

STUN authentication helper.

Enums

enum pj_stun_auth_type¶

Type of authentication.

Values:

enumerator PJ_STUN_AUTH_NONE¶: No authentication.

enumerator PJ_STUN_AUTH_SHORT_TERM¶: Authentication using short term credential.

enumerator PJ_STUN_AUTH_LONG_TERM¶: Authentication using long term credential.

enum pj_stun_auth_cred_type¶

Type of authentication data in the credential.

Values:

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.

enumerator 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.

enum pj_stun_passwd_type¶

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

Values:

enumerator PJ_STUN_PASSWD_PLAIN¶: Plain text password.

enumerator 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.

Functions

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.

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.

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_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_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_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.

struct pj_stun_auth_cred¶: #include <stun_auth.h>
This structure contains the descriptions needed to perform server side authentication. Depending on the type set in the structure, application may specify a static username/password combination, or to have callbacks called by the function to authenticate the credential dynamically.

struct pj_stun_req_cred_info¶: #include <stun_auth.h>
This structure contains the credential information that is found and used to authenticate incoming requests. Application may use this information when generating authentication for the outgoing response.