1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<title>Module mod_auth_msql</title>
</head>
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
<BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#000080"
ALINK="#FF0000"
>
<DIV ALIGN="CENTER">
<IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]">
<H3>
Apache HTTP Server Version 1.2
</H3>
</DIV>
<H1 ALIGN="CENTER">Module mod_auth_msql</H1>
This module is contained in the <code>mod_auth_msql.c</code> file and
is compiled in by default. It allows access control using the public
domain mSQL database <code><a
href="ftp://ftp.bond.edu.au/pub/Minerva/msql">ftp://ftp.bond.edu.au/pub/Minerva/msql</a></code>,
a fast but limited SQL engine which can be contacted over an internal
Unix domain protocol as well as over normal TCP/IP socket
communication. It is only available in Apache 1.1 and later. <p>
<a href="#FullDescription">Full description</a> /
<a href="#Example">Example</a> /
<a href="#CompileTimeOptions">Compile time options</a> /
<a href="#RevisionHistory">RevisionHistory</a> /
<a href="#Person">Person to blame</a> /
<a href="#Sourcecode">Sourcecode</a>
<p>
<hr><h2><a name="FullDescription">Full description of all tokens</a></h2>
<dl>
<code><dt>
Auth_MSQLhost < FQHN | IP Address | localhost >
</dt></code><dd>
Hostname of the machine running the mSQL demon. The effective uid
of the server should be allowed access. If not given, or if it is
the magic name <code>localhost</code>, it is passed to the mSQL library as a null
pointer. This effectively forces it to use /dev/msql rather than the
(slower) socket communication.
</dd>
<code><dt>
Auth_MSQLdatabase < mSQL database name >
</dt></code><dd>
Name of the database in which the following table(s) are contained (Quick check: use the
mSQL command <code>relshow [<hostname> dbase]</code> to verify the spelling of the
database name).
</dd>
<code><dt>
Auth_MSQLpwd_table < mSQL table name >
</dt></code><dd>
Contains at least the fields with the username
and the (encrypted) password. Each uid should only occur once in this table and
for performance reasons should be a primary key.
Normally this table is compulsory, but it is
possible to use a fall-through to other methods
and use the mSQL module for group control only.
See the <a href="#Authoritative"><code>Auth_MSQL_Authoritative</code></a>
directive below.
</dd>
<code><dt>
Auth_MSQLgrp_table < mSQL table name in the above database >
</dt></code><dd>
Contains at least the fields with the
username and the groupname. A user which
is in multiple groups has therefore
multiple entries. There might be some performance
problems associated with this and one
might consider to have separate tables for each
group (rather than all groups in one table) if
your directory structure allows for it.
One only need to specify this table when doing
group control.
</dd>
<code><dt>
Auth_MSQLuid_field < mSQL field name >
</dt></code><dd>
Name of the field containing the username in the <code>
Auth_MSQLpwd_table</code> and optionally in the <code>
Auth_MSQLgrp_table</code> tables.
</dd>
<code><dt>
Auth_MSQLpwd_field < mSQL field name >
</dt></code><dd>
Fieldname for the passwords in the <code>
Auth_MSQLpwd_table</code> table.
</dd>
<code><dt>
Auth_MSQLgrp_field < mSQL field name >
</dt></code><dd>
Fieldname for the groupname<br>
Only the fields used need to be specified. When this
module is compiled with the
<a href="#VITEK"><code>BACKWARD_VITEK</code></a> option then
the uid and pwd field names default to 'user' and 'password'.
However you are strongly encouraged to always specify these values
explicitly given the security issues involved.
</dd>
<code><dt>
Auth_MSQL_nopasswd < on | off >
</dt></code><dd>
Skip password comparison if passwd field is
empty, i.e. allow any password. This is 'off'
by default to ensure that an empty field
in the mSQL table does not allow people in by
default with a random password.
</dd>
<code><dt>
<a name="Authoritative">Auth_MSQL_Authoritative < on | off ></a>
</dt></code><dd>
Default is 'on'. When set 'on', there is no
fall-through to other authorization methods. So if a
user is not in the mSQL dbase table (and perhaps
not in the right group) or has the password wrong, then
he or she is denied access. When this directive is set to
'off', control is passed on to any other authorization
modules, such as the basic auth module with the htpasswd
file or the Unix-(g)dbm modules. The default is 'on'
to avoid nasty 'fall-through' surprises. Be sure you
know what you are doing when you decide to switch it off.
</dd>
<code><dt>
Auth_MSQL_EncryptedPasswords < on | off >
</dt></code><dd>
Default is 'on'. When set on, the values in the
pwd_field are assumed to be crypt-ed using *your*
machines 'crypt()' function and the incoming password
is 'crypt'ed before comparison. When this function is
'off', the comparison is done directly with the plaintext
entered password. (Yes, http-basic-auth does send the
password as plaintext over the wire :-( ). The default
is a sensible 'on', and I personally think that it is
a *very-bad-idea* to change this. However a multi
vendor or international environment (which sometimes
leads to different crypts functions) might force you to.
</dd>
</dl>
<hr><h2><a name="Example">Example</a></h2>
An example mSQL table could be created with the following commands:
<pre>
% msqladmin create www <br>
% msql www <br>
-> create table user_records ( <br>
-> User_id char(32) primary key, <br>
-> Cpasswd char(32), <br>
-> Xgroup char(32) <br>
-> ) \g <br>
query OK <br>
-> \q <br>
% <br>
</pre><br>
The <code>User_id</code> can be as long as desired. However some of the
popular web browsers truncate names at or stop the user from entering
names longer than 32 characters. Furthermore the 'crypt' function
on your platform might impose further limits. Also use of
the <code>require users uid [uid..]</code> directive in the
<code>access.conf</code> file where the uid's are separated by
spaces can possibly prohibit the use of spaces in your usernames.
Also, please note the <a href="#MAX_FIELD_LEN"><code>MAX_FIELD_LEN</code></a>
directive somewhere below.
<p>
To use the above, the following example could be in your
<code>access.conf</code> file. Also there is a more elaborate description
below this example.
<p>
<code><directory /web/docs/private></code>
<p>
<dl>
<dt><code>
Auth_MSQLhost localhost<br>
</code></dt>
<blockquote>or</blockquote>
<dt><code>
Auth_MSQLhost datab.machine.your.org
</code></dt><dd>
If this directive is omitted or set to <code>localhost</code>,
it is assumed that Apache and the mSQL
database run on the same (physical) machine and the faster
/dev/msql communication channel will be used. Otherwise,
it is the machine to contact by TCP/IP. Consult the mSQL
documentation for more information.
</dd>
<p>
<dt><code>
Auth_MSQLdatabase www
</code></dt><dd>
The name of the database on the above machine,
which contains *both* the tables for group and
for user/passwords. Currently it is not possible
to have these split over two databases. Make
sure that the <code>msql.acl</code> (access control file) of
mSQL does indeed allow the effective uid of the
web server read access to this database. Check the
httpd.conf file for this uid.
</dd>
<code><dt>
Auth_MSQLpwd_table user_records
</dt></code><dd>
This is the table which contain the uid/password combination
is specified.
</dd>
<code><dt>
Auth_MSQLuid_field User_id <br>
Auth_MSQLpwd_field Cpasswd
</dt></code><dd>
These two directive specify the field names in the <code>user_record</code>
table. If this module is compiled with the <a href="#VITEK"><code>BACKWARD_VITEK</code></a>
compatibility switch, the defaults <code>user</code> and <code>password</code> are
assumed if you do not specify them. Currently the user_id field
*MUST* be a primary key or one must ensure that each user only
occurs <b>once</b> in the table. If a uid occurs twice access is
denied by default; but see the <code><a href="#ONLY_ONCE">ONLY_ONCE</a></code>
compiler directive for more information.
</dd>
<code><dt>
Auth_MSQLgrp_table user_records <br>
Auth_MSQLgrp_field Xgroup <br>
</dt></code><dd>
Optionally one can also specify a table which contains the
user/group combinations. This can be the same table which
also contains the username/password combinations. However
if a user belongs to two or more groups, one will have to
use a different table with multiple entries.
</dd>
<code><dt>
Auth_MSQL_nopasswd off <br>
Auth_MSQL_Authoritative on <br>
Auth_MSQL_EncryptedPasswords on <br>
</dt></code><dd>
These three optional fields (all set to the sensible defaults,
so you really do not have to enter them) are described in more
detail below. If you choose to set these to any other values then
the above, be very sure you understand the security implications and
do verify that Apache does what you expect it to do.
</dd>
<code><dt>
AuthName example mSQL realm <br>
AuthType basic
</dt></code>
<dd>
Normal Apache/NCSA tokens for access control
<p>
<code><limit get post head></code><br>
<code>order deny,allow </code><br>
<code>allow from all </code><br>
<p>
<code>require valid-user </code><br>
<ul><li><code>valid-user</code>; allow in any user which has a valid uid/passwd
pair in the above pwd_table.
</ul>
or<br>
<code>require user smith jones </code><br>
<ul><li>Limit access to users who have a valid uid/passwd pair in the
above pwd_table *and* whose uid is 'smith' or 'jones'. Do note that
the uid's are separated by 'spaces' for historic (NCSA) reasons.
So allowing uids with spaces might cause problems.
</ul>
<code>require group has_paid</code><br>
<ul><li>Optionally also ensure that the uid has the value 'has_paid' in
the group field in the group table.
</ul>
<code><limit> </code><br>
</dd>
</dl>
<hr><h2><a name="CompileTimeOptions">Compile Time Options</a></h2>
<dl>
<dt><code>
<a name="ONLY_ONCE">#define ONLY_ONCE 1</a>
</code></dt><dd>
If the mSQL table containing the uid/passwd combination does
not have the uid field as a primary key, it is possible for the
uid to occur more than once in the table with possibly different
passwords. When this module is compiled with the <code>ONLY_ONCE</code>
directive set, access is denied if the uid occurs more than once in the
uid/passwd table. If you choose not to set it, the software takes
the first pair returned and ignores any further pairs. The SQL
statement used for this is<br>
<p><code>"select password form pwd_table where user='UID'"</code><p>
this might lead to unpredictable results. For this reason as well
as for performance reasons you are strongly advised to make the
uid field a primary key. Use at your own peril :-)
</dd>
<dt><code>
<a name="KEEP_MSQL_CONNECTION_OPEN">#define KEEP_MSQL_CONNECTION_OPEN</a>
</code></dt><dd>
Normally the (TCP/IP) connection with the database is opened and
closed for each SQL query. When the Apache web-server and the database
are on the same machine, and /dev/msql is used this does not
cause a serious overhead. However when your platform does not
support this (see the mSQL documentation) or when the web server
and the database are on different machines the overhead can be
considerable. When the above directive is set defined the server leaves
the connection open, i.e. no call to <code>msqlClose()</code>.
If an error occurs an attempt is made to reopen the connection for
the next http request.
<p>
This has a number of very serious drawbacks
<ul><li> It costs 2 already rare file-descriptors for each child.
<li> It costs msql-connections, typically one per child. The (compiled in)
number of connections mSQL can handle is low, typically 6 or 12.
which might prohibit access to the mSQL database for later
processes.
<li> When a child dies, it might not free that connection properly
or quick enough.
<li> When errors start to occur, connection/file-descriptor resources
might become exhausted very quickly.
</ul>
<p>
In short, use this at your own peril and only in a highly controlled and
monitored environment.
</dd>
<dt><code>
<a name="VITEK">
#define BACKWARD_VITEK<br></a>
#define VITEK_uid_name "user"<br>
#define VITEK_gid_name "passwd"
</code></dt><dd>
A second mSQL auth module for Apache has also been developed by Vivek Khera
<<a href="mailto:khera@kciLink.com"><code>khera@kciLink.com</code></a>>
and was subsequently distributed with some early versions of Apache. It
can be obtained from
<code><a href="ftp://ftp.kcilink.com/pub/">ftp://ftp.kcilink.com/pub/mod_auth_msql.c*</a></code>.
Older 'vitek' versions had the field/table names compiled in. Newer
versions, v.1.11 have more <code>access.conf</code> configuration
options. However these where chosen not to be in line the 'ewse'
version of this module. Also, the 'vitek' module does not give group
control or 'empty' password control.
<p>
To get things slightly more in line this version (0.9) should
be backward compatible with the 'vitek' module by:
<ul><li> Adding support for the <code>Auth_MSQL_EncryptedPasswords</code> on/off functionality
<li> Adding support for the different spelling of the 4 configuration
tokens for user-table-name, user/password-field-name and dbase-name.
<li> Setting some field names to a default which used to be hard
coded in in older 'vitek' modules.
</ul>
<p>
If this troubles you, remove the 'BACKWARD_VITEK' define.
</dd>
<dt><code>
<a name="MAX_FIELD_LEN">
#define MAX_FIELD_LEN (64)<br>
#define MAX_QUERY_LEN (32+24+MAX_FIELD_LEN*2+3*MSQL_FIELD_NAME_LEN+1*MSQL_TABLE_NAME_LEN)<br></a>
</code></dt><dd>
In order to avoid using the very large <code>HUGE_STRING_LENGTH</code>, the above two compile
time directives are supplies. The <code>MAX_FIELD_LEN</code> contains the maximum number of
characters in your user, password and group fields. The maximum query length is derived
from those values.
<p>
We only do the following two queries:
<ul><li>For the user/passwd combination
<p><code>"select PWDFIELD from PWDTABLE where USERFIELD='UID'"</code><br>
<li>Optionally for the user/group combination:
<p><code>"select GROUPFIELD from GROUPTABLE where USERFIELD='UID' and GROUPFIELD='GID'"</code><br>
</ul>
<p>
This leads to the above limit for the query string. We are ignoring escaping a wee bit here
assuming not more than 24 escapes.)
</dd>
</dl>
<hr><h2><a name="RevisionHistory">Revision History</a></h2>
This version: 23 Nov 1995, 24 Feb 1996, 16 May 1996.
<dl>
<dt>Version 0.0<br></dt>
<dd>First release
</dd>
<dt>Version 0.1<br></dt>
<dd>Update to Apache 1.00
</dd>
<dt>Version 0.2<br></dt>
<dd>Added lines which got missing God knows when
and which did the valid-user authentication no good at all !
</dd>
<dt>Version 0.3<br></dt>
<dd>Added '<code>Auth_MSQL_nopasswd</code>' option
</dd>
<dt>Version 0.4<br></dt>
<dd>Cleaned out the error messages mess.
</dd>
<dt>Version 0.6<br></dt>
<dd>Inconsistency with gid/grp in comment/token/source
Make sure you really use '<code>Auth_MSQLgrp_field</code>'
as indicated above.
</dd>
<dt>Version 0.7<br></dt>
<dd><code>*host</code> to <code>host</code> fixed. Credits
go to Rob Stout, <stout@lava.et.tudelft.nl> for
spotting this one.
</dd>
<dt>Version 0.8<br></dt>
<dd>Authoritative directive added. See above.
</dd>
<dt>Version 0.9<br></dt>
<dd><code>palloc</code> return code check(s), should be
backward compatible with 1.11 version of Vivek Khera
<khera@kciLink.com> msql
module, fixed broken err msg in group control, changed
command table messages to make more sense when displayed
in that new module management tool. Added
<code>Auth_MSQL_EncryptedPasswords</code> on/off functionality.
msqlClose() statements added upon error. Support for
persistent connections with the mSQL database (riscy).
Escaping of ' and \. Replaced some
<code>MAX_STRING_LENGTH</code> claims.
</dd>
</dl>
<hr><h2><a name="Person">Contact/person to blame</a></h2>
This module was written for the
<a href="http://ewse.ceo.org">European Wide Service Exchange</a> by
<<a href="mailto:Dirk.vanGulik@jrc.it"><code>Dirk.vanGulik@jrc.it</code></a>>.
Feel free to contact me if you have any problems, ice-creams or bugs. This
documentation, courtesy of Nick Himba, <a href="mailto:himba@cs.utwente.nl">
<code><himba@cs.utwente.nl></code></a>.
<p>
<hr><h2><a NAME="Sourcecode">Sourcecode</a></h2>
The source code can be found at <a href="http://www.apache.org"><code>
http://www.apache.org</code></a>. A snapshot of a development version
usually resides at <a href="http://me-www.jrc.it/~dirkx/mod_auth_msql.c"><code>
http://me-www.jrc.it/~dirkx/mod_auth_msql.c</code></a>. Please make sure
that you always quote the version you use when filing a bug report.
<p>
Furthermore a test/demonstration suite (which assumes that you have
both mSQL and Apache compiled and installed) is available at the contrib
section of <a href="ftp://ftp.apache.org/apache/dist/contrib"><code>
ftp://ftp.apache.org/apache/dist/contrib</code></a> or
<a href="http://me-www.jrc.it/~dirkx/apache-msql-demo.tar.gz"><code>
http://me-www.jrc.it/~dirkx/apache-msql-demo.tar.gz</code></a> and
its <a href="http://me-www.jrc.it/~dirkx/apache-msql-demo"><code>
README</code></a> file.
<HR>
<H3 ALIGN="CENTER">
Apache HTTP Server Version 1.2
</H3>
<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A>
<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A>
</body>
</html>
|
