BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJSIP Reference

Structures and functions to perform authentication. More...

Modules

 Digest AKAv1 and AKAv2 Authentication API
 Digest AKAv1 and AKAv2 Authentication API.
 

Data Structures

struct  pjsip_cred_info
 
struct  pjsip_cached_auth_hdr
 
struct  pjsip_cached_auth
 
struct  pjsip_auth_clt_pref
 
struct  pjsip_auth_clt_sess
 
struct  pjsip_auth_lookup_cred_param
 
struct  pjsip_auth_srv
 
struct  pjsip_auth_srv_init_param
 

Macros

#define PJSIP_MD5STRLEN   32
 
#define PJSIP_AUTH_SRV_IS_PROXY   1
 

Typedefs

typedef pj_status_t(* pjsip_cred_cb) (pj_pool_t *pool, const pjsip_digest_challenge *chal, const pjsip_cred_info *cred, const pj_str_t *method, pjsip_digest_credential *auth)
 
typedef pj_status_t pjsip_auth_lookup_cred(pj_pool_t *pool, const pj_str_t *realm, const pj_str_t *acc_name, pjsip_cred_info *cred_info)
 
typedef pj_status_t pjsip_auth_lookup_cred2(pj_pool_t *pool, const pjsip_auth_lookup_cred_param *param, pjsip_cred_info *cred_info)
 

Enumerations

enum  pjsip_cred_data_type { PJSIP_CRED_DATA_PLAIN_PASSWD =0, PJSIP_CRED_DATA_DIGEST =1, PJSIP_CRED_DATA_EXT_AKA =16 }
 
enum  pjsip_auth_qop_type { PJSIP_AUTH_QOP_NONE, PJSIP_AUTH_QOP_AUTH, PJSIP_AUTH_QOP_AUTH_INT, PJSIP_AUTH_QOP_UNKNOWN }
 

Functions

void pjsip_auth_clt_pref_dup (pj_pool_t *pool, pjsip_auth_clt_pref *dst, const pjsip_auth_clt_pref *src)
 
void pjsip_cred_info_dup (pj_pool_t *pool, pjsip_cred_info *dst, const pjsip_cred_info *src)
 
int pjsip_cred_info_cmp (const pjsip_cred_info *cred1, const pjsip_cred_info *cred2)
 
pj_status_t pjsip_auth_clt_init (pjsip_auth_clt_sess *sess, pjsip_endpoint *endpt, pj_pool_t *pool, unsigned options)
 
pj_status_t pjsip_auth_clt_deinit (pjsip_auth_clt_sess *sess)
 
pj_status_t pjsip_auth_clt_clone (pj_pool_t *pool, pjsip_auth_clt_sess *sess, const pjsip_auth_clt_sess *rhs)
 
pj_status_t pjsip_auth_clt_set_credentials (pjsip_auth_clt_sess *sess, int cred_cnt, const pjsip_cred_info *c)
 
pj_status_t pjsip_auth_clt_set_prefs (pjsip_auth_clt_sess *sess, const pjsip_auth_clt_pref *p)
 
pj_status_t pjsip_auth_clt_get_prefs (pjsip_auth_clt_sess *sess, pjsip_auth_clt_pref *p)
 
pj_status_t pjsip_auth_clt_init_req (pjsip_auth_clt_sess *sess, pjsip_tx_data *tdata)
 
pj_status_t pjsip_auth_clt_reinit_req (pjsip_auth_clt_sess *sess, const pjsip_rx_data *rdata, pjsip_tx_data *old_request, pjsip_tx_data **new_request)
 
pj_status_t pjsip_auth_srv_init (pj_pool_t *pool, pjsip_auth_srv *auth_srv, const pj_str_t *realm, pjsip_auth_lookup_cred *lookup, unsigned options)
 
pj_status_t pjsip_auth_srv_init2 (pj_pool_t *pool, pjsip_auth_srv *auth_srv, const pjsip_auth_srv_init_param *param)
 
pj_status_t pjsip_auth_srv_verify (pjsip_auth_srv *auth_srv, pjsip_rx_data *rdata, int *status_code)
 
pj_status_t pjsip_auth_srv_challenge (pjsip_auth_srv *auth_srv, const pj_str_t *qop, const pj_str_t *nonce, const pj_str_t *opaque, pj_bool_t stale, pjsip_tx_data *tdata)
 
void pjsip_auth_create_digest (pj_str_t *result, const pj_str_t *nonce, const pj_str_t *nc, const pj_str_t *cnonce, const pj_str_t *qop, const pj_str_t *uri, const pj_str_t *realm, const pjsip_cred_info *cred_info, const pj_str_t *method)
 

Detailed Description

Macro Definition Documentation

◆ PJSIP_MD5STRLEN

#define PJSIP_MD5STRLEN   32

Length of digest string.

◆ PJSIP_AUTH_SRV_IS_PROXY

#define PJSIP_AUTH_SRV_IS_PROXY   1

Flag to specify that server is a proxy.

Typedef Documentation

◆ pjsip_cred_cb

typedef pj_status_t(* pjsip_cred_cb) (pj_pool_t *pool, const pjsip_digest_challenge *chal, const pjsip_cred_info *cred, const pj_str_t *method, pjsip_digest_credential *auth)

Type of callback function to create authentication response. Application can specify this callback in cb field of the credential info (pjsip_cred_info) and specifying PJSIP_CRED_DATA_DIGEST_CALLBACK as data_type. When this function is called, most of the fields in the auth authentication response will have been filled by the framework. Application normally should just need to calculate the response digest of the authentication response.

Parameters
poolPool to allocate memory from if application needs to.
chalThe authentication challenge sent by server in 401 or 401 response, in either Proxy-Authenticate or WWW-Authenticate header.
credThe credential that has been selected by the framework to authenticate against the challenge.
authThe authentication response which application needs to calculate the response digest.
Returns
Application may return non-PJ_SUCCESS to abort the authentication process. When this happens, the framework will return failure to the original function that requested authentication.

◆ pjsip_auth_lookup_cred

typedef pj_status_t pjsip_auth_lookup_cred(pj_pool_t *pool, const pj_str_t *realm, const pj_str_t *acc_name, pjsip_cred_info *cred_info)

Type of function to lookup credential for the specified name.

Parameters
poolPool to initialize the credential info.
realmRealm to find the account.
acc_nameAccount name to look for.
cred_infoThe structure to put the credential when it's found.
Returns
The function MUST return PJ_SUCCESS when it found a correct credential for the specified account and realm. Otherwise it may return PJSIP_EAUTHACCNOTFOUND or PJSIP_EAUTHACCDISABLED.

◆ pjsip_auth_lookup_cred2

typedef pj_status_t pjsip_auth_lookup_cred2(pj_pool_t *pool, const pjsip_auth_lookup_cred_param *param, pjsip_cred_info *cred_info)

Type of function to lookup credential for the specified name.

Parameters
poolPool to initialize the credential info.
paramThe input param for credential lookup.
cred_infoThe structure to put the credential when it's found.
Returns
The function MUST return PJ_SUCCESS when it found a correct credential for the specified account and realm. Otherwise it may return PJSIP_EAUTHACCNOTFOUND or PJSIP_EAUTHACCDISABLED.

Enumeration Type Documentation

◆ pjsip_cred_data_type

Type of data in the credential information in pjsip_cred_info.

Enumerator
PJSIP_CRED_DATA_PLAIN_PASSWD 

Plain text password.

PJSIP_CRED_DATA_DIGEST 

Hashed digest.

PJSIP_CRED_DATA_EXT_AKA 

Extended AKA info is available

◆ pjsip_auth_qop_type

Authentication's quality of protection (qop) type.

Enumerator
PJSIP_AUTH_QOP_NONE 

No quality of protection.

PJSIP_AUTH_QOP_AUTH 

Authentication.

PJSIP_AUTH_QOP_AUTH_INT 

Authentication with integrity protection.

PJSIP_AUTH_QOP_UNKNOWN 

Unknown protection.

Function Documentation

◆ pjsip_auth_clt_pref_dup()

void pjsip_auth_clt_pref_dup ( pj_pool_t pool,
pjsip_auth_clt_pref dst,
const pjsip_auth_clt_pref src 
)

Duplicate a client authentication preference setting.

Parameters
poolThe memory pool.
dstDestination client authentication preference.
srcSource client authentication preference.

◆ pjsip_cred_info_dup()

void pjsip_cred_info_dup ( pj_pool_t pool,
pjsip_cred_info dst,
const pjsip_cred_info src 
)

Duplicate a credential info.

Parameters
poolThe memory pool.
dstDestination credential.
srcSource credential.

◆ pjsip_cred_info_cmp()

int pjsip_cred_info_cmp ( const pjsip_cred_info cred1,
const pjsip_cred_info cred2 
)

Compare two credential infos.

Parameters
cred1The credential info to compare.
cred2The credential info to compare.
Returns
0 if both credentials are equal.

◆ pjsip_auth_clt_init()

pj_status_t pjsip_auth_clt_init ( pjsip_auth_clt_sess sess,
pjsip_endpoint endpt,
pj_pool_t pool,
unsigned  options 
)

Initialize client authentication session data structure, and set the session to use pool for its subsequent memory allocation. The argument options should be set to zero for this PJSIP version.

Parameters
sessThe client authentication session.
endptEndpoint where this session belongs.
poolPool to use.
optionsMust be zero.
Returns
PJ_SUCCESS on success.

◆ pjsip_auth_clt_deinit()

pj_status_t pjsip_auth_clt_deinit ( pjsip_auth_clt_sess sess)

Deinitialize client authentication session data structure.

Parameters
sessThe client authentication session.
Returns
PJ_SUCCESS on success.

◆ pjsip_auth_clt_clone()

pj_status_t pjsip_auth_clt_clone ( pj_pool_t pool,
pjsip_auth_clt_sess sess,
const pjsip_auth_clt_sess rhs 
)

Clone client initialization session.

Parameters
poolPool to use.
sessStructure to put the duplicated session.
rhsThe client session to be cloned.
Returns
PJ_SUCCESS on success;

◆ pjsip_auth_clt_set_credentials()

pj_status_t pjsip_auth_clt_set_credentials ( pjsip_auth_clt_sess sess,
int  cred_cnt,
const pjsip_cred_info c 
)

Set the credentials to be used during the session. This will duplicate the specified credentials using client authentication's pool.

Parameters
sessThe client authentication session.
cred_cntNumber of credentials.
cArray of credentials.
Returns
PJ_SUCCESS on success.

◆ pjsip_auth_clt_set_prefs()

pj_status_t pjsip_auth_clt_set_prefs ( pjsip_auth_clt_sess sess,
const pjsip_auth_clt_pref p 
)

Set the preference for the client authentication session.

Parameters
sessThe client authentication session.
pPreference.
Returns
PJ_SUCCESS on success.

◆ pjsip_auth_clt_get_prefs()

pj_status_t pjsip_auth_clt_get_prefs ( pjsip_auth_clt_sess sess,
pjsip_auth_clt_pref p 
)

Get the preference for the client authentication session.

Parameters
sessThe client authentication session.
pPointer to receive the preference.
Returns
PJ_SUCCESS on success.

◆ pjsip_auth_clt_init_req()

pj_status_t pjsip_auth_clt_init_req ( pjsip_auth_clt_sess sess,
pjsip_tx_data tdata 
)

Initialize new request message with authorization headers. This function will put Authorization/Proxy-Authorization headers to the outgoing request message. If caching is enabled (PJSIP_AUTH_HEADER_CACHING) and the session has previously sent Authorization/Proxy-Authorization header with the same method, then the same Authorization/Proxy-Authorization header will be resent from the cache only if qop is not present. If the stack is configured to automatically generate next Authorization/Proxy-Authorization headers (PJSIP_AUTH_AUTO_SEND_NEXT flag), then new Authorization/Proxy- Authorization headers are calculated and generated when they are not present in the case or if authorization session has qop.

If both PJSIP_AUTH_HEADER_CACHING flag and PJSIP_AUTH_AUTO_SEND_NEXT flag are not set, this function will do nothing. The stack then will only send Authorization/Proxy-Authorization to respond 401/407 response.

Parameters
sessThe client authentication session.
tdataThe request message to be initialized.
Returns
PJ_SUCCESS if successfull.

◆ pjsip_auth_clt_reinit_req()

pj_status_t pjsip_auth_clt_reinit_req ( pjsip_auth_clt_sess sess,
const pjsip_rx_data rdata,
pjsip_tx_data old_request,
pjsip_tx_data **  new_request 
)

Call this function when a transaction failed with 401 or 407 response. This function will reinitialize the original request message with the authentication challenge found in the response message, and add the new authorization header in the authorization cache.

Note that upon return the reference counter of the new transmit data will be set to 1.

Parameters
sessThe client authentication session.
rdataThe response message containing 401/407 status.
old_requestThe original request message, which will be re- created with authorization info.
new_requestPointer to receive new request message which will contain all required authorization headers.
Returns
PJ_SUCCESS if new request can be successfully created to respond all the authentication challenges.

◆ pjsip_auth_srv_init()

pj_status_t pjsip_auth_srv_init ( pj_pool_t pool,
pjsip_auth_srv auth_srv,
const pj_str_t realm,
pjsip_auth_lookup_cred lookup,
unsigned  options 
)

Initialize server authorization session data structure to serve the specified realm and to use lookup_func function to look for the credential info.

Parameters
poolPool used to initialize the authentication server.
auth_srvThe authentication server structure.
realmRealm to be served by the server.
lookupAccount lookup function.
optionsOptions, bitmask of:
  • PJSIP_AUTH_SRV_IS_PROXY: to specify that the server will authorize clients as a proxy server (instead of as UAS), which means that Proxy-Authenticate will be used instead of WWW-Authenticate.
Returns
PJ_SUCCESS on success.

◆ pjsip_auth_srv_init2()

pj_status_t pjsip_auth_srv_init2 ( pj_pool_t pool,
pjsip_auth_srv auth_srv,
const pjsip_auth_srv_init_param param 
)

Initialize server authorization session data structure to serve the specified realm and to use lookup_func function to look for the credential info.

Parameters
poolPool used to initialize the authentication server.
auth_srvThe authentication server structure.
paramThe initialization param.
Returns
PJ_SUCCESS on success.

◆ pjsip_auth_srv_verify()

pj_status_t pjsip_auth_srv_verify ( pjsip_auth_srv auth_srv,
pjsip_rx_data rdata,
int status_code 
)

Request the authorization server framework to verify the authorization information in the specified request in rdata.

Parameters
auth_srvThe server authentication structure.
rdataIncoming request to be authenticated.
status_codeWhen not null, it will be filled with suitable status code to be sent to the client.
Returns
PJ_SUCCESS if request is successfully authenticated. Otherwise the function may return one of the following error codes:
  • PJSIP_EAUTHNOAUTH
  • PJSIP_EINVALIDAUTHSCHEME
  • PJSIP_EAUTHACCNOTFOUND
  • PJSIP_EAUTHACCDISABLED
  • PJSIP_EAUTHINVALIDREALM
  • PJSIP_EAUTHINVALIDDIGEST

◆ pjsip_auth_srv_challenge()

pj_status_t pjsip_auth_srv_challenge ( pjsip_auth_srv auth_srv,
const pj_str_t qop,
const pj_str_t nonce,
const pj_str_t opaque,
pj_bool_t  stale,
pjsip_tx_data tdata 
)

Add authentication challenge headers to the outgoing response in tdata. Application may specify its customized nonce and opaque for the challenge, or can leave the value to NULL to make the function fills them in with random characters.

Parameters
auth_srvThe server authentication structure.
qopOptional qop value.
nonceOptional nonce value.
opaqueOptional opaque value.
staleStale indication.
tdataThe outgoing response message. The response must have 401 or 407 response code.
Returns
PJ_SUCCESS on success.

◆ pjsip_auth_create_digest()

void pjsip_auth_create_digest ( pj_str_t result,
const pj_str_t nonce,
const pj_str_t nc,
const pj_str_t cnonce,
const pj_str_t qop,
const pj_str_t uri,
const pj_str_t realm,
const pjsip_cred_info cred_info,
const pj_str_t method 
)

Helper function to create MD5 digest out of the specified parameters.

Parameters
resultString to store the response digest. This string must have been preallocated by caller with the buffer at least PJSIP_MD5STRLEN (32 bytes) in size.
nonceOptional nonce.
ncNonce count.
cnonceOptional cnonce.
qopOptional qop.
uriURI.
realmRealm.
cred_infoCredential info.
methodSIP method.

 


PJSIP Open Source, high performance, small footprint, and very very portable SIP stack
Copyright (C) 2006-2008 Teluu Inc.