pj_stun_auth_cred Struct Reference [STUN Authentication]

Data Fields
pj_stun_auth_cred_type	type
union {
struct {
pj_str_t   realm
pj_str_t   username
pj_stun_passwd_type   data_type
pj_str_t   data
pj_str_t   nonce
}   static_cred
struct {
void *   user_data
pj_status_t(*   get_auth )(void *user_data, pj_pool_t *pool, pj_str_t *realm, pj_str_t *nonce)
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)
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)
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)
}   dyn_cred
}	data

---

Detailed Description

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.

---

Field Documentation

pj_str_t pj_stun_auth_cred::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.

union { ... } pj_stun_auth_cred::data

This union contains the authentication data.

pj_stun_passwd_type pj_stun_auth_cred::data_type

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

struct { ... } pj_stun_auth_cred::dyn_cred

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

pj_status_t(* pj_stun_auth_cred::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.

Parameters:

	user_data	The user data as specified in the credential.
	pool	Pool to allocate memory.
	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.
	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.

Returns:

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

pj_status_t(* pj_stun_auth_cred::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.

Parameters:

	msg	The outgoing message where the credential is to be applied.
	user_data	The user data as specified in the credential.
	pool	Pool where the callback can allocate memory to fill in the credential.
	realm	On return, the callback may specify the realm if long term credential is desired, otherwise this string must be set to empty.
	username	On return, the callback must fill in with the username.
	nonce	On return, the callback may optionally fill in this argument with NONCE value if desired, otherwise this argument must be set to empty.
	data_type	On return, the callback must set this argument with the type of password in the data argument.
	data	On return, the callback must set this with the password, encoded according to data_type argument.

Returns:

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

pj_status_t(* pj_stun_auth_cred::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.

Parameters:

	msg	The STUN message where the password will be applied to.
	user_data	The user data as specified in the credential.
	realm	The realm as specified in the message.
	username	The username as specified in the message.
	pool	Pool to allocate memory when necessary.
	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).
	data	On return, application should fill up this argument with the password according to data_type.

Returns:

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_str_t pj_stun_auth_cred::nonce

Optional NONCE.

pj_str_t pj_stun_auth_cred::realm

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

struct { ... } pj_stun_auth_cred::static_cred

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

pj_stun_auth_cred_type pj_stun_auth_cred::type

The type of authentication information in this structure.

void* pj_stun_auth_cred::user_data

User data which will be passed back to callback functions.

pj_str_t pj_stun_auth_cred::username

The username of the credential.

pj_bool_t(* pj_stun_auth_cred::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.

Parameters:

	msg	The STUN message where the nonce was received.
	user_data	The user data as specified in the credential.
	realm	The realm as specified in the message.
	username	The username as specified in the message.
	nonce	The nonce to be verified.

Returns:

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

---

The documentation for this struct was generated from the following file:

• stun_auth.h