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:
- 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 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
|#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.
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.
|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.|
- PJ_SUCCESS if response has been created successfully.