| /* $Id$ */ |
| /* |
| * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) |
| * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org> |
| * |
| * 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 <pjsip/sip_auth.h> |
| |
| 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 <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 |
| |
| /** |
| * 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__ */ |
| |