BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJNATH Reference

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_dataThe user data as specified in the credential.
poolPool to allocate memory.
realmOn 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.
nonceOn 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
msgThe outgoing message where the credential is to be applied.
user_dataThe user data as specified in the credential.
poolPool where the callback can allocate memory to fill in the credential.
realmOn return, the callback may specify the realm if long term credential is desired, otherwise this string must be set to empty.
usernameOn return, the callback must fill in with the username.
nonceOn return, the callback may optionally fill in this argument with NONCE value if desired, otherwise this argument must be set to empty.
data_typeOn return, the callback must set this argument with the type of password in the data argument.
dataOn 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
msgThe STUN message where the password will be applied to.
user_dataThe user data as specified in the credential.
realmThe realm as specified in the message.
usernameThe username as specified in the message.
poolPool to allocate memory when necessary.
data_typeOn return, application should fill up this argument with the type of data (which should be zero if data is a plaintext password).
dataOn 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
msgThe STUN message where the nonce was received.
user_dataThe user data as specified in the credential.
realmThe realm as specified in the message.
usernameThe username as specified in the message.
nonceThe 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:

 


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