Digest AKAv1 and AKAv2 Authentication API
[Authentication API's]

Digest AKAv1 and AKAv2 Authentication API. More...

Defines
#define	PJSIP_AKA_AKLEN   6
#define	PJSIP_AKA_AMFLEN   2
#define	PJSIP_AKA_AUTNLEN   16
#define	PJSIP_AKA_CKLEN   16
#define	PJSIP_AKA_IKLEN   16
#define	PJSIP_AKA_KLEN   16
#define	PJSIP_AKA_MACLEN   8
#define	PJSIP_AKA_OPLEN   16
#define	PJSIP_AKA_RANDLEN   16
#define	PJSIP_AKA_RESLEN   8
#define	PJSIP_AKA_SQNLEN   6
Functions
pj_status_t	pjsip_auth_create_aka_response (pj_pool_t *pool, const pjsip_digest_challenge *chal, const pjsip_cred_info *cred, const pj_str_t *method, pjsip_digest_credential *auth)

---

Detailed Description

This module implements HTTP digest authentication using Authentication and Key Agreement (AKA) version 1 and version 2 (AKAv1-MD5 and AKAv2-MD5), as specified in RFC 3310 and RFC 4169. SIP AKA authentication is used by 3GPP and IMS systems.

Using Digest AKA Authentication

Support for digest AKA authentication is currently made optional, so application needs to declare PJSIP_HAS_DIGEST_AKA_AUTH to non-zero in config_site.h to enable AKA support:

   #define PJSIP_HAS_DIGEST_AKA_AUTH   1

In addition, application would need to link with libmilenage library from third_party directory.

Application then specifies digest AKA credential by initializing the authentication credential as follows:

    pjsip_cred_info cred;

    pj_bzero(&cred, sizeof(cred));

    cred.scheme = pj_str("Digest");
    cred.realm = pj_str("ims-domain.test");
    cred.username = pj_str("user@ims-domain.test");
    cred.data_type = PJSIP_CRED_DATA_PLAIN_PASSWD | PJSIP_CRED_DATA_EXT_AKA;
    cred.data = pj_str("password");

    // AKA extended info
    cred.ext.aka.k = pj_str("password");
    cred.ext.aka.cb = &pjsip_auth_create_aka_response

Description:

• To support AKA, application adds PJSIP_CRED_DATA_EXT_AKA flag in the data_type field. This indicates that extended information specific to AKA authentication is available in the credential, and that response digest computation will use the callback function instead of the usual MD5 digest computation.

• The scheme for the credential is "Digest".

• The realm is the expected realm in the challenge. Application may also specify wildcard realm ("*") if it wishes to respond to any realms in the challenge.

• The data field is optional. Application may fill this with the password if it wants to support both MD5 and AKA MD5 in a single credential. The pjsip_auth_create_aka_response() function will use this field if the challenge indicates "MD5" as the algorithm instead of "AKAv1-MD5" or "AKAv2-MD5".

• The ext.aka.k field specifies the permanent subscriber key to be used for AKA authentication. Application may specify binary password containing NULL character in this key, since the length of the key is indicated in the slen field of the string.

• The ext.aka.cb field specifies the callback function to calculate the response digest. Application can specify pjsip_auth_create_aka_response() in this field to use PJSIP's implementation, but it's free to provide it's own function.

• Optionally application may set ext.aka.op and ext.aka.amf in the credential to specify AKA Operator variant key and AKA Authentication Management Field information.

---

Define Documentation

#define PJSIP_AKA_AKLEN   6

Length of Authentication Key (AK) in bytes.

#define PJSIP_AKA_AMFLEN   2

Length of Authentication Management Field (AMF) in bytes.

#define PJSIP_AKA_AUTNLEN   16

Length of AUTN in bytes.

#define PJSIP_AKA_CKLEN   16

Length of Confidentiality Key (CK) in bytes.

#define PJSIP_AKA_IKLEN   16

Length of Integrity Key (AK) in bytes.

#define PJSIP_AKA_KLEN   16

Length of permanent/subscriber Key (K) in bytes.

#define PJSIP_AKA_MACLEN   8

Length of AKA authentication code in bytes.

#define PJSIP_AKA_OPLEN   16

Length of operator key in bytes.

#define PJSIP_AKA_RANDLEN   16

Length of random challenge (RAND) in bytes.

#define PJSIP_AKA_RESLEN   8

Length of response digest in bytes.

#define PJSIP_AKA_SQNLEN   6

Length of sequence number (SQN) in bytes.

---

Function Documentation

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

This function creates MD5, AKAv1-MD5, or AKAv2-MD5 response for the specified challenge in chal, according to the algorithm specified in the challenge, and based on the information in the credential cred.

Application may register this function as ext.aka.cb field of pjsip_cred_info structure to make PJSIP automatically call this function to calculate the response digest. To do so, it needs to add PJSIP_CRED_DATA_EXT_AKA flag in the data_type field of the credential, and fills up other AKA specific information in the credential.

Parameters:

	pool	Pool to allocate memory.
	chal	The authentication challenge sent by server in 401 or 401 response, as either Proxy-Authenticate or WWW-Authenticate header.
	cred	The credential to be used.
	method	The request method.
	auth	The digest credential where the digest response will be placed to. Upon calling this function, the nonce, nc, cnonce, qop, uri, and realm fields of this structure must have been set by caller. Upon return, the response field will be initialized by this function.

Returns:

PJ_SUCCESS if response has been created successfully.