BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJNATH Reference

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

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.

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

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

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.

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.

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.

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

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

The type of authentication information in this structure.

User data which will be passed back to callback functions.

The username of the credential.

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:

 


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