Debian Codegraph @

src/modules/auth_db/README

raw
1 Auth_db Module
2
3 Jan Janak
4
5 FhG Fokus
6 <[email protected]>
7
8 Jakob Schlyter
9
10 <[email protected]>
11
12 Bogdan-Andrei Iancu
13
14 Voice Sistem SRL
15 <[email protected]>
16
17 Daniel-Constantin Mierla
18
19 <[email protected]>
20
21 Edited by
22
23 Jan Janak
24
25 <[email protected]>
26
27 Copyright © 2002, 2003 FhG FOKUS
28
29 Copyright © 2005 Voice Sistem SRL
30 __________________________________________________________________
31
32 Table of Contents
33
34 1. Admin Guide
35
36 1. Overview
37 2. Dependencies
38
39 2.1. Kamailio Modules
40 2.2. External Libraries or Applications
41
42 3. Parameters
43
44 3.1. db_url (string)
45 3.2. user_column (string)
46 3.3. domain_column (string)
47 3.4. password_column (string)
48 3.5. password_column_2 (string)
49 3.6. calculate_ha1 (integer)
50 3.7. use_domain (integer)
51 3.8. load_credentials (string)
52 3.9. version_table (integer)
53 3.10. force_generate_avps (integer)
54
55 4. Functions
56
57 4.1. www_authenticate(realm, table [, method])
58 4.2. www_authorize(realm, table)
59 4.3. proxy_authenticate(realm, table)
60 4.4. proxy_authorize(realm, table)
61 4.5. auth_check(realm, table, flags)
62 4.6. is_subscriber(uri, dbtable, flags)
63
64 List of Examples
65
66 1.1. db_url parameter usage
67 1.2. user_column parameter usage
68 1.3. domain_column parameter usage
69 1.4. password_column parameter usage
70 1.5. password_column_2 parameter usage
71 1.6. calculate_ha1 parameter usage
72 1.7. use_domain parameter usage
73 1.8. load_credentials parameter usage
74 1.9. version_table parameter usage
75 1.10. force_generate_avps parameter usage
76 1.11. www_authorize usage
77 1.12. proxy_authorize usage
78 1.13. auth_check usage
79 1.14. is_subscriber usage
80
81 Chapter 1. Admin Guide
82
83 Table of Contents
84
85 1. Overview
86 2. Dependencies
87
88 2.1. Kamailio Modules
89 2.2. External Libraries or Applications
90
91 3. Parameters
92
93 3.1. db_url (string)
94 3.2. user_column (string)
95 3.3. domain_column (string)
96 3.4. password_column (string)
97 3.5. password_column_2 (string)
98 3.6. calculate_ha1 (integer)
99 3.7. use_domain (integer)
100 3.8. load_credentials (string)
101 3.9. version_table (integer)
102 3.10. force_generate_avps (integer)
103
104 4. Functions
105
106 4.1. www_authenticate(realm, table [, method])
107 4.2. www_authorize(realm, table)
108 4.3. proxy_authenticate(realm, table)
109 4.4. proxy_authorize(realm, table)
110 4.5. auth_check(realm, table, flags)
111 4.6. is_subscriber(uri, dbtable, flags)
112
113 1. Overview
114
115 This module contains all authentication related functions that need the
116 access to the database. This module should be used together with auth
117 module, it cannot be used independently because it depends on the
118 module. Select this module if you want to use database to store
119 authentication information like subscriber usernames and passwords. If
120 you want to use radius authentication, then use auth_radius instead.
121
122 2. Dependencies
123
124 2.1. Kamailio Modules
125 2.2. External Libraries or Applications
126
127 2.1. Kamailio Modules
128
129 The module depends on the following modules (in other words the listed
130 modules must be loaded before this module):
131 * auth -- Generic authentication functions
132 * database -- Any database module (currently mysql, postgres, dbtext)
133
134 2.2. External Libraries or Applications
135
136 The following libraries or applications must be installed before
137 running Kamailio with this module loaded:
138 * none
139
140 3. Parameters
141
142 3.1. db_url (string)
143 3.2. user_column (string)
144 3.3. domain_column (string)
145 3.4. password_column (string)
146 3.5. password_column_2 (string)
147 3.6. calculate_ha1 (integer)
148 3.7. use_domain (integer)
149 3.8. load_credentials (string)
150 3.9. version_table (integer)
151 3.10. force_generate_avps (integer)
152
153 3.1. db_url (string)
154
155 This is URL of the database to be used. Value of the parameter depends
156 on the database module used. For example for mysql and postgres modules
157 this is something like mysql://username:password@host:port/database.
158 For dbtext module (which stores data in plaintext files) it is
159 directory in which the database resides.
160
161 Default value is “mysql://kamailioro:kamailioro@localhost/kamailio”.
162
163 Example 1.1. db_url parameter usage
164 ...
165 modparam("auth_db", "db_url", "dbdriver://username:password@dbhost/dbname")
166 ...
167
168 3.2. user_column (string)
169
170 This is the name of the column holding usernames. Default value is fine
171 for most people. Use the parameter if you really need to change it.
172
173 Default value is “username”.
174
175 Example 1.2. user_column parameter usage
176 ...
177 modparam("auth_db", "user_column", "user")
178 ...
179
180 3.3. domain_column (string)
181
182 This is the name of the column holding domains of users. Default value
183 is fine for most people. Use the parameter if you really need to change
184 it.
185
186 Default value is “domain”.
187
188 Example 1.3. domain_column parameter usage
189 ...
190 modparam("auth_db", "domain_column", "domain")
191 ...
192
193 3.4. password_column (string)
194
195 This is the name of the column holding passwords. Passwords can be
196 either stored as plain text or pre-calculated HA1 strings. HA1 strings
197 are MD5 hashes of username, password, and realm. HA1 strings are more
198 safe because the server doesn't need to know plaintext passwords and
199 they cannot be obtained from HA1 strings.
200
201 Default value is “ha1”.
202
203 Example 1.4. password_column parameter usage
204 ...
205 modparam("auth_db", "password_column", "password")
206 ...
207
208 3.5. password_column_2 (string)
209
210 As described in the previous section this parameter contains name of
211 column holding pre-calculated HA1 string that were calculated including
212 the domain in the username. This parameter is used only when
213 calculate_ha1 is set to 0 and user agent send a credentials containing
214 the domain in the username.
215
216 Default value of the parameter is ha1b.
217
218 Example 1.5. password_column_2 parameter usage
219 ...
220 modparam("auth_db", "password_column_2", "ha1_2")
221 ...
222
223 3.6. calculate_ha1 (integer)
224
225 This parameter tells the server whether it should use a pre-calculated
226 HA1 string or plaintext passwords for authentication.
227
228 If the parameter is set to 0 and the username parameter of credentials
229 contains also “@domain” (some user agents append the domain to the
230 username parameter), then the server will use the HA1 values from the
231 column specified in the “password_column_2” parameter. If the username
232 parameter doesn't contain a domain, the server will use the HA1 values
233 from the column given in the “password_column”parameter.
234
235 If the parameter is set to 1 then the HA1 value will be calculated from
236 the column specified in the “password_column” parameter.
237
238 The “password_column_2”column contain also HA1 strings but they should
239 be calculated including the domain in the username parameter (as
240 opposed to password_column which (when containing HA1 strings) should
241 always contains HA1 strings calculated without domain in username.
242
243 This ensures that the authentication will always work when using
244 pre-calculated HA1 strings, not depending on the presence of the domain
245 in username.
246
247 Default value of this parameter is 0.
248
249 Example 1.6. calculate_ha1 parameter usage
250 ...
251 modparam("auth_db", "calculate_ha1", 1)
252 ...
253
254 3.7. use_domain (integer)
255
256 If true (not 0), domain will be also used when looking up in the
257 subscriber table. If you have a multi-domain setup, it is strongly
258 recommended to turn on this parameter to avoid username overlapping
259 between domains.
260
261 IMPORTANT: before turning on this parameter, be sure that the domain
262 column in subscriber table is properly populated.
263
264 Default value is “0 (false)”.
265
266 Example 1.7. use_domain parameter usage
267 ...
268 modparam("auth_db", "use_domain", 1)
269 ...
270
271 3.8. load_credentials (string)
272
273 This parameter specifies of credentials to be fetch from database when
274 the authentication is performed. The loaded credentials will be stored
275 in AVPs. If the AVP name is not specifically given, it will be used a
276 NAME AVP with the same name as the column name.
277
278 Parameter syntax:
279 * load_credentials = credential (';' credential)*
280 * credential = (avp_specification '=' column_name) | (column_name)
281 * avp_specification = '$avp(' + 'i:'ID | 's:'NAME | alias + ')'
282
283 Default value of this parameter is “NULL” (no credentials loaded).
284
285 Example 1.8. load_credentials parameter usage
286 ...
287 # load rpid column into $avp(i:123) and email_address column
288 # into $avp(s:email_address)
289 modparam("auth_db", "load_credentials", "$avp(i:123)=rpid;email_address")
290 ...
291
292 3.9. version_table (integer)
293
294 If set to 0, the module will skip checking the version for subscriber
295 table.
296
297 Default value is “1 (check for table version)”.
298
299 Example 1.9. version_table parameter usage
300 ...
301 modparam("auth_db", "version_table", 0)
302 ...
303
304 3.10. force_generate_avps (integer)
305
306 If set to different than 0, the module will fetch user DB attributes
307 even if authentication failed.
308
309 Default value is “0” (don't fetch user DB attributes if authentication
310 failed).
311
312 Example 1.10. force_generate_avps parameter usage
313 ...
314 modparam("auth_db", "force_generate_avps", 1)
315 ...
316
317 4. Functions
318
319 4.1. www_authenticate(realm, table [, method])
320 4.2. www_authorize(realm, table)
321 4.3. proxy_authenticate(realm, table)
322 4.4. proxy_authorize(realm, table)
323 4.5. auth_check(realm, table, flags)
324 4.6. is_subscriber(uri, dbtable, flags)
325
326 4.1. www_authenticate(realm, table [, method])
327
328 Name alias: www_authorize(realm, table)
329
330 The function verifies credentials according to RFC2617. If the
331 credentials are verified successfully then the function will succeed
332 and mark the credentials as authorized (marked credentials can be later
333 used by some other functions). If the function was unable to verify the
334 credentials for some reason then it will fail and the script should
335 call www_challenge which will challenge the user again.
336
337 Negative codes may be interpreted as follows:
338 * -1 (generic error) - Bad credentials , couldn't parse credentials ,
339 no memory left , couldn't fetch from table , couldn't get realm or
340 some generic error occurred and no reply was sent out;
341 * -2 (invalid password) - wrong password;
342 * -3 (invalid user) - authentication user does not exist.
343 * -4 (nonce expired) - the nonce has expired
344 * -5 (no credentials) - request does not contain an Authorization
345 header with the correct realm.
346 * -6 (nonce reused) - the nonce has already been used to authenticate
347 a previous request
348 * -8 (authuser mismatch) - depending on the method, the From/To/RURI
349 user does not match the authentication user (see auth_check()
350 function).
351
352 Meaning of the parameters is as follows:
353 * realm - Realm is an opaque string that the user agent should
354 present to the user so he can decide what username and password to
355 use. Usually this is domain of the host the server is running on.
356 It must not be empty string “”. In case of REGISTER requests To
357 header field domain (e.g., variable $td) can be used (because this
358 header field represents the user being registered), for all other
359 messages From header field domain can be used (e.g., variable $fd).
360 The string may contain pseudo variables.
361 * table - Table to be used to lookup usernames and passwords (usually
362 subscribers table).
363 * method - the method to be used for authentication. This parameter
364 is optional and if not set is the first "word" on the request-line.
365
366 This function can be used from REQUEST_ROUTE.
367
368 Example 1.11. www_authorize usage
369 ...
370 if (!www_authorize("kamailio.org", "subscriber")) {
371 www_challenge("kamailio.org", "1");
372 };
373 ...
374
375 4.2. www_authorize(realm, table)
376
377 It is same function as www_authenticate(realm, table). This name is
378 kept for backward compatibility, since it was named this way first time
379 by it actually does user authentication.
380
381 4.3. proxy_authenticate(realm, table)
382
383 Name alias: proxy_authorize(realm, table)
384
385 The function verifies credentials according to RFC2617. If the
386 credentials are verified successfully then the function will succeed
387 and mark the credentials as authorized (marked credentials can be later
388 used by some other functions). If the function was unable to verify the
389 credentials for some reason then it will fail and the script should
390 call proxy_challenge which will challenge the user again.
391
392 Negative return codes have the same meaning as for www_authenticate().
393
394 Meaning of the parameters is as follows:
395 * realm - Realm is an opaque string that the user agent should
396 present to the user so he can decide what username and password to
397 use. Usually this is domain of the host the server is running on.
398 It must not be empty string “”. Apart of a static string, typical
399 value is From header field domain (e.g., variable $fd).
400 If an empty string “” is used then the server will generate it from
401 the request. From header field domain will be used as realm.
402 The string may contain pseudo variables.
403 * table - Table to be used to lookup usernames and passwords (usually
404 subscribers table).
405
406 This function can be used from REQUEST_ROUTE.
407
408 Example 1.12. proxy_authorize usage
409 ...
410 if (!proxy_authorize("$fd", "subscriber)) {
411 proxy_challenge("$fd", "1"); # Realm will be autogenerated
412 };
413 ...
414
415 4.4. proxy_authorize(realm, table)
416
417 It is same function as proxy_authenticate(realm, table). This name is
418 kept for backward compatibility, since it was named this way first time
419 but it actually does user authentication.
420
421 4.5. auth_check(realm, table, flags)
422
423 The function combines the functionalities of www_authenticate and
424 proxy_authenticate, first being executed if the SIP request is a
425 REGISTER, the second for the rest.
426
427 In addition, a matter of flags parameter value, the function checks if
428 authentication username matches From/To header username, and
429 Request-URI in case of PUBLISH.
430
431 Negative return codes have the same meaning as for www_authenticate().
432
433 Meaning of the parameters is as follows:
434 * realm - Realm is an opaque string that the user agent should
435 present to the user so he can decide what username and password to
436 use. Usually this is domain of the host the server is running on.
437 It must not be empty string “”. Apart of a static string, typical
438 value is From header field domain (e.g., variable $fd).
439 The string may contain pseudo variables.
440 * table - Table to be used to lookup usernames and passwords (usually
441 subscribers table).
442 The string may contain pseudo variables.
443 * flags - set of flags to control the behaviour of the function. If
444 it is 1, then the function will check to see if the authentication
445 username matches either To or From header username. REGISTER
446 requests: From and To must match the authentication user. PUBLISH
447 requests: From, To and Request-URI must match the authentication
448 user. All other requests: From header must match the authentication
449 user. If bit 2 is set as well (flags==3), the ID check is skipped
450 for INVITE, BYE, PRACK, UPDATE, MESSAGE - these requests can come
451 with anonymous caller id. If set to 0, then all user checks are
452 skipped.
453 Additionally all domains in the checked URIs and the realm in the
454 authentication header will be checked to match the provided realm
455 parameter.
456 The string may contain pseudo variables.
457
458 This function can be used from REQUEST_ROUTE.
459
460 Example 1.13. auth_check usage
461 ...
462 if (!auth_check("$fd", "subscriber", "1")) {
463 auth_challenge("$fd", "1");
464 exit;
465 }
466 ...
467
468 4.6. is_subscriber(uri, dbtable, flags)
469
470 The function checks if there is a subscriber corresponding to the AoR
471 in uri parameter. It uses same database connection as for
472 authentication functions.
473
474 In addition, if the subscriber record is found, then the
475 load_credentials attributes are loaded. A use case can be loading the
476 credential attributes for callee.
477
478 Meaning of the parameters is as follows:
479 * uri - a valid SIP URI value to identify the subscriber. The string
480 may contain pseudo variables.
481 * dbtable - Table to be used to lookup username and domain from URI
482 (usually subscriber table). The string may contain pseudo
483 variables.
484 * flags - set of flags to control the behaviour of the function. If
485 1st bit is set, then the function will use the domain part of the
486 URI to perform the database table search. If 2nd bit is set, then
487 the credentials are not loaded in variables (a simple check if
488 subscriber exists).
489 The parameter may be a pseudo variable.
490
491 This function can be used from ANY_ROUTE.
492
493 Example 1.14. is_subscriber usage
494 ...
495 if (!is_subscriber("$ru", "subscriber", "3")) {
496 # callee is not a local subscriber
497 ...
498 }
499 ...