1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
|
/* $Id$ */
/*
* Copyright (C) 2003-2005 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 __PJ_STUN_AUTH_H__
#define __PJ_STUN_AUTH_H__
/**
* @file stun_auth.h
* @brief STUN authentication.
*/
#include <pjlib-util/stun_msg.h>
PJ_BEGIN_DECL
/* **************************************************************************/
/**
* @defgroup PJLIB_UTIL_STUN_AUTH STUN Authentication
* @ingroup PJLIB_UTIL_STUN
* @{
*/
/**
* Type of authentication data in the credential.
*/
typedef enum pj_stun_auth_cred_type
{
/**
* The credential data contains a static credential to be matched
* against the credential in the message. A static credential can be
* used as both client side or server side authentication.
*/
PJ_STUN_AUTH_CRED_STATIC,
/**
* The credential data contains callbacks to be called to verify the
* credential in the message. A dynamic credential is suitable when
* performing server side authentication where server does not know
* in advance the identity of the user requesting authentication.
*/
PJ_STUN_AUTH_CRED_DYNAMIC
} pj_stun_auth_cred_type;
/**
* This structure contains the descriptions needed to perform server side
* authentication. Depending on the \a type set in the structure, application
* may specify a static username/password combination, or to have callbacks
* called by the function to authenticate the credential dynamically.
*/
typedef struct pj_stun_auth_cred
{
/**
* The type of authentication information in this structure.
*/
pj_stun_auth_cred_type type;
/**
* This union contains the authentication data.
*/
union
{
/**
* This structure contains static data for performing authentication.
* A non-empty realm indicates whether short term or long term
* credential is used.
*/
struct
{
/**
* If not-empty, it indicates that this is a long term credential.
*/
pj_str_t realm;
/**
* The username of the credential.
*/
pj_str_t username;
/**
* Data type to indicate the type of password in the \a data field.
* Value zero indicates that the data contains a plaintext
* password.
*/
int data_type;
/**
* The data, which depends depends on the value of \a data_type
* field. When \a data_type is zero, this field will contain the
* plaintext password.
*/
pj_str_t data;
/**
* Optional NONCE.
*/
pj_str_t nonce;
} static_cred;
/**
* This structure contains callback to be called by the framework
* to authenticate the incoming message.
*/
struct
{
/**
* User data which will be passed back to callback functions.
*/
void *user_data;
/**
* This callback is called by pj_stun_verify_credential() when
* server needs to challenge the request with 401 response.
*
* @param user_data The user data as specified in the credential.
* @param pool Pool to allocate memory.
* @param realm On return, the function should fill in with
* realm if application wants to use long term
* credential. Otherwise application should set
* empty string for the realm.
* @param nonce On return, if application wants to use long
* term credential, it MUST fill in the nonce
* with some value. Otherwise if short term
* credential is wanted, it MAY set this value.
* If short term credential is wanted and the
* application doesn't want to include NONCE,
* then it must set this to empty string.
*
* @return The callback should return PJ_SUCCESS, or
* otherwise response message will not be
* created.
*/
pj_status_t (*get_auth)(void *user_data,
pj_pool_t *pool,
pj_str_t *realm,
pj_str_t *nonce);
/**
* Get the password for the specified username. This function
* is also used to check whether the username is valid.
*
* @param user_data The user data as specified in the credential.
* @param realm The realm as specified in the message.
* @param username The username as specified in the message.
* @param pool Pool to allocate memory when necessary.
* @param data_type On return, application should fill up this
* argument with the type of data (which should
* be zero if data is a plaintext password).
* @param data On return, application should fill up this
* argument with the password according to
* data_type.
*
* @return The callback should return PJ_SUCCESS if
* username has been successfully verified
* and password was obtained. If non-PJ_SUCCESS
* is returned, it is assumed that the
* username is not valid.
*/
pj_status_t (*get_password)(void *user_data,
const pj_str_t *realm,
const pj_str_t *username,
pj_pool_t *pool,
int *data_type,
pj_str_t *data);
/**
* This callback will be called to verify that the NONCE given
* in the message can be accepted. If this callback returns
* PJ_FALSE, 438 (Stale Nonce) response will be created.
*
* @param user_data The user data as specified in the credential.
* @param realm The realm as specified in the message.
* @param username The username as specified in the message.
* @param nonce The nonce to be verified.
*
* @return The callback MUST return non-zero if the
* NONCE can be accepted.
*/
pj_bool_t (*verify_nonce)(void *user_data,
const pj_str_t *realm,
const pj_str_t *username,
const pj_str_t *nonce);
} dyn_cred;
} data;
} pj_stun_auth_cred;
/**
* Duplicate authentication credential.
*
* @param pool Pool to be used to allocate memory.
* @param dst Destination credential.
* @param src Source credential.
*/
PJ_DECL(void) pj_stun_auth_cred_dup(pj_pool_t *pool,
pj_stun_auth_cred *dst,
const pj_stun_auth_cred *src);
/**
* Verify credential in the STUN message. Note that before calling this
* function, application must have checked that the message contains
* PJ_STUN_ATTR_MESSAGE_INTEGRITY attribute by calling pj_stun_msg_find_attr()
* function, because this function will reject the message with 401 error
* if it doesn't contain PJ_STUN_ATTR_MESSAGE_INTEGRITY attribute.
*
* @param pkt The original packet which has been parsed into
* the message. This packet MUST NOT have been modified
* after the parsing.
* @param pkt_len The length of the packet.
* @param msg The parsed message to be verified.
* @param cred Pointer to credential to be used to authenticate
* the message.
* @param pool If response is to be created, then memory will
* be allocated from this pool.
* @param p_response Optional pointer to receive the response message
* then the credential in the request fails to
* authenticate.
*
* @return PJ_SUCCESS if credential is verified successfully.
* If the verification fails and \a p_response is not
* NULL, an appropriate response will be returned in
* \a p_response.
*/
PJ_DECL(pj_status_t) pj_stun_verify_credential(const pj_uint8_t *pkt,
unsigned pkt_len,
const pj_stun_msg *msg,
pj_stun_auth_cred *cred,
pj_pool_t *pool,
pj_stun_msg **p_response);
/**
* @}
*/
/* Calculate HMAC-SHA1 key for long term credential, by getting
* MD5 digest of username, realm, and password.
*/
void pj_stun_calc_md5_key(pj_uint8_t digest[16],
const pj_str_t *realm,
const pj_str_t *username,
const pj_str_t *passwd);
PJ_END_DECL
#endif /* __PJ_STUN_AUTH_H__ */
|
