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.

Public Members

pj_stun_auth_cred_type type

The type of authentication information in this structure.

pj_str_t realm

If not-empty, it indicates that this is a long term credential.

pj_str_t username

The username of the credential.

pj_stun_passwd_type data_type

Data type to indicate the type of password in the data field.

pj_str_t data

The data, which depends depends on the value of data_type field. When data_type is zero, this field will contain the plaintext password.

pj_str_t nonce

Optional NONCE.

struct pj_stun_auth_cred::[anonymous]::[anonymous] static_cred

This structure contains static data for performing authentication. A non-empty realm indicates whether short term or long term credential is used.

void *user_data

User data which will be passed back to callback functions.

pj_status_t (*get_auth)(void *user_data, pj_pool_t *pool, pj_str_t *realm, pj_str_t *nonce)

This callback is called by pj_stun_verify_credential() when server needs to challenge the request with 401 response.

Param user_data:

The user data as specified in the credential.

Param pool:

Pool to allocate memory.

Param realm:

On return, the function should fill in with realm if application wants to use long term credential. Otherwise application should set empty string for the realm.

Param nonce:

On return, if application wants to use long term credential, it MUST fill in the nonce with some value. Otherwise if short term credential is wanted, it MAY set this value. If short term credential is wanted and the application doesn’t want to include NONCE, then it must set this to empty string.

Return:

The callback should return PJ_SUCCESS, or otherwise response message will not be created.

pj_status_t (*get_cred)(const pj_stun_msg *msg, void *user_data, pj_pool_t *pool, pj_str_t *realm, pj_str_t *username, pj_str_t *nonce, pj_stun_passwd_type *data_type, pj_str_t *data)

Get the credential to be put in outgoing request.

Param msg:

The outgoing message where the credential is to be applied.

Param user_data:

The user data as specified in the credential.

Param pool:

Pool where the callback can allocate memory to fill in the credential.

Param realm:

On return, the callback may specify the realm if long term credential is desired, otherwise this string must be set to empty.

Param username:

On return, the callback must fill in with the username.

Param nonce:

On return, the callback may optionally fill in this argument with NONCE value if desired, otherwise this argument must be set to empty.

Param data_type:

On return, the callback must set this argument with the type of password in the data argument.

Param data:

On return, the callback must set this with the password, encoded according to data_type argument.

Return:

The callback must return PJ_SUCCESS, otherwise the message transmission will be cancelled.

pj_status_t (*get_password)(const pj_stun_msg *msg, void *user_data, const pj_str_t *realm, const pj_str_t *username, pj_pool_t *pool, pj_stun_passwd_type *data_type, pj_str_t *data)

Get the password for the specified username. This function is also used to check whether the username is valid.

Param msg:

The STUN message where the password will be applied to.

Param user_data:

The user data as specified in the credential.

Param realm:

The realm as specified in the message.

Param username:

The username as specified in the message.

Param pool:

Pool to allocate memory when necessary.

Param data_type:

On return, application should fill up this argument with the type of data (which should be zero if data is a plaintext password).

Param data:

On return, application should fill up this argument with the password according to data_type.

Return:

The callback should return PJ_SUCCESS if username has been successfully verified and password was obtained. If non-PJ_SUCCESS is returned, it is assumed that the username is not valid.

pj_bool_t (*verify_nonce)(const pj_stun_msg *msg, void *user_data, const pj_str_t *realm, const pj_str_t *username, const pj_str_t *nonce)

This callback will be called to verify that the NONCE given in the message can be accepted. If this callback returns PJ_FALSE, 438 (Stale Nonce) response will be created.

This callback is optional.

Param msg:

The STUN message where the nonce was received.

Param user_data:

The user data as specified in the credential.

Param realm:

The realm as specified in the message.

Param username:

The username as specified in the message.

Param nonce:

The nonce to be verified.

Return:

The callback MUST return non-zero if the NONCE can be accepted.

struct pj_stun_auth_cred::[anonymous]::[anonymous] dyn_cred

This structure contains callback to be called by the framework to authenticate the incoming message.

union pj_stun_auth_cred::[anonymous] data

This union contains the authentication data.

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.

Public Members

pj_str_t realm

The REALM value found in the incoming request. If short term credential is used, the value will be empty.

pj_str_t username

The USERNAME value found in the incoming request.

pj_str_t nonce

Optional NONCE.

pj_str_t auth_key

Authentication key that was used to authenticate the incoming request. This key is created with pj_stun_create_key(), and it can be used to encode the credential of the outgoing response.