| 1 |
UID Auth DB Module |
| 2 |
|
| 3 |
Jan Janak |
| 4 |
|
| 5 |
FhG Fokus |
| 6 |
<[email protected]> |
| 7 |
|
| 8 |
Jakob Schlyter |
| 9 |
|
| 10 |
<[email protected]> |
| 11 |
|
| 12 |
Copyright © 2002, 2003 FhG FOKUS |
| 13 |
__________________________________________________________________ |
| 14 |
|
| 15 |
Table of Contents |
| 16 |
|
| 17 |
1. Admin Guide |
| 18 |
|
| 19 |
1. Overview |
| 20 |
2. Dependencies |
| 21 |
3. Parameters |
| 22 |
|
| 23 |
3.1. db_url (string) |
| 24 |
3.2. user_column (string) |
| 25 |
3.3. domain_column (string) |
| 26 |
3.4. password_column (string) |
| 27 |
3.5. rpid_column (string) |
| 28 |
3.6. calculate_ha1 (integer) |
| 29 |
3.7. plain_password_column (string) |
| 30 |
3.8. password_column_2 (string) |
| 31 |
3.9. use_rpid (integer) |
| 32 |
|
| 33 |
4. Functions |
| 34 |
|
| 35 |
4.1. www_authorize(realm, table) |
| 36 |
4.2. proxy_authorize(realm, table) |
| 37 |
|
| 38 |
List of Examples |
| 39 |
|
| 40 |
1.1. db_url parameter usage |
| 41 |
1.2. user_column usage |
| 42 |
1.3. domain_column usage |
| 43 |
1.4. password_column usage |
| 44 |
1.5. rpid_column usage |
| 45 |
1.6. calculate_ha1usage |
| 46 |
1.7. plain_password_column usage |
| 47 |
1.8. password_column_2 usage |
| 48 |
1.9. use_rpidusage |
| 49 |
1.10. www_authorize usage |
| 50 |
1.11. proxy_authorize usage |
| 51 |
|
| 52 |
Chapter 1. Admin Guide |
| 53 |
|
| 54 |
Table of Contents |
| 55 |
|
| 56 |
1. Overview |
| 57 |
2. Dependencies |
| 58 |
3. Parameters |
| 59 |
|
| 60 |
3.1. db_url (string) |
| 61 |
3.2. user_column (string) |
| 62 |
3.3. domain_column (string) |
| 63 |
3.4. password_column (string) |
| 64 |
3.5. rpid_column (string) |
| 65 |
3.6. calculate_ha1 (integer) |
| 66 |
3.7. plain_password_column (string) |
| 67 |
3.8. password_column_2 (string) |
| 68 |
3.9. use_rpid (integer) |
| 69 |
|
| 70 |
4. Functions |
| 71 |
|
| 72 |
4.1. www_authorize(realm, table) |
| 73 |
4.2. proxy_authorize(realm, table) |
| 74 |
|
| 75 |
1. Overview |
| 76 |
|
| 77 |
This module contains all authentication related functions that need the |
| 78 |
access to the database. This module should be used together with auth |
| 79 |
module, it cannot be used independently because it depends on the |
| 80 |
module. Select this module if you want to use database to store |
| 81 |
authentication information like subscriber usernames and passwords. If |
| 82 |
you want to use radius authentication, then use auth_radius instead. |
| 83 |
|
| 84 |
2. Dependencies |
| 85 |
|
| 86 |
The module depends on the following modules (in other words the listed |
| 87 |
modules must be loaded before this module): |
| 88 |
* auth. Generic authentication functions. |
| 89 |
* database. Any database module (currently mysql, postgres, dbtext) |
| 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. rpid_column (string) |
| 98 |
3.6. calculate_ha1 (integer) |
| 99 |
3.7. plain_password_column (string) |
| 100 |
3.8. password_column_2 (string) |
| 101 |
3.9. use_rpid (integer) |
| 102 |
|
| 103 |
3.1. db_url (string) |
| 104 |
|
| 105 |
This is URL of the database to be used. Value of the parameter depends |
| 106 |
on the database module used. For example for mysql and postgres modules |
| 107 |
this is something like mysql://username:password@host:port/database. |
| 108 |
For dbtext module (which stores data in plaintext files) it is |
| 109 |
directory in which the database resides. |
| 110 |
|
| 111 |
Default value is "mysql://serro:47serro11@localhost/ser". |
| 112 |
|
| 113 |
Example 1.1. db_url parameter usage |
| 114 |
modparam("auth_db", "db_url", "mysql://foo:[email protected]/ser") |
| 115 |
|
| 116 |
3.2. user_column (string) |
| 117 |
|
| 118 |
This is the name of the column holding usernames. Default value is fine |
| 119 |
for most people. Use the parameter if you really need to change it. |
| 120 |
|
| 121 |
Default value is "username". |
| 122 |
|
| 123 |
Example 1.2. user_column usage |
| 124 |
modparam("auth_db", "user_column", "user") |
| 125 |
|
| 126 |
3.3. domain_column (string) |
| 127 |
|
| 128 |
This is the name of the column holding domains of users. Default value |
| 129 |
is fine for most people. Use the parameter if you really need to change |
| 130 |
it. |
| 131 |
|
| 132 |
Default value is "domain". |
| 133 |
|
| 134 |
Example 1.3. domain_column usage |
| 135 |
modparam("auth_db", "domain_column", "domain") |
| 136 |
|
| 137 |
3.4. password_column (string) |
| 138 |
|
| 139 |
This is the name of the column holding passwords. Passwords can be |
| 140 |
either stored as plain text or pre-calculated HA1 strings. HA1 strings |
| 141 |
are MD5 hashes of username, password, and realm. HA1 strings are more |
| 142 |
safe because the server doesn't need to know plaintext passwords and |
| 143 |
they cannot be obtained from HA1 strings. |
| 144 |
|
| 145 |
Default value is "ha1". |
| 146 |
|
| 147 |
Example 1.4. password_column usage |
| 148 |
modparam("auth_db", "password_column", "password") |
| 149 |
|
| 150 |
3.5. rpid_column (string) |
| 151 |
|
| 152 |
This is the name of the column holding information for the |
| 153 |
Remote-Party-ID header field. Default value is fine for most people. |
| 154 |
Use the parameter if you really need to change it. |
| 155 |
|
| 156 |
Default value is "rpid". |
| 157 |
|
| 158 |
Example 1.5. rpid_column usage |
| 159 |
modparam("auth_db", "rpid_column", "remote_party_id") |
| 160 |
|
| 161 |
3.6. calculate_ha1 (integer) |
| 162 |
|
| 163 |
This parameter tells server whether it should read plaintext password |
| 164 |
from the database or HA1 string. If the parameter is set to 1 then the |
| 165 |
server will assume that the column pointed to by plain_password_column |
| 166 |
contains plaintext passwords and it will calculate HA1 strings on the |
| 167 |
fly. |
| 168 |
|
| 169 |
If the parameter is set to 0 then the server assumes that the database |
| 170 |
contains HA1 strings directly and will not calculate them. In this case |
| 171 |
it will use value of password_column as name of column with HA1 |
| 172 |
password. If username parameter of credentials contains also @domain |
| 173 |
(some user agents put domain in username parameter), then column |
| 174 |
pointed to by password_column_2 parameter will be used instead. This |
| 175 |
column should also contain HA1 strings but they should be calculated |
| 176 |
including the domain in the username parameter (as opposed to |
| 177 |
password_column which (when containing HA1 strings) should always |
| 178 |
contains HA1 strings calculated without domain in username. |
| 179 |
|
| 180 |
This ensures that the authentication will always work when using |
| 181 |
pre-calculated HA1 string, not depending on the presence of the domain |
| 182 |
in username. |
| 183 |
|
| 184 |
Default value of this parameter is 0. |
| 185 |
|
| 186 |
Example 1.6. calculate_ha1usage |
| 187 |
modparam("auth_db", "calculate_ha1", 1) |
| 188 |
|
| 189 |
3.7. plain_password_column (string) |
| 190 |
|
| 191 |
This parameter holds the name of column holding plain text password. |
| 192 |
This column is used when calculate_ha1 is set. |
| 193 |
|
| 194 |
Default value is "password". |
| 195 |
|
| 196 |
Example 1.7. plain_password_column usage |
| 197 |
modparam("auth_db", "plain_password_column", "password") |
| 198 |
|
| 199 |
3.8. password_column_2 (string) |
| 200 |
|
| 201 |
As described in the previous section this parameter contains name of |
| 202 |
column holding pre-calculated HA1 string that were calculated including |
| 203 |
the domain in the username. This parameter is used only when |
| 204 |
calculate_ha1 is set to 0 and user agent sends credentials containing |
| 205 |
the domain in the username. |
| 206 |
|
| 207 |
Default value of the parameter is ha1b. |
| 208 |
|
| 209 |
Example 1.8. password_column_2 usage |
| 210 |
modparam("auth_db", "password_column_2", "ha1_2") |
| 211 |
|
| 212 |
3.9. use_rpid (integer) |
| 213 |
|
| 214 |
This parameter specifies whether the server should fetch a value for |
| 215 |
the Remote-Party-ID header field from the database. |
| 216 |
|
| 217 |
If the parameter is set to 1 the server expects to find a value for |
| 218 |
this header in the column specified by the rpid_column parameter. |
| 219 |
|
| 220 |
Default value of this parameter is 0. |
| 221 |
|
| 222 |
Example 1.9. use_rpidusage |
| 223 |
modparam("auth_db", "use_rpid", 1) |
| 224 |
|
| 225 |
4. Functions |
| 226 |
|
| 227 |
4.1. www_authorize(realm, table) |
| 228 |
4.2. proxy_authorize(realm, table) |
| 229 |
|
| 230 |
4.1. www_authorize(realm, table) |
| 231 |
|
| 232 |
The function verifies credentials according to RFC2617. If the |
| 233 |
credentials are verified successfully then the function will succeed |
| 234 |
and mark the credentials as authorized (marked credentials can be later |
| 235 |
used by some other functions). If the function was unable to verify the |
| 236 |
credentials for some reason then it will fail and the script should |
| 237 |
call www_challenge which will challenge the user again. |
| 238 |
|
| 239 |
Meaning of the parameters is as follows: |
| 240 |
* realm. Realm is a opaque string that the user agent should present |
| 241 |
to the user so he can decide what username and password to use. |
| 242 |
Usually this is domain of the host the server is running on. If an |
| 243 |
empty string "" is used then the server will generate it from the |
| 244 |
request. In case of REGISTER requests To header field domain will |
| 245 |
be used (because this header field represents a user being |
| 246 |
registered), for all other messages From header field domain will |
| 247 |
be used. |
| 248 |
* table. Table to be used to lookup usernames and passwords (usually |
| 249 |
subscribers table). |
| 250 |
|
| 251 |
Example 1.10. www_authorize usage |
| 252 |
... |
| 253 |
if (www_authorize("iptel.org", "subscriber")) { |
| 254 |
www_challenge("iptel.org", "1"); |
| 255 |
}; |
| 256 |
... |
| 257 |
|
| 258 |
4.2. proxy_authorize(realm, table) |
| 259 |
|
| 260 |
The function verifies credentials according to RFC2617. If the |
| 261 |
credentials are verified successfully then the function will succeed |
| 262 |
and mark the credentials as authorized (marked credentials can be later |
| 263 |
used by some other functions). If the function was unable to verify the |
| 264 |
credentials for some reason then it will fail and the script should |
| 265 |
call proxy_challenge which will challenge the user again. |
| 266 |
|
| 267 |
Meaning of the parameters is as follows: |
| 268 |
* realm - Realm is a opaque string that the user agent should present |
| 269 |
to the user so he can decide what username and password to use. |
| 270 |
Usually this is domain of the host the server is running on. |
| 271 |
If an empty string "" is used then the server will generate it from |
| 272 |
the request. From header field domain will be used as realm. |
| 273 |
* table - Table to be used to lookup usernames and passwords (usually |
| 274 |
subscribers table). |
| 275 |
|
| 276 |
Example 1.11. proxy_authorize usage |
| 277 |
... |
| 278 |
if (!proxy_authorize("", "subscriber)) { |
| 279 |
proxy_challenge("", "1"); # Realm will be autogenerated |
| 280 |
}; |
| 281 |
... |