Group PJSIP_AUTH_AKA_API

group PJSIP_AUTH_AKA_API

Digest AKAv1 and AKAv2 Authentication API.

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.

Defines

PJSIP_AKA_AKLEN

Length of Authentication Key (AK) in bytes.

PJSIP_AKA_AMFLEN

Length of Authentication Management Field (AMF) in bytes.

PJSIP_AKA_AUTNLEN

Length of AUTN in bytes.

PJSIP_AKA_CKLEN

Length of Confidentiality Key (CK) in bytes.

PJSIP_AKA_IKLEN

Length of Integrity Key (AK) in bytes.

PJSIP_AKA_KLEN

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

PJSIP_AKA_MACLEN

Length of AKA authentication code in bytes.

PJSIP_AKA_OPLEN

Length of operator key in bytes.

PJSIP_AKA_RANDLEN

Length of random challenge (RAND) in bytes.

PJSIP_AKA_RESLEN

Length of response digest in bytes.

PJSIP_AKA_SQNLEN

Length of sequence number (SQN) in bytes.

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)

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.