/* $Id$ */ /* * Copyright (C) 2008-2009 Teluu Inc. (http://www.teluu.com) * Copyright (C) 2003-2008 Benny Prijono * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ #ifndef __PJSIP_AUTH_SIP_AUTH_AKA_H__ #define __PJSIP_AUTH_SIP_AUTH_AKA_H__ /** * @file sip_auth_aka.h * @brief SIP Digest AKA Authorization Module. */ #include PJ_BEGIN_DECL /** * @defgroup PJSIP_AUTH_AKA_API Digest AKAv1 and AKAv2 Authentication API * @ingroup PJSIP_AUTH_API * @brief 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. * * @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 config_site.h to enable AKA support: * @code #define PJSIP_HAS_DIGEST_AKA_AUTH 1 @endcode * * In addition, application would need to link with libmilenage * 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 /** * 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. 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, as either Proxy-Authenticate or * WWW-Authenticate header. * @param cred The credential to be used. * @param method The request method. * @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_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); /** * @} */ PJ_END_DECL #endif /* __PJSIP_AUTH_SIP_AUTH_AKA_H__ */