Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjsip / include / pjsip / sip_auth_aka.h
1 /* $Id$ */
2 /* 
3  * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4  * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
5  *
6  * This program is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software
18  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
19  */
20 #ifndef __PJSIP_AUTH_SIP_AUTH_AKA_H__
21 #define __PJSIP_AUTH_SIP_AUTH_AKA_H__
22
23 /**
24  * @file sip_auth_aka.h
25  * @brief SIP Digest AKA Authorization Module.
26  */
27
28 #include <pjsip/sip_auth.h>
29
30 PJ_BEGIN_DECL
31
32 /**
33  * @defgroup PJSIP_AUTH_AKA_API Digest AKAv1 and AKAv2 Authentication API
34  * @ingroup PJSIP_AUTH_API
35  * @brief Digest AKAv1 and AKAv2 Authentication API
36  * @{
37  *
38  * This module implements HTTP digest authentication using Authentication
39  * and Key Agreement (AKA) version 1 and version 2 (AKAv1-MD5 and AKAv2-MD5),
40  * as specified in RFC 3310 and RFC 4169. SIP AKA authentication is used
41  * by 3GPP and IMS systems.
42  *
43  * @section pjsip_aka_using Using Digest AKA Authentication
44  *
45  * Support for digest AKA authentication is currently made optional, so
46  * application needs to declare \a PJSIP_HAS_DIGEST_AKA_AUTH to non-zero
47  * in <tt>config_site.h</tt> to enable AKA support:
48  *
49  @code
50    #define PJSIP_HAS_DIGEST_AKA_AUTH   1
51  @endcode
52
53  *
54  * In addition, application would need to link with <b>libmilenage</b>
55  * library from \a third_party directory.
56  *
57  * Application then specifies digest AKA credential by initializing the 
58  * authentication credential as follows:
59  *
60  @code
61
62     pjsip_cred_info cred;
63
64     pj_bzero(&cred, sizeof(cred));
65
66     cred.scheme = pj_str("Digest");
67     cred.realm = pj_str("ims-domain.test");
68     cred.username = pj_str("user@ims-domain.test");
69     cred.data_type = PJSIP_CRED_DATA_PLAIN_PASSWD | PJSIP_CRED_DATA_EXT_AKA;
70     cred.data = pj_str("password");
71
72     // AKA extended info
73     cred.ext.aka.k = pj_str("password");
74     cred.ext.aka.cb = &pjsip_auth_create_aka_response
75
76  @endcode
77  *
78  * Description:
79  * - To support AKA, application adds \a PJSIP_CRED_DATA_EXT_AKA flag in the
80  * \a data_type field. This indicates that extended information specific to
81  * AKA authentication is available in the credential, and that response 
82  * digest computation will use the callback function instead of the usual MD5
83  * digest computation.
84  *
85  * - The \a scheme for the credential is "Digest". 
86  *
87  * - The \a realm is the expected realm in the challenge. Application may 
88  * also specify wildcard realm ("*") if it wishes to respond to any realms 
89  * in the challenge.
90  *
91  * - The \a data field is optional. Application may fill this with the password
92  * if it wants to support both MD5 and AKA MD5 in a single credential. The
93  * pjsip_auth_create_aka_response() function will use this field if the
94  * challenge indicates "MD5" as the algorithm instead of "AKAv1-MD5" or
95  * "AKAv2-MD5".
96  *
97  * - The \a ext.aka.k field specifies the permanent subscriber key to be used
98  * for AKA authentication. Application may specify binary password containing
99  * NULL character in this key, since the length of the key is indicated in
100  * the \a slen field of the string.
101  *
102  * - The \a ext.aka.cb field specifies the callback function to calculate the
103  * response digest. Application can specify pjsip_auth_create_aka_response()
104  * in this field to use PJSIP's implementation, but it's free to provide
105  * it's own function.
106  *
107  * - Optionally application may set \a ext.aka.op and \a ext.aka.amf in the
108  * credential to specify AKA Operator variant key and AKA Authentication 
109  * Management Field information.
110  */
111
112 /**
113  * Length of Authentication Key (AK) in bytes.
114  */
115 #define PJSIP_AKA_AKLEN         6
116
117 /**
118  * Length of Authentication Management Field (AMF) in bytes.
119  */
120 #define PJSIP_AKA_AMFLEN        2
121
122 /**
123  * Length of AUTN in bytes.
124  */
125 #define PJSIP_AKA_AUTNLEN       16
126
127 /**
128  * Length of Confidentiality Key (CK) in bytes.
129  */
130 #define PJSIP_AKA_CKLEN         16
131
132 /**
133  * Length of Integrity Key (AK) in bytes.
134  */
135 #define PJSIP_AKA_IKLEN         16
136
137 /**
138  * Length of permanent/subscriber Key (K) in bytes.
139  */
140 #define PJSIP_AKA_KLEN          16
141
142 /**
143  * Length of AKA authentication code in bytes.
144  */
145 #define PJSIP_AKA_MACLEN        8
146
147 /**
148  * Length of operator key in bytes.
149  */
150 #define PJSIP_AKA_OPLEN         16
151
152 /**
153  * Length of random challenge (RAND) in bytes.
154  */
155 #define PJSIP_AKA_RANDLEN       16
156
157 /**
158  * Length of response digest in bytes.
159  */
160 #define PJSIP_AKA_RESLEN        8
161
162 /**
163  * Length of sequence number (SQN) in bytes.
164  */
165 #define PJSIP_AKA_SQNLEN        6
166
167 /**
168  * This function creates MD5, AKAv1-MD5, or AKAv2-MD5 response for
169  * the specified challenge in \a chal, according to the algorithm 
170  * specified in the challenge, and based on the information in the 
171  * credential \a cred.
172  *
173  * Application may register this function as \a ext.aka.cb field of
174  * #pjsip_cred_info structure to make PJSIP automatically call this
175  * function to calculate the response digest. To do so, it needs to
176  * add \a PJSIP_CRED_DATA_EXT_AKA flag in the \a data_type field of
177  * the credential, and fills up other AKA specific information in
178  * the credential.
179  *
180  * @param pool      Pool to allocate memory.
181  * @param chal      The authentication challenge sent by server in 401
182  *                  or 401 response, as either Proxy-Authenticate or
183  *                  WWW-Authenticate header.
184  * @param cred      The credential to be used.
185  * @param method    The request method.
186  * @param auth      The digest credential where the digest response
187  *                  will be placed to. Upon calling this function, the
188  *                  nonce, nc, cnonce, qop, uri, and realm fields of
189  *                  this structure must have been set by caller. Upon
190  *                  return, the \a response field will be initialized
191  *                  by this function.
192  *
193  * @return          PJ_SUCCESS if response has been created successfully.
194  */
195 PJ_DECL(pj_status_t) pjsip_auth_create_aka_response(
196                                              pj_pool_t *pool,
197                                              const pjsip_digest_challenge*chal,
198                                              const pjsip_cred_info *cred,
199                                              const pj_str_t *method,
200                                              pjsip_digest_credential *auth);
201
202
203 /**
204  * @}
205  */
206
207
208
209 PJ_END_DECL
210
211
212 #endif  /* __PJSIP_AUTH_SIP_AUTH_AKA_H__ */
213