Debian Codegraph @

src/modules/uid_auth_db/README

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