Protected W3C httpd Setup

Access can be restricted according to user name, internet address, or both. Access control can be tree-level, file level, or both. You can also look at the examples of protection setup.

In This Section...

Password File
Group File
Protect Directive in Configuration File
Protection Setup File
Protecting a Tree of Documents
Protecting Individual Files
Using Two-Level Protection
Embedding the Protection Setup in the Configuration File Itself
ACLOverRide
Access Control List File

Password File

If user-wise access control is used there has to be a password file listing all the users and their encrypted passwords. Password file can be maintained by htadm program which is a part ot W3C httpd distribution.

Note: Unix password files are understood by W3C httpd (but not vice versa). However, Unix users are in no way connected to the WWW access authorization.

Group File

Group file contains declarations of groups containing users and other groups, with possibly an IP address template. Group declarations as viewed from top-level look like this:

        groupname: item, item, item

The list of items is called a group definition. Each item can be a username, an already-defined groupname, or a comma-separated list of user and group names in parentheses. Any of these can be followed by an at sign @ followed by either a single IP address template, or a comma-separated list of IP address templates in parentheses. The following are valid group declarations:

        authors: john, james
        trusted: authors, jim
        cern_people: @128.141.*.*
        hackers: marca@141.142.*.*, sanders@153.39.*.*,
                 (luotonen, timbl, hallam)@128.141.*.*,
                 cailliau@(128.141.201.162, 128.141.248.119)
        cern_hackers: hackers@128.141.*.*

If an item contains only IP address template part all users from those addresses are accepted (e.g. cern_people above). Note the last two declarations: cern_hackers group is made up of the hackers group by restricting it further according to IP address.

Group definition can be continued to next line after any comma in the definition. Forward references in group file are illegal (i.e. to use group name before it is defined).

Group definition syntax is valid not only in group file, but also in

GetMask in protection setup file, and
in last field in ACL entries.

Special Predefined Groups

All: Group name All is predefined and means all the authenticated users, i.e. users that have an entry in httpd's password file. Aliases for All is Users.
Anybody: Group name Anybody is predefined to mean that access is not restricted according to remote users, i.e. just anybody can access the document, even without authentication. Aliases for Anybody are Anyone and Anonymous. Also, when the group/user name is not specified in the protection Mask (only @hostname form) it is taken to mean Anybody from that host.

Server Configuration File

Typically you protect a tree of documents by protect rule in rule file, and specify authorized persons and IP addresses in the protection setup file or access control list file:

        Protect /very/secret/*  /WWW/httpd.setup

If there are Unix file system protections set up so that there is no world read-permission the daemon naturally has to run as the owner or the group member of those files.

However, if there are protected trees owned by different people this doesn't work. In that case the daemon has to run as root, and the user and group ids have to be specified in the protect rule, e.g.:

        Protect /kevin/secret/*	  /WWW/httpd.setup1  kevin.www
        Protect /marcus/secret/*  /WWW/httpd.setup2  marcus.nogroup

Protection Setup File

Each protect rule has an associated protection setup file. It specifies valid authentication schemes, password and group files, and password server-id:

        AuthType      Basic
        ServerId      OurCollaboration
        PasswordFile  /WWW/Admin/passwd
        GroupFile     /WWW/Admin/group

Password server id needs not be a real machine name. It's only purpose is to inform the browser about which password file it is using (different protection setups on the same machine can use different password file and that would otherwise confuse pseudo-intelligent clients trying to figure out which password to send).

Note: Same server-ids on different machines are considered different by clients (otherwise this would be a security hole).

Protecting Entire Tree As One Entity

If you want to control access only to entire trees of documents and don't care to restrict access differently to individual files, it suffices to give a GetMask in setup file (and you don't need any ACL files):

        GetMask    group, user, group@address, ...

Group definition has the same syntax as in group file.

Protecting Individual Files Differently

When each individual file needs to be protected separately you should use an ACL (access control list) file in the same directory as the protected files. After that no file in that directory can be accessed unless there is a specific entry in ACL allowing it.

In this case you don't need the GetMask in setup file.

Restricting Access Even Further

There may be both GetMask and an ACL, in which case both conditions must be met. This is typically used so that GetMask defines a general group of people allowed to access the tree, and ACLs restrict access even further.

Protection Setup Embedded in the Configuration File

Often it is not necessary to have the protection information in a different file; as a new feature W3C httpd allows protection setup to be "embedded" inside the configuration file itself.

Instead of writing the setup in a different file and referring to it by the filename, you can use the Protection directive to define the protection setup and bind it to a name, and later refer to this setup via that name.

The previous example could be written into the main configuration as follows:

    Protection  PROT-NAME  {
        UserId        marcus
        GroupId       nogroup
        AuthType      Basic
        ServerId      OurCollaboration
        PasswordFile  /WWW/Admin/passwd
        GroupFile     /WWW/Admin/group
        GetMask       group, user, group@address, ...
    }
    Protect  /private/URL/*      PROT-NAME
    Protect  /another/private/*  PROT-NAME

Note that since the protection setup is in the same file as the other configuration directives, it is also possible to specify the UserId and GroupId for the server to run as, without it being a security hole. With external protection setup this is made impossible because of security reasons; that is why there is an extra field after the protection setup filename specifying the user and group ids in that case:

        Protect /kevin/secret/*	  /WWW/httpd.setup1  kevin.www
        Protect /marcus/secret/*  /WWW/httpd.setup2  marcus.nogroup

If you need a given protection setup only once there is no need to first bind it to a name and then refer to it by that name, but rather just combine the two:

    Protect  /private/URL/*  {
        UserId        marcus
        GroupId       nogroup
        AuthType      Basic
        ServerId      OurCollaboration
        PasswordFile  /WWW/Admin/passwd
        GroupFile     /WWW/Admin/group
        GetMask       group, user, group@address, ...
    }

httpd is not very robust in parsing this particular directive; make sure you have a space between the URL template and the curly brace, and that the ending curly brace is alone on that line. Also, comments are not allowed inside the protection setup definition.

ACLOverRide

The normal behavior in access control is that the masks specified in the protection setup define the groups that can be allowed in the ACL files - ACL files normally cannot allow anything that the masks don't allow. This can be changed in the protection setup by explicitly allowing ACL's to override the masks:

        ACLOverRide  On

This will inhibit the mask checks when an ACL file exists.

Access Control List File

ACL file is a file named .www_acl in the same directory as the files the access of which it is controlling. It looks typically something like this:

        secret*.html : GET,POST : trusted_people
        minutes*.html: GET,POST : secretaries
        *.html : GET : willy,kenny

It is worth noticing that all the templates are matched against (unlike in rule file where translation of rules stops in pass and fail.. So in the previous example all the HTML files are accessible to willy and kenny, even those matching the two previous templates.

The last field is just a list of users and group (possibly at required IP addresses), and in fact this field is in same syntax as group file.

When PUT method will be implemented it can appear in the middle field separated by a comma from get:

        *.html : GET,PUT : authors

Note that a ACL file can not be created in a directory without defining a protection template in the configuration file using either the Protection or the DefProt scheme. The reason is that the ACL protection needs to know what UserID, password etc. to use in order to determine whether a user has access to a specific file or not. However, once this is done, the ACL file can be extended without making changes to the server configuration file.

httpd@w3.org, July 1995