213 lines
6.4 KiB
C
213 lines
6.4 KiB
C
/* $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__ */
|
|
|