Protecting directory trees via username/passwords

The Simplest Possible Protection Scheme

We're going to add protection to a web site to allow only 1 user, the user "mott", to access any pages on the entire site. The user mott's password is "blackberry"

To apply protection to files there are a minimum of 2 things that must be done. The number of things to do can increase, but you cannot get away with less than:

Adding information to the SY:HTTPD.CON file.
Creating a password file with usernames and passwords in it.

Modifying the SY:HTTPD.CON file

In the SY:HTTPD.CON file, before the Pass rules, add the following lines:

Protect /* {
	PassWdfile  	/__c__/pwfile.dat
	GET-Mask		mott
}

We've just told the web server three things:

We want to protect all files on the site. We did this by specifying a filespec of "/*", which means everything.
There is a file in the root of C: called PWFILE.DAT which contains username and password information.
We only want to allow the user "mott" to access these files.

The format of the password file

The password file is a simple ascii file. Passwords in the TSX-32 scheme are maintained as clear text so this file should be located in a secure location. In the file, there is one line for each user who may ever be able to access any files. The format of the each line is as follows:

name:password

There are actually other fields that can be on the line, and the ':' is used as a separator, but we're taking the minimalist approach so we won't worry about them. The alert reader will note that since we store passwords in clear text that a password cannot contain a colon.

The password field in this file must be padded with upper case 'X' to a length of 13 characters. These final 'X''s are not part of the password proper but they must be in the file. Thus, in the entry for our friend Mr. Mott, whose password is "blackberry", we have one single line in the file:

mott:blackberryXXX

We just strung 'X''s out until we hit 13 characters for the password. The alert reader will wonder if 'X' can be part of the password, and the answer is yes. "ZXC123" is a valid passord, as is "XX123". If the last letter of the password is 'X' it will not be seen as part of the password, so that "ABCX" is equivalent to "ABC". For the curious, a valid password is 'XXXXX', which will end up in the file as

mott:XXXXXXXXXXXXX

Unfortunately that also matches any number of 'X's strung together, so the sage advise on this matter is: Dont do that.

What happens when users try to access the web pages

When a user tries to access the web page the server sends a code back to the browser which tells the browser to ask for a username and password. The browser sends back the username and password in a mildly encoded form and the server performs the comparison and either responds with the page or with another error code. In our first example the protect rule applied to all pages, so the attempt to access any page would result in a request for a username and password.

Protecting the files in just one directory

In this example we will allow general access to the files on the server but restrict access to the files in one directory.

Now that we've set everything up this is a snap. Here is our protect rule from the first example.

Protect /* {
	PassWdfile  	/__c__/pwfile.dat
	GET-Mask		mott
}

To protect the files in a directory we simply change the directory specification on the protect rule. Lets say that we want to protect the files in the \mott directory. To do this we change our protect rule to the following:

Protect /mott/* {
	PassWdfile  	/__c__/pwfile.dat
	GET-Mask		mott
}

Now when the client attempts to access files in /mott they will be prompted for a username and password, but an attempt to access any other directory will be allowed. Before going further, we need to discuss the order that translation of filespecs occurs in.

Important note about Protect rule file specifications

It isn't at all obvious that protect file specifications are the values that come in from the browswer, not the values that come after the pass rules are evaluated.

You're familiar with how a file specification can be passed through the pass/fail rules to allow mapping of a specification to an actual filename. The specification from the browser is the input, and the actual filename on disk is the output. The Protect rule evaluates the file specification as it is received from the browser.

To illustrate this, imagine that you have the following protect and pass rules:

Protect /private/* {
	PassWdfile  	/__c__/pwfile.dat
	GET-Mask		mott
}

pass	/test	/__c__/private/secret.htm

Then, imagine that the client requests the url http://domainname/test.

It is tempting to imagine that the pass rule will be processed first and the protect rule second, so that the protect rule is applied to the final, real filename. That way, all paths to the same disk file would end up going through the same Protect rule.

In actual operation the Protect rule is evaluated first, and in this sample it discovers that the directory that the user requested, /test, is not protected. Thus, the request will be translated and the file will be referenced.

Ipmap directives are applied before the Protect rule

The TSX-32 server implemented a new directive called ipmap . This directive allows you to map requests for all pages associated with a specific IP address to be mapped to a specific directory. In this way separate trees can be maintained for separate domain names.

The Protect rule is evaluated before the pass rules, as mentioned. However, it is also evaluated after the ipmap directive.

To illustrate, lets say you had the following directives:


Ipmap 123.123.123.123  /mydomain

Protect /mydomain* {
	PassWdfile  	/__c__/pwfile.dat
	GET-Mask		mott
}

pass	/mydomain/	/__c__/mydomain/*

Lets say the user connects to this site with the URL http://123.123.123.123/. The following 3 things would occur.

The Ipmap directive would convert the null filespec to /mydomain.
The Protect rule would determine that this directory is protected and cause the client to prompt for a username and password.
Assuming that the username and password were valid, the file would be re-requested and the pass rule would translate it to an actual disk file.

Protecting the files in more than one directory

There can be as many Protect directives as you want. Each one can control some set of things. The next example will demonstrate how to protect files in more than one directory. Since we can have more than one Protect directive, we'll just add in another directory with another Protect directive.

Protect /mott/* {
	PassWdfile  	/__c__/pwfile.dat
	GET-Mask		mott
}

Protect /dan/* {
	PassWdfile  	/__c__/pwfile.dat
	GET-Mask		mott
}

This pair of directives will allow the user mott to access the /mott and the /dan directories, after logging in with a username and password.

Allowing different users to access different directories

The next incremental change that we can make is to allow the user mott to access the /mott directory and allow the user dan to access the /dan directory. To do this, we'll add a new record in the pwfile.dat file for the user dan . His password will be beachbum . Here is the new pwfile.dat with two users in it.

mott:blackberryXXX
dan:beachbumXXXXX

To allow additional users to access different directories we have two Protect directives, one for each directory each specifying a different user.

Protect /mott/* {
	PassWdfile  	/__c__/pwfile.dat
	GET-Mask		mott
}

Protect /dan/* {
	PassWdfile  	/__c__/pwfile.dat
	GET-Mask		dan
}

This will allow mott to access files in the /mott directory and the user dan to access files in the /dan directory.

Allowing more than one user to access files in a single directory

Now that we have two users defined, the next change we can make is to allow both of those users to access the files in one directory. To do this we add an additional username onto the Get-Mask specifier.

In this example we'll allow the user mott and the user dan to access the /tpl directory.

Protect /tpl/* {
	PassWdfile  	/__c__/pwfile.dat
	GET-Mask	mott,dan
}

Protecting the files in one directory to anyone in the password file

The GET-Mask directive in the "Protect" rule accepts the pre-defined name "All", which means "anyone who has an entry in the password file".

In this example we'll allow anyone with an entry in the password file to access the /samples directory.

Protect /samples/* {
	PassWdfile	/__c__/pwfile.dat
	Get-Mask	All
}

Back to main Next tutorial