Continuing ticket #396: tested digest AKAv1, implemented AKAv2, and some works in the authentication framework to support it

git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@1500 74dad513-b988-da41-8d7b-12977e46ad98

1 files changed, 138 insertions, 17 deletions

diff --git a/pjsip/include/pjsip/sip_auth_aka.h b/pjsip/include/pjsip/sip_auth_aka.h
index c5c2a60d..2c8030ab 100644
--- a/pjsip/include/pjsip/sip_auth_aka.h
+++ b/pjsip/include/pjsip/sip_auth_aka.h
@@ -29,49 +29,170 @@
 PJ_BEGIN_DECL
 
 /**
- * @defgroup PJSIP_AUTH_AKA_API Digest AKA Authentication API's
+ * @defgroup PJSIP_AUTH_AKA_API Digest AKAv1 and AKAv2 Authentication API
  * @ingroup PJSIP_AUTH_API
- * @brief Digest AKA helper API.
+ * @brief Digest AKAv1 and AKAv2 Authentication API
  * @{
  *
- * This module currently exports one function, #pjsip_auth_create_akav1_response(),
- * which can be registered as the callback function in \a ext.aka.cb field
- * of #pjsip_cred_info structure, to calculate the MD5-AKAv1 digest
- * response.
- */
+ * 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.
+ *
+ * @section pjsip_aka_using Using Digest AKA Authentication
+ *
+ * Support for digest AKA authentication is currently made optional, so
+ * application needs to declare \a PJSIP_HAS_DIGEST_AKA_AUTH to non-zero
+ * in <tt>config_site.h</tt> to enable AKA support:
+ *
+ @code
+   #define PJSIP_HAS_DIGEST_AKA_AUTH   1
+ @endcode
+
+ *
+ * In addition, application would need to link with <b>libmilenage</b>
+ * library from \a third_party directory.
+ *
+ * Application then specifies digest AKA credential by initializing the 
+ * authentication credential as follows:
+ *
+ @code
+
+    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
+
+ @endcode
+ *
+ * Description:
+ * - To support AKA, application adds \a PJSIP_CRED_DATA_EXT_AKA flag in the
+ * \a 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 \a scheme for the credential is "Digest". 
+ *
+ * - The \a 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 \a 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 \a 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 \a slen field of the string.
+ *
+ * - The \a 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 \a ext.aka.op and \a ext.aka.amf in the
+ * credential to specify AKA Operator variant key and AKA Authentication 
+ * Management Field information.
+ */
 
+/**
+ * Length of Authentication Key (AK) in bytes.
+ */
 #define PJSIP_AKA_AKLEN		6
+
+/**
+ * Length of Authentication Management Field (AMF) in bytes.
+ */
 #define PJSIP_AKA_AMFLEN	2
+
+/**
+ * Length of AUTN in bytes.
+ */
 #define PJSIP_AKA_AUTNLEN	16
+
+/**
+ * Length of Confidentiality Key (CK) in bytes.
+ */
 #define PJSIP_AKA_CKLEN		16
+
+/**
+ * Length of Integrity Key (AK) in bytes.
+ */
 #define PJSIP_AKA_IKLEN		16
+
+/**
+ * Length of permanent/subscriber Key (K) in bytes.
+ */
 #define PJSIP_AKA_KLEN		16
+
+/**
+ * Length of AKA authentication code in bytes.
+ */
+#define PJSIP_AKA_MACLEN	8
+
+/**
+ * Length of operator key in bytes.
+ */
 #define PJSIP_AKA_OPLEN		16
+
+/**
+ * Length of random challenge (RAND) in bytes.
+ */
 #define PJSIP_AKA_RANDLEN	16
+
+/**
+ * Length of response digest in bytes.
+ */
 #define PJSIP_AKA_RESLEN	8
-#define PJSIP_AKA_MACLEN	8
 
 /**
- * This function creates MD5 AKAv1 response for the specified challenge
- * in \a chal, based on the information in the credential \a cred.
+ * Length of sequence number (SQN) in bytes.
+ */
+#define PJSIP_AKA_SQNLEN	6
+
+/**
+ * This function creates MD5, AKAv1-MD5, or AKAv2-MD5 response for
+ * the specified challenge in \a chal, according to the algorithm 
+ * specified in the challenge, and based on the information in the 
+ * credential \a cred.
+ *
  * Application may register this function as \a ext.aka.cb field of
  * #pjsip_cred_info structure to make PJSIP automatically call this
- * function to calculate the response digest.
+ * function to calculate the response digest. To do so, it needs to
+ * add \a PJSIP_CRED_DATA_EXT_AKA flag in the \a data_type field of
+ * the credential, and fills up other AKA specific information in
+ * the credential.
  *
  * @param pool	    Pool to allocate memory.
  * @param chal	    The authentication challenge sent by server in 401
- *		    or 401 response, in either Proxy-Authenticate or
+ *		    or 401 response, as either Proxy-Authenticate or
  *		    WWW-Authenticate header.
- * @param cred	    The credential that has been selected by the framework
- *		    to authenticate against the challenge.
+ * @param cred	    The credential to be used.
  * @param method    The request method.
- * @param auth	    The authentication credential where the digest response
- *		    will be placed to.
+ * @param 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 \a response field will be initialized
+ *		    by this function.
  *
  * @return	    PJ_SUCCESS if response has been created successfully.
  */
-PJ_DECL(pj_status_t) pjsip_auth_create_akav1(pj_pool_t *pool,
+PJ_DECL(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,