Limiting Access to Your WN Hierarchy

[Previous] [Next] [Up] [Top] [Search] [Index]

Limiting Access to Your WN Hierarchy

There are two ways to limit access to your hierarchy. You can restrict access by hostname or IP address and you can restrict access to users whose name and password are in a file on your server (authentication). You can, of course, do both. To restrict access to an entire hierarchy you must restrict access to each of its subdirectories.

Warning: If access to a directory is restricted by either of the ways described here the restrictions affect only that one directory and not its subdirectories.

10.1 Access Control Files: Limiting Access by Hostname or IP Address

If you have opted to limit access to your server in this way you do so by setting the value of Accessfile in the index file for a directory. In the directory record part of an index file, a line like

Accessfile=~/dir/.access

specifies that the the access control file WN_root/dir/.access contains restrictions on what sites are allowed to access this directory. The Accessfile directive takes the value of a path to a file in three different forms. If the path begins with a '/' or with ~/ then it is relative to the WN hierarchy root, and otherwise it is relative to the directory containing the index file in which the directive occurs. In particular the access file must be located within your WN hierarchy.

Also note that limiting access to this directory does not limit access to subdirectories. The Accessfile= line must occur in the index file of each directory you want restricted. Of course, they can all refer to the same file. To use the same file for several directories be sure to use the Accessfile=~/dir/.access form of the directive so the line can be the same for every index file.

This will limit access to the server to those clients with an IP address or subnet address listed (and not excluded) in the file .access listed in the Accessfile directive.

There are three possible formats for lines in the access file. First you may list the domain names of the machines using wildcards provided the machines all have proper PTR domain name records. For example the line

dogbert.widget.com

allows access to one host. To allow access to all machines in the widget.com domain, use the line

*.widget.com

Note that this will not allow access to a machine called widget.com if it exists. One would need to add in the line "widget.com" to allow it access.

You can also allow access by IP address and, in general, this is somewhat more secure than using the hostnames. There are two line formats for IP addresses. The first is to explicitly list an IP address like 129.111.222.123 or a subnet address like 129.111.222. or 129.111. In case a subnet address is listed it must end with a period like

129.111.222.
or
132.123.

but complete IP addresses like 129.111.222.123 should not end with a period. If a subnet address is listed any client with an IP address beginning with that subnet address will be allowed access.

The second format for IP address restriction uses a net address, net mask pair with the two parts separated by a '/'. For example

129.111.222.0/255.255.255.0

The presence of the '/' indicates to the server that this format is being used. The part before the '/' is the "net address" and the part after is the "net mask". The server will then take the IP address of the remote client, do a logical "and" of each of its four parts with the corresponding four parts of the net mask (255.255.255.0 in this example) and check that the four results agree with the four parts of the net address (129.111.222.0). So the access file line above will match (and allow access to) precisely those machines with IP address of the form 129.111.222.x because the "x" part is "anded" with 0 and hence becomes 0, while the first three parts are anded with 255 and hence unchanged, so they must equal 129, 111, and 222 respectively.

You can also exclude IP addresses or domain names by prefixing them with an '!', so if the access file contained only the lines

!speedy.acns.nwu.edu
*

Access would be permitted to every machine except speedy (the * matches, and allows access to, anything). Likewise

!129.111.
!129.222.0.0/255.255.0.0
*

would allow access to everyone except those on subnet 129.111 or on subnet 129.222. In general prefixing a line (in any of the three formats) with '!' causes immediate denial of access to any matching host. The first matching line (with or without leading '!') for a host is the one which takes effect. Once a match is found access will be granted (or denied if a '!' is present) and no subsequent lines in the access file will be considered.

A line in an accessfile cannot exceed 255 characters in length and every line must end with a newline (some editors don't guarantee this and the last line of a file may not have a newline). A blank line at the end is fine. If these conditions are not met an error of type "Access file line overflow" will be generated.

10.1.1 Privileged Sites

You may also designate "privileged sites" in your access files. If you list a site in an access file with a '+' prefix like

+hopf.math.nwu.edu
+123.123.123.1
+111.111.111.0/255.255.255.0

then requests from that site will be exempt from any password requirements (as described below). In other words, no username/password pair will be required for requests from these sites, even if they are required from other sites.

Obviously the '+' and '!' prefixes for access file lines are mutually exclusive.

10.1.2 Customized Error Messages

It is possible to specify a URL referring to a customized document intended as an error message when access is denied. The easiest way to do this is to place the line

Access-denied-URL=http://host/dir/foo.html

or the line

Access-denied-URL=/dir/foo.html

at the beginning of the access file. When this is done and a request is denied because of failure to meet the restrictions in that access file, the browser will be redirected to the URL "http://host/dir/foo.html" or "/dir/foo.html". This line is also a legal directory directive which may be placed in an index file.

10.2 Limiting Access by Password -- Authentication

You can also maintain a password file (or files) on your system and restrict access to those users who can supply a valid user name and password. This is the so-called "Basic" authentication described in the HTTP protocol.

Warning: I would strongly advise against using basic authentication described here to protect sensitive information on a server which runs on system on which untrusted users have accounts.

The use of basic authentication with WN involves two additional programs which can be found in the /bin directory of the distribution. The first of these is mkpasswd which is a perl utility for creating and altering password files. It should be run the first time with the command

mkpasswd -n filename

This prompts you for a username and password and then creates a password file called "filename" with that entry. On subsequent uses the -n argument should be omitted so that entries will be added to the existing file instead of starting a new one (the -n is for "new"). If a subsequent entry is made with the same user name the entry for that user will be replaced. If the "filename" argument is omitted then the default name of wnpasswd is used. There is another optional argument which may be used with this program. The command

mkpasswd -D filename

causes a UNIX DBM database to be created or used instead of a simple flat file. This is very useful if you have a very large number of password entries. The database resides in the two files filename.dir and filename.pag. The -n option has no effect when combined with the -D option. To create a new database you must remove or rename the .pag and .dir files. To remove a single entry from a password file use the command "mkpasswd -d filename" or "mkpasswd -Dd filename" for a DBM database.

Once you have created your password file and made sure that it is readable by the userid under which the server will run, you are ready to set up the WN authentication module, called authwn. This is done on a per directory basis by three entries in directory record of the index file. Entries like

Authorization-realm=myrealm@host.domain
Authorization-module=~/bin/authwn "~/dir/wnpasswd"
Authorization-type=basic

in the directory record specify that the authentication module authwn is being used to check user's passwords and that it should consult the password file "wnpasswd" in WN_root/dir/. If instead of the password file "wnpasswd" you are using a DBM database "wnpasswd.dir" and "wnpasswd.pag" created with "mkpasswd -D" as described above (or created some other way), then you should use the line

Authorization-module=~/bin/authwn -D "~/dir/wnpasswd"

The password file can also be specified with the -P option as in

Authorization-module=~/bin/authwn -P wnpasswd

The name of the password file can be given in three different formats: beginning with a '/' meaning it is relative to the system root, beginning with ~/ indicating it is relative to the WN hierarchy root, or something else indicating it is relative to the directory containing this index file. If you use the "~/..." form it is a good idea to put the file name in double quotes as shown above to prevent the shell from trying to interpret the '~'.

Note that if you designate a privileged site in your access control file then any users from that site will not be requested to supply a user name and password.

For security reasons when you use authwn or any Authorization-Module you are required to use either the -t or -T option or the -a or -A option when the server is run and to have the index.cache file in the protected directory owned by the trusted user or group. This is to guard against counterfeit authentication modules. Note that the four command line arguments -a, -A, -t, -T all take a numeric argument. Thus the command should be "./swn -t 203" and not "./swn -t joe" if user joe has user id 203.

The Authorization-Realm line is to notify the client that for any document on this server with the same realm as this one, the same password / username combination will be valid, so the client need not ask the user for a username and password, but can reuse the one supplied for the first document with this realm. For security reasons it is a good idea to put your host and domain name in the realm. This may at least discourage attempts at other sites to forge your realm in order to collect user passwords. Your users should also be warned never to enter their password if the realm displayed when they are prompted for a password contains a different hostname than the one in the URL they are trying to access.

Also note that password protecting a directory does not protect its subdirectories. The three "Authorization" lines must occur in the index file of each directory you want to protect. Of course, these lines can all be identical for different directories if you use the "Authorization-module=~/bin/authwn ~/dir/wnpasswd" form to specify locations relative to your WN root.

There is also support for a "group" file with authentication. This feature is invoked by using the -g and -G options with the authwn authentication module. The line

Authorization-module=authwn -g grpname -G foo -P wnpasswd

means to use the group name "grpname" and the group file "foo." The group file is a file in the format of a UNIX "/etc/group" file. That is, it has lines of the form

grpname:*:99:user1,user3,user5

where the fields are separated by colons, the first field is a group name, and the fourth field is a comma separated list of user names. Authwn will ignore the second and third fields. If the line above is in the file foo and authwn is invoked as above then a user will be granted access provided the supplied password matches that in the wnpasswd file and the user's username is in the list after the second ':' in the line starting with the group name. Thus, in this example users user1, user3, and user5 will be given access if they provide valid passwords and other users will not.

It is possible to specify a custom error message to be sent when password authentication fails because of an incorrect password or username. The directory directive

Auth-denied-file=~/dir/foo.html

specifies that any request for a document in this directory which is denied because of an authorization module restriction results in the file ~/dir/foo.html being sent instead. A default value for all directories can be set by uncommenting the "#define AUTH_DENIED_FILE" line in config.h and recompiling. Note that this is not a URL but the name of a file whose content is to be sent as error text when authentication is denied. If the file name starts with '~/' as above it is assumed to be relative to the WN root directory. Otherwise it is assumed to be a path relative to the directory containing the index file. The "Basic" authentication scheme is flawed in that it involves the transmission of essentially unencoded passwords over the network. It is relatively easy for unscrupulous people to obtain "sniffer" software which allows eavesdropping on all local network traffic. This means, in particular, that it is possible to intercept passwords.

This particular problem is remedied by the "Digest" authentication scheme. Digest authentication is supported experimentally by WN, but has the rather severe drawback that no publicly available clients currently support it. It is experimental, because I have no client to test it and hence it has barely been tested.

Note: To enable the DBM features of authwn you will have to uncomment the lines in authwn/Makefile starting with #DBMFLAG and #DBMLIB and recompile the authwn program by running make in the /authwn directory.

John Franks <john@math.nwu.edu>

[Previous] [Next] [Up] [Top] [Search] [Index]