| 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 |
... |