Debian Codegraph @

src/modules/auth/README

raw
1 The Auth Module
2
3 Jan Janak
4
5 FhG Fokus
6 <[email protected]>
7
8 Juha Heinanen
9
10 TutPro Inc
11 <[email protected]>
12
13 Daniel-Constantin Mierla
14
15 asipto.com
16 <[email protected]>
17
18 Copyright © 2002, 2003 FhG FOKUS
19 __________________________________________________________________
20
21 Table of Contents
22
23 1. Admin Guide
24
25 1. Overview
26 2. Dependencies
27 3. Parameters
28
29 3.1. auth_checks_register (flags)
30 3.2. auth_checks_no_dlg (flags)
31 3.3. auth_checks_in_dlg (flags)
32 3.4. qop (string)
33 3.5. nonce_count (boolean)
34 3.6. one_time_nonce (boolean)
35 3.7. nid_pool_no (integer)
36 3.8. nc_array_size (integer)
37 3.9. nc_array_order (integer)
38 3.10. otn_in_flight_no (integer)
39 3.11. otn_in_flight_order (integer)
40 3.12. secret (string)
41 3.13. nonce_expire (integer)
42 3.14. nonce_auth_max_drift (integer)
43 3.15. force_stateless_reply (boolean)
44 3.16. realm_prefix (string)
45 3.17. use_domain (boolean)
46 3.18. algorithm (string)
47 3.19. add_authinfo_hdr (boolean)
48
49 4. Functions
50
51 4.1. consume_credentials()
52 4.2. has_credentials(realm)
53 4.3. www_challenge(realm, flags)
54 4.4. proxy_challenge(realm, flags)
55 4.5. auth_challenge(realm, flags)
56 4.6. pv_www_authenticate(realm, passwd, flags [, method])
57 4.7. pv_proxy_authenticate(realm, passwd, flags)
58 4.8. pv_auth_check(realm, passwd, flags, checks)
59 4.9. auth_get_www_authenticate(realm, flags, pvdest)
60 4.10. auth_algorithm(algorithm)
61
62 List of Examples
63
64 1.1. Setting the auth_checks_register module parameter
65 1.2. qop example
66 1.3. nonce_count example
67 1.4. one_time_nonce example
68 1.5. nid_pool_no example
69 1.6. nc_array_size example
70 1.7. nc_array_order example
71 1.8. otn_in_flight_no example
72 1.9. otn_in_flight_order example
73 1.10. Setting secret module parameter
74 1.11. nonce_expire example
75 1.12. nonce_auth_max_drift example
76 1.13. force_stateless_reply example
77 1.14. realm_prefix parameter example
78 1.15. force_stateless_reply example
79 1.16. algorithm example
80 1.17. add Authentication-Info header example
81 1.18. consume_credentials example
82 1.19. consume_credentials example
83 1.20. www_challenge usage
84 1.21. proxy_challenge usage
85 1.22. auth_challenge usage
86 1.23. pv_www_authenticate usage
87 1.24. pv_proxy_authenticate usage
88 1.25. pv_auth_check usage
89 1.26. auth_get_www_authenticate usage
90 1.27. auth_algorithm example
91
92 Chapter 1. Admin Guide
93
94 Table of Contents
95
96 1. Overview
97 2. Dependencies
98 3. Parameters
99
100 3.1. auth_checks_register (flags)
101 3.2. auth_checks_no_dlg (flags)
102 3.3. auth_checks_in_dlg (flags)
103 3.4. qop (string)
104 3.5. nonce_count (boolean)
105 3.6. one_time_nonce (boolean)
106 3.7. nid_pool_no (integer)
107 3.8. nc_array_size (integer)
108 3.9. nc_array_order (integer)
109 3.10. otn_in_flight_no (integer)
110 3.11. otn_in_flight_order (integer)
111 3.12. secret (string)
112 3.13. nonce_expire (integer)
113 3.14. nonce_auth_max_drift (integer)
114 3.15. force_stateless_reply (boolean)
115 3.16. realm_prefix (string)
116 3.17. use_domain (boolean)
117 3.18. algorithm (string)
118 3.19. add_authinfo_hdr (boolean)
119
120 4. Functions
121
122 4.1. consume_credentials()
123 4.2. has_credentials(realm)
124 4.3. www_challenge(realm, flags)
125 4.4. proxy_challenge(realm, flags)
126 4.5. auth_challenge(realm, flags)
127 4.6. pv_www_authenticate(realm, passwd, flags [, method])
128 4.7. pv_proxy_authenticate(realm, passwd, flags)
129 4.8. pv_auth_check(realm, passwd, flags, checks)
130 4.9. auth_get_www_authenticate(realm, flags, pvdest)
131 4.10. auth_algorithm(algorithm)
132
133 1. Overview
134
135 This is a generic module that itself doesn't provide all functions
136 necessary for authentication but provides functions that are needed by
137 all other authentication related modules (so called authentication
138 backends).
139
140 We decided to divide the authentication code into several modules
141 because there are now more than one backends (currently database
142 authentication and radius are supported). This allows us to create
143 separate packages so users can install and load only the required
144 functionality. This also allows us to avoid unnecessary dependencies in
145 the binary packages.
146
147 2. Dependencies
148
149 The following modules must be loaded before this module:
150 * sl - stateless reply.
151
152 3. Parameters
153
154 3.1. auth_checks_register (flags)
155 3.2. auth_checks_no_dlg (flags)
156 3.3. auth_checks_in_dlg (flags)
157 3.4. qop (string)
158 3.5. nonce_count (boolean)
159 3.6. one_time_nonce (boolean)
160 3.7. nid_pool_no (integer)
161 3.8. nc_array_size (integer)
162 3.9. nc_array_order (integer)
163 3.10. otn_in_flight_no (integer)
164 3.11. otn_in_flight_order (integer)
165 3.12. secret (string)
166 3.13. nonce_expire (integer)
167 3.14. nonce_auth_max_drift (integer)
168 3.15. force_stateless_reply (boolean)
169 3.16. realm_prefix (string)
170 3.17. use_domain (boolean)
171 3.18. algorithm (string)
172 3.19. add_authinfo_hdr (boolean)
173
174 3.1. auth_checks_register (flags)
175
176 See description of parameter auth_checks_in_dlg.
177
178 3.2. auth_checks_no_dlg (flags)
179
180 See description of parameter auth_checks_in_dlg.
181
182 3.3. auth_checks_in_dlg (flags)
183
184 These three module parameters control which optional integrity checks
185 will be performed on the SIP message carrying digest response during
186 SIP MD5 digest authentication. auth_checks_register controls integrity
187 checks to be performed on REGISTER messages, auth_checks_no_dlg
188 controls which optional integrity checks will be performed on SIP
189 requests that have no To header field or no To tag (in other words the
190 requests either establishing or outside dialogs). auth_checks_in_dlg
191 controls which integrity checks will be performed on SIP requests
192 within dialogs, such as BYE or re-INVITE. The default value for all
193 three parameters is 0 (old behaviour, no extra checks). The set of
194 integrity checks that can be performed on REGISTERs is typically
195 different from sets of integrity checks that can be performed for other
196 SIP request types, hence we have three independent module parameters.
197
198 Without the extra checks the nonce will protect only against expired
199 values. Some reply attacks are still possible in the expire "window". A
200 possible workaround is to always force qop authentication and always
201 check the uri from the authorization header, but this would not work if
202 an upstream proxy rewrites the uri and it will also not work with a lot
203 of UA implementations.
204
205 In this case the nonce value will be used only to hold the expire time
206 (see nonce_expire) and an MD5 over it and some secret (the MD5 is used
207 to make sure that nobody tampers with the nonce expire time).
208
209 When the extra checks are enabled, the nonce will include an extra MD5
210 over the selected part/parts of the message (see below) and some other
211 secret. This will be used to check if the selected part of the message
212 is the same when an UA tries to reuse the nonce, thus protecting or
213 severely limiting reply attacks.
214
215 The possible flag values for all three parameters are:
216 * 1 for checking if the message URI changed (uses the whole URI)
217 * 2 for checking the callid
218 * 4 for checking the From tag
219 * 8 for checking the source IP address (see nonce.h).
220
221 As an example setting auth_checks_register to 3 would check if the
222 callid or the request uri changed from the REGISTER message for which
223 the original nonce was generated (this would allow nonce reuse only
224 within the same UA and for the expire time). Note that enabling the
225 extra checks will limit nonce caching by UAs, requiring extra
226 challenges and roundtrips, but will provide much better protection.
227
228 Warning
229
230 Do not enable the from tag check (4) for REGISTERs
231 (auth_checks_register) and out-of-dialog messages (auth_checks_no_dlg)
232 unless you are sure that all your user agents do not change the from
233 tag when challenged. Some user agents will also change the callid when
234 the challenged request is not in-dialog, so avoid enabling the callid
235 check (2) for messages that are not part of a dialog
236 (auth_checks_no_dlg). In some rare case this will also have to be done
237 for REGISTERs.
238
239 When the secret parameter is set and the extra checks are enabled, the
240 first half of the secret will be used for the expire time MD5 and the
241 other half for the extra checks MD5, so make sure you have a long
242 secret (32 chars or longer are recommended).
243
244 Example 1.1. Setting the auth_checks_register module parameter
245 ...
246 # For REGISTER requests we hash the Request-URI, Call-ID, and source IP of the
247 # request into the nonce string. This ensures that the generated credentials
248 # cannot be used with another registrar, user agent with another source IP
249 # address or Call-ID. Note that user agents that change Call-ID with every
250 # REGISTER message will not be able to register if you enable this.
251 modparam("auth", "auth_checks_register", 11)
252
253 # For dialog-establishing requests (such as the original INVITE, OPTIONS, etc)
254 # we hash the Request-URI and source IP. Hashing Call-ID and From tags takes
255 # some extra precaution, because these checks could render some UA unusable.
256 modparam("auth", "auth_checks_no_dlg", 9)
257
258 # For mid-dialog requests, such as re-INVITE, we can hash source IP and
259 # Request-URI just like in the previous case. In addition to that we can hash
260 # Call-ID and From tag because these are fixed within a dialog and are
261 # guaranteed not to change. This settings effectively restrict the usage of
262 # generated credentials to a single user agent within a single dialog.
263 modparam("auth", "auth_checks_in_dlg", 15)
264
265 ...
266
267 3.4. qop (string)
268
269 If set, enable qop for challenges: each challenge will include a qop
270 parameter. This is the recommended way, but some older non rfc3261
271 compliant UAs might get confused and might not authenticate properly if
272 qop is enabled.
273
274 Enabling qop together with nonce_count will provide extra-security
275 (protection against replay attacks) while still allowing credentials
276 caching at the UA side and thus not compromising performance.
277
278 The possible values are: "auth", "auth-int" and "" (unset).
279
280 The default value is not-set ("").
281
282 See also: nonce_count.
283
284 Example 1.2. qop example
285 ...
286 modparam("auth", "qop", "auth") # set qop=auth
287 ...
288
289 3.5. nonce_count (boolean)
290
291 If enabled the received nc value is remembered and checked against the
292 older value (for a successful authentication the received nc must be
293 greater than the previously received one, see rfc2617 for more
294 details). This will provide protection against replay attacks while
295 still allowing credentials caching at the UA side.
296
297 It depends on qop being enabled (if qop is not enabled, the challenges
298 won't include qop and so the UA will probably not include the qop or nc
299 parameters in its response).
300
301 If a response doesn't include qop or nc (for example obsolete UAs that
302 don't support them) the response will be checked according to the other
303 enabled nonce checks, in this order: one_time_nonce and auth_checks_*.
304 If a response includes nc only the normal nonce_expire checks and the
305 nonce_count checks will be performed, all the other checks will be
306 ignored.
307
308 The nonce_count checks work by tracking a limited number of nonces. The
309 maximum number of tracked nonces is set using the nc_array_size or
310 nc_array_order parameters. If this number is exceeded, older entries
311 will be overwritten. As long as the maximum rate of challengeable
312 messages per average response time is lower than nc_array_size, the
313 nonce_count checks should work flawlessly. For optimum performance
314 (maximum reuse of cache credentials) nc_array_size divided by
315 nid_pool_no should be lower than the message rate multiplied by the
316 desired nonce_expire.
317
318 The maximum accepted nc value is 255. If nc becomes greater than this,
319 the nonce will be considered stale and the UA will be re-challenged.
320
321 Note: nonce_count should be enabled only in stateful mode (a
322 transaction should be created prior to the authentication check to
323 absorb possible retransmissions and all the replies should be sent
324 statefully, using t_reply()). If nonce_count and the authentication
325 checks are used in the stateless mode then all retransmissions will be
326 challenged.
327
328 The default value is 0 (off).
329
330 See also: qop, nc_array_size, nc_array_order, nid_pool_no,
331 nonce_expire. one_time_nonce.
332
333 Example 1.3. nonce_count example
334 ...
335 modparam("auth", "nonce_count", 1) # enable nonce_count support
336 modparam("auth", "qop", "auth") # enable qop=auth
337
338 ....
339 route{
340 ...
341 # go stateful and catch retransmissions
342 if (!t_newtran()) {
343 xlog("L_NOTICE", "Failed to create new transaction\n");
344 drop;
345 };
346 if (method=="REGISTER"){
347 if (!www_authenticate("test", "credentials")){
348 # reply must be sent with t_reply because the
349 # transaction is already created at this point
350 # (we are in "stateful" mode)
351 if ($? == -2){
352 t_reply("500", "Internal Server Error");
353 }else if ($? == -3){
354 t_reply("400", "Bad Request");
355 }else{
356 if ($digest_challenge)
357 append_to_reply("%$digest_challenge");
358 t_reply("401", "Unauthorized");
359 }
360 drop;
361 }
362 if (!save_noreply("location")) {
363 t_reply("400", "Invalid REGISTER Request");
364 drop;
365 }
366 append_to_reply("%$contact");
367 t_reply("$code", "$reason"); # no %, avps are used directly
368 drop;
369 }else{
370 if (!proxy_authenticate("my_realm", "credentials")){
371 if ($? == -2){
372 t_reply("500", "Internal Server Error");
373 }else if ($? == -3){
374 t_reply("400", "Bad Request");
375 }else{
376 if ($digest_challenge)
377 append_to_reply("%$digest_challenge");
378 t_reply("401", "Unauthorized");
379 }
380 drop;
381 }
382 }
383 ...
384
385 3.6. one_time_nonce (boolean)
386
387 If set to 1 nonce reuse is disabled: each nonce is allowed only once,
388 in the first response to a challenge. All the messages will be
389 challenged, even retransmissions. Stateful mode should be used, to
390 catch retransmissions before the authentication checks (using
391 t_newtran() before the authentication checks and sending all the
392 replies with t_reply()).
393
394 one_time_nonce provides enhanced replay protections at the cost of
395 invalidating UA side credentials caching, challenging every message
396 (and thus generating extra messages and extra round-trips) and
397 requiring stateful mode. In general qop and nonce_count should be
398 prefered (if possible) with fallback to auth_checks_*. Due to the
399 disadvantages listed above, one_time_nonce should be used only if the
400 extra checks provided by auth_checks_register, auth_checks_no_dlg and
401 auth_checks_in_dlg are deemed insufficient for a specific setup.
402
403 Compared to nonce_count, one_time_nonce provides the same protection,
404 but at a higher message cost. The only advantages are that it works
405 with user agents that do not support qop and nc and that it uses less
406 memory for the same supported number of maximum in-flight nonces (by a
407 factor of 8). one_time_nonce can be used as fallback from nonce_count,
408 when the UA doesn't support nc (it happens automatically when both of
409 them are enabled).
410
411 Like nonce_count, one_time_nonce works by tracking a limited number of
412 nonces. The maximum number of tracked nonces is set using the
413 otn_in_flight_no or otn_in_flight_order parameters. If this number is
414 exceeded, older entries will be overwritten. As long as the maximum
415 rate of challengeable messages per average response time is lower than
416 otn_in_flight_no, the one_time_nonce checks should work flawlessly.
417
418 The default value is 0 (off).
419
420 See also: otn_in_flight_no, otn_in_flight_order, nid_pool_no and
421 nonce_count.
422
423 Example 1.4. one_time_nonce example
424 ...
425 modparam("auth", "one_time_nonce", 1)
426 # Note: stateful mode should be used, see the nonce_count example
427 ...
428
429 3.7. nid_pool_no (integer)
430
431 Controls the number of partitions for the nonce_count and
432 one_time_nonce arrays (it's common to both of them to reduce the nonce
433 size).
434
435 Instead of using single arrays for keeping nonce state, these arrays
436 can be divided into more partitions. Each Kamailio process is assigned
437 to one of these partitions, allowing for higher concurrency on
438 multi-CPU machines. Besides increasing performance, increasing
439 nid_pool_no has also a negative effect: it could decrease the maximum
440 supported in-flight nonces in certain conditions. In the worst case,
441 when only one Kamailio process receives most of the traffic (e.g. very
442 busy tcp connection between two proxies), the in-flight nonces could be
443 limited to the array size (nc_array_size for nonce_count or
444 otn_in_flight_no for one_time_nonce) divided by the partitions number
445 (nid_pool_no). However for normal traffic, when the process receiving a
446 message is either random or chosen in a round-robin fashion the maximum
447 in-flight nonces number will be very little influenced by nid_pool_no
448 (the messages will be close to equally distributed to processes using
449 different partitions).
450
451 nid_pool_no value should be one of: 1, 2, 4, 8, 16, 32 or 64 (the
452 maximum value is 64 and all values should be of the form 2^k or else
453 they will be rounded down to 2^k).
454
455 The default value is 1.
456
457 See also: nonce_count, one_time_nonce, nc_array_size and
458 otn_in_flight_no.
459
460 Example 1.5. nid_pool_no example
461 ...
462 modparam("auth", "nid_pool_no", 4)
463 ...
464
465 3.8. nc_array_size (integer)
466
467 Maximum number of in-flight nonces for nonce_count. It represents the
468 maximum nonces for which state will be kept. When this number is
469 exceeded, state for the older nonces will be discarded to make space
470 for new ones (see nonce_count for more details).
471
472 The value should be of the form 2^k. If it's not it will be rounded
473 down to 2^k (for example a value of 1000000 will be rounded down to
474 2^19=524288). nc_array_order can be used to directly specify the power
475 of 2 (e.g. nc_array_order set to 20 is equivalent to nc_array_size set
476 to 1048576).
477
478 The memory used to keep the nonce state will be nc_array_size in bytes.
479
480 The default value is 1048576 (1M in-flight nonces, using 1Mb memory).
481
482 See also: nonce_count and nid_pool_no.
483
484 Example 1.6. nc_array_size example
485 ...
486 modparam("auth", "nc_array_size", 4194304) # 4Mb
487 ...
488
489 3.9. nc_array_order (integer)
490
491 Equivalent to nc_array_size, but instead of directly specifying the
492 size, its value is the power at which 2 should be raised
493 (log2(nc_array_size)).
494
495 nc_array_size = 2^nc_array_order. For more details see nc_array_size.
496
497 The default value is 20 (1M in-flight nonces, using 1Mb memory).
498
499 See also: nonce_count, nc_array_size and nid_pool_no.
500
501 Example 1.7. nc_array_order example
502 ...
503 modparam("auth", "nc_array_order", 22) # 4Mb
504 ...
505
506 3.10. otn_in_flight_no (integer)
507
508 Maximum number of in-flight nonces for one_time_nonce. It represents
509 the maximum number of nonces remembered for the one-time-nonce check.
510 When this number is exceeded, information about older nonces will be
511 discarded and overwritten with information about the new generated ones
512 (see one_time_nonce for more details).
513
514 The value should be of the form 2^k. If it's not it will be rounded
515 down to 2^k (for example a value of 1000000 will be rounded down to
516 2^19=524288). otn_in_flight_no can be used to directly specify the
517 power of 2 (e.g. otn_in_flight_order set to 19 is equivalent to
518 otn_in_fligh_number set to 524288).
519
520 The memory used to keep the nonce information will be the
521 otn_in_flight_no divided by 8 (only 1 bit of state is kept per nonce).
522
523 The default value is 1048576 (1M in-flight nonces, using 128Kb memory).
524
525 See also: one_time_nonce and nid_pool_no.
526
527 Example 1.8. otn_in_flight_no example
528 ...
529 modparam("auth", "otn_in_flight_no", 8388608) # 8 Mb (1Mb memory)
530 ...
531
532 3.11. otn_in_flight_order (integer)
533
534 Equivalent to otn_in_flight_no, but instead of directly specifying the
535 size, its value is the power at which 2 should be raised
536 (log2(otn_in_flight_no)).
537
538 otn_in_flight_no = 2^otn_in_flight_order. For more details see
539 otn_in_flight_order.
540
541 The default value is 20 (1M in-flight nonces, using 128Kb memory).
542
543 See also: one_time_nonce, otn_in_flight_no and nid_pool_no.
544
545 Example 1.9. otn_in_flight_order example
546 ...
547 modparam("auth", "otn_in_flight_order", 23) # 8 Mb (1Mb memory)
548 ...
549
550 3.12. secret (string)
551
552 Secret phrase used to calculate the nonce value used to challenge the
553 client for authentication.
554
555 If you use multiple servers in your installation, and would like to
556 authenticate on the second server against the nonce generated at the
557 first one, it is necessary to explicitly set the secret to the same
558 value on all servers. However, as the use of a shared (and fixed)
559 secret as nonce is insecure, it is much better is to stay with the
560 default. Any clients should send the authenticated request to the
561 server that issued the challenge.
562
563 Default value is randomly generated string.
564
565 Example 1.10. Setting secret module parameter
566 ...
567 modparam("auth", "secret", "johndoessecretphrase")
568 ...
569
570 3.13. nonce_expire (integer)
571
572 Nonces have limited lifetime. After a given period of time nonces will
573 be considered invalid. This is to protect replay attacks. Credentials
574 containing a stale nonce will be not authorized, but the user agent
575 will be challenged again. This time the challenge will contain stale
576 parameter which will indicate to the client that it doesn't have to
577 disturb user by asking for username and password, it can recalculate
578 credentials using existing username and password.
579
580 The value is in seconds and default value is 300 seconds.
581
582 Example 1.11. nonce_expire example
583 ...
584 modparam("auth", "nonce_expire", 600) # Set nonce_expire to 600s
585 ...
586
587 3.14. nonce_auth_max_drift (integer)
588
589 Maximum difference in seconds between a nonce creation time and the
590 current time, if the nonce creation time appears to be in the future.
591
592 In some cases, like shortly after a system time backward adjustment or
593 when the current proxy is part of a cluster which is not
594 time-synchronized, it's possible to receive a nonce with creation time
595 in the future. In this case if the difference is greater than
596 nonce_auth_max_drift seconds, consider the nonce stale and re-challenge
597 (otherwise after a dramatic time change backwards, it might happen that
598 some previously generated nonces will be valid for too much time).
599
600 The default value is 3 seconds
601
602 See also: nonce_expire.
603
604 Example 1.12. nonce_auth_max_drift example
605 ...
606 modparam("auth", "nonce_auth_max_drift", 1) # set max drift to 1 s
607 ...
608
609 3.15. force_stateless_reply (boolean)
610
611 If set to 1, www_challenge() and proxy_challenge() functions send reply
612 statelessly no matter if transaction exists or not. If set to 0
613 (default), reply is sent statefully if transaction exists and
614 statelessly otherwise.
615
616 Example 1.13. force_stateless_reply example
617 ...
618 modparam("auth", "force_stateless_reply", 1)
619 ...
620
621 3.16. realm_prefix (string)
622
623 Prefix to be automatically stripped from the realm. As an alternative
624 to SRV records (not all SIP clients support SRV lookup), a subdomain of
625 the master domain can be defined for SIP purposes (like
626 sip.mydomain.net pointing to same IP address as the SRV record for
627 mydomain.net). By ignoring the realm_prefix “sip.”, at authentication,
628 sip.example.com will be equivalent to example.com .
629
630 Default value is empty string.
631
632 Example 1.14. realm_prefix parameter example
633 modparam("auth", "realm_prefix", "sip.")
634
635 3.17. use_domain (boolean)
636
637 If set to 1, pv_auth_check() uses domain parts of the URIs to check
638 user identity.
639
640 Example 1.15. force_stateless_reply example
641 ...
642 modparam("auth", "use_domain", 1)
643 ...
644
645 3.18. algorithm (string)
646
647 Configure hash algorithm used for digest authentication. Possible
648 values are "MD5", "SHA-256", "SHA-512" or "SHA-512-256". If left empty
649 MD5 is used. If specified, the specified algorithm is used and is also
650 put in the 'algorithm' field of the challenge header.
651
652 Warning: SHA-256/512 hash values take twice or more the space of MD5
653 hash values. So a buffer overflow might occur if this option is used in
654 combination with another auth_* module that does not allocate at least
655 enough (65 or 129) bytes to store hash values. SHA-256/512 can safely
656 be used with the module auth_db as it allocates 256 bytes to store HA1
657 values.
658
659 Example 1.16. algorithm example
660 ...
661 modparam("auth", "algorithm", "SHA-256")
662 ...
663
664 3.19. add_authinfo_hdr (boolean)
665
666 Should an Authentication-Info header be added on 200 OK responses? The
667 Authentication-Info header offers mutual authentication. The server
668 proves to the client that it knows the user's secret.
669
670 The header also includes the next nonce which may be used by the client
671 in a future request. If one_time_nonce is enabled, a new nonce is
672 calculated for the next nonce. Otherwise the current nonce is used for
673 the next nonce.
674
675 The default value is 0 (no).
676
677 Example 1.17. add Authentication-Info header example
678 ...
679 modparam("auth", "add_authinfo_hdr", yes)
680 ...
681
682 4. Functions
683
684 4.1. consume_credentials()
685 4.2. has_credentials(realm)
686 4.3. www_challenge(realm, flags)
687 4.4. proxy_challenge(realm, flags)
688 4.5. auth_challenge(realm, flags)
689 4.6. pv_www_authenticate(realm, passwd, flags [, method])
690 4.7. pv_proxy_authenticate(realm, passwd, flags)
691 4.8. pv_auth_check(realm, passwd, flags, checks)
692 4.9. auth_get_www_authenticate(realm, flags, pvdest)
693 4.10. auth_algorithm(algorithm)
694
695 4.1. consume_credentials()
696
697 This function removes previously authorized credential headers from the
698 message being processed by the server. That means that the downstream
699 message will not contain credentials there were used by this server.
700 This ensures that the proxy will not reveal information about
701 credentials used to downstream elements and also the message will be a
702 little bit shorter. The function must be called after www_authorize,
703 proxy_authorize, www_authenticate or proxy_authenticate.
704
705 Example 1.18. consume_credentials example
706 ...
707 if (www_authenticate("realm", "subscriber")) {
708 consume_credentials();
709 }
710 ...
711
712 4.2. has_credentials(realm)
713
714 This function returns true if the request has Authorization or
715 Proxy-Authorization header with provided realm. The parameter can be
716 string with pseudo-variables.
717
718 Example 1.19. consume_credentials example
719 ...
720 if (has_credentials("myrealm")) {
721 ...
722 }
723 ...
724
725 4.3. www_challenge(realm, flags)
726
727 The function challenges a user agent. It will generate a WWW-Authorize
728 header field containing a digest challenge, it will put the header
729 field into a response generated from the request the server is
730 processing and send the 401 reply. Upon reception of such a reply the
731 user agent should compute credentials and retry the request. For more
732 information regarding digest authentication see RFC2617. See module
733 parameter force_stateless_reply regarding sending of the reply.
734
735 Meaning of the parameters is as follows:
736 * realm - Realm is an opaque string that the user agent should
737 present to the user so he can decide what username and password to
738 use. Usually this is domain of the host the server is running on.
739 It must not be empty string “”. In case of REGISTER requests, the
740 To header field domain (e.g., variable $td) can be used (because
741 this header field represents the user being registered), for all
742 other messages From header field domain can be used (e.g., variable
743 $fd).
744 The string may contain pseudo variables.
745 * flags - Value of this parameter can be a bitmask of following:
746 + 1 - build challenge header with qop=auth
747 + 2 - build challenge header with qop=auth-int
748 + 4 - do not send '500 Internal Server Error' reply
749 automatically in failure cases (error code is returned to
750 config)
751 + 16 - build challenge header with stale=true
752
753 This function can be used from REQUEST_ROUTE.
754
755 Example 1.20. www_challenge usage
756 ...
757 if (!www_authenticate("$td", "subscriber")) {
758 www_challenge("$td", "1");
759 exit;
760 }
761 ...
762
763 4.4. proxy_challenge(realm, flags)
764
765 The function challenges a user agent. It will generate a
766 Proxy-Authorize header field containing a digest challenge, it will put
767 the header field into a response generated from the request the server
768 is processing and send the 407 reply. Upon reception of such a reply
769 the user agent should compute credentials and retry the request. For
770 more information regarding digest authentication see RFC2617. See
771 module parameter force_stateless_reply regarding sending of the reply.
772
773 Meaning of the parameters is the same as for function
774 www_challenge(realm, flags)
775
776 This function can be used from REQUEST_ROUTE.
777
778 Example 1.21. proxy_challenge usage
779 ...
780 if (!proxy_authenticate("$fd", "subscriber")) {
781 proxy_challenge("$fd", "1");
782 exit;
783 }
784 ...
785
786 4.5. auth_challenge(realm, flags)
787
788 The function challenges a user agent for authentication. It combines
789 the functions www_challenge() and proxy_challenge(), by calling
790 internally the first one for REGISTER requests and the second one for
791 the rest of other request types. In other words, it challenges for
792 authentication by sending a 401 reply for REGISTER requests and 407
793 reply for the other types of SIP requests.
794
795 Meaning of the parameters the same as for function www_challenge(realm,
796 flags)
797
798 This function can be used from REQUEST_ROUTE.
799
800 Example 1.22. auth_challenge usage
801 ...
802 if (!auth_check("$fd", "subscriber", "1")) {
803 auth_challenge("$fd", "1");
804 exit;
805 }
806 ...
807
808 4.6. pv_www_authenticate(realm, passwd, flags [, method])
809
810 The function verifies credentials according to RFC2617. If the
811 credentials are verified successfully then the function will succeed
812 and mark the credentials as authorized (marked credentials can be later
813 used by some other functions). If the function was unable to verify the
814 credentials for some reason then it will fail and the script should
815 call www_challenge which will challenge the user again.
816
817 Negative codes may be interpreted as follows:
818 * -1 (generic error) - some generic error occurred and no reply was
819 sent out
820 * -2 (invalid password) - wrong password
821 * -4 (nonce expired) - the nonce has expired
822 * -5 (no credentials) - request does not contain an Authorization
823 header with the correct realm
824 * -6 (nonce reused) - the nonce has already been used to authenticate
825 a previous request
826
827 Meaning of the parameters is as follows:
828 * realm - Realm is an opaque string that the user agent should
829 present to the user so he can decide what username and password to
830 use. Usually this is domain of the host the server is running on.
831 It must not be empty string “”. In case of REGISTER requests To
832 header field domain (e.g., variable $td) can be used (because this
833 header field represents a user being registered), for all other
834 messages From header field domain can be used (e.g., variable $fd).
835 The string may contain pseudo variables.
836 * passwd - the password to be used for authentication. Can contain
837 config variables. The Username is taken from Auth header.
838 * flags - the value of this parameter can be a bitmask of following:
839 + 1 - the value of password parameter is HA1 format
840 + 2 - build challenge header with no qop and add it to avp
841 + 4 - build challenge header with qop=auth and add it to avp
842 + 8 - build challenge header with qop=auth-int and add it to avp
843 + 16 - build challenge header with stale=true
844 + 32 - don't invalidate nc on authentication failure
845 * method - the method to be used for authentication. This parameter
846 is optional and if not set is the first "word" on the request-line.
847
848 When challenge header is built and stored in avp, append_to_reply() and
849 the sl reply functions can be used to send appropriate SIP reply to
850 challenge for authentication.
851
852 This function can be used from REQUEST_ROUTE.
853
854 Example 1.23. pv_www_authenticate usage
855 ...
856 if (!pv_www_authenticate("$td", "123abc", "0")) {
857 www_challenge("$td", "1");
858 exit;
859 }
860 ...
861
862 4.7. pv_proxy_authenticate(realm, passwd, flags)
863
864 The function verifies credentials according to RFC2617. If the
865 credentials are verified successfully then the function will succeed
866 and mark the credentials as authorized (marked credentials can be later
867 used by some other functions). If the function was unable to verify the
868 credentials for some reason then it will fail and the script should
869 call proxy_challenge which will challenge the user again. For more
870 about the negative return codes, see the above function.
871
872 Meaning of the parameters is the same as for pv_www_authenticate(realm,
873 passwd, flags)
874
875 This function can be used from REQUEST_ROUTE.
876
877 Example 1.24. pv_proxy_authenticate usage
878 ...
879 $avp(password)="xyz";
880 if (!pv_proxy_authenticate("$fd", "$avp(password)", "0")) {
881 proxy_challenge("$fd", "1");
882 exit;
883 }
884 ...
885
886 4.8. pv_auth_check(realm, passwd, flags, checks)
887
888 The function combines the functionalities of pv_www_authenticate and
889 pv_proxy_authenticate, first being executed if the SIP request is a
890 REGISTER, the second for the rest.
891
892 Meaning of the first three parameters is the same as for
893 pv_www_authenticate(realm, passwd, flags).
894
895 Parameter checks can be used to control the behaviour of the function.
896 If it is 1, then the function will check to see if the authentication
897 username matches either To or From header username, a matter of whether
898 it is for a REGISTER request or not. The parameter may be a pseudo
899 variable.
900
901 The set of possible return codes is the same than
902 pv_{www,proxy}_authenticate, with one more possible value:
903
904 -8 (auth user mismatch) - the auth user is different than the From/To
905 user
906
907 This function can be used from REQUEST_ROUTE.
908
909 Example 1.25. pv_auth_check usage
910 ...
911 $avp(password)="xyz";
912 if (!pv_auth_check("$fd", "$avp(password)", "0", "1")) {
913 auth_challenge("$fd", "1");
914 exit;
915 }
916 ...
917
918 4.9. auth_get_www_authenticate(realm, flags, pvdest)
919
920 Build WWW-Authentication header and set the resulting value in 'pvdest'
921 pseudo-variable parameter.
922
923 Meaning of the realm and flags parameters is the same as for
924 pv_www_authenticate(realm, passwd, flags)
925
926 This function can be used from ANY_ROUTE.
927
928 Example 1.26. auth_get_www_authenticate usage
929 ...
930 if (auth_get_www_authenticate("$fd", "0", "$var(wauth)")) {
931 xlog("www authenticate header is [$var(wauth)]\n");
932 }
933 ...
934
935 4.10. auth_algorithm(algorithm)
936
937 Set hash algorithm used for digest authentication thus overriding
938 algorithm parameter. Possible values are the same as those of algorithm
939 parameter. The parameter may be a pseudo variable.
940
941 Example 1.27. auth_algorithm example
942 ...
943 if($fU == "alice") {
944 $var(alg) = "SHA-256";
945 } else {
946 $var(alg) = "MD5";
947 }
948 auth_algorithm("$var(alg)");
949 if (!auth_check("$fd", "subscriber", "1")) {
950 auth_challenge("$fd", "1");
951 exit;
952 }
953 ...