/ 
CGI-Builder-Auth-0.06
River stage zero No dependents
/ CGI::Builder::Auth::Realm

NAME

CGI::Builder::Auth::Realm - Database of HTTPD Security Realms

SYNOPSIS

use CGI::Builder::Auth::Realm;

# pull out the definition of the "members" realm
$realms = new CGI::Builder::Auth::Realm(-config_file=>'/home/httpd/conf/realms.conf');
$def = $realms->realm(-realm=>'members');

# show info about the realm
print "realm name = ",     $def->name,"\n";
print "user database = ",  $def->userdb,"\n";
print "group database = ", $def->groupdb,"\n";
print "user type = ",      $def->usertype,"\n";
print "group type = ",     $def->grouptype,"\n";
print "web server type = ",$def->server,"\n";
print "cryptography = ",   $def->crypt,"\n";
print "other fields = ",   $def->fields,"\n";

# Connect to the database for the realm,
# returning a CGI::Builder::Auth::RealmManager object.
$database = $def->connect(-writable=>1);

DESCRIPTION

Pay no attention to that man behind the curtain! Move along, nothing to see here!

This module was originally part of the HTTPD-User-Manage collection, which is available on CPAN. If you want to use it, go download that package. This module is used as part of the internal implementation of CGI::Builder::Auth. The original documentation is preserved here in this release for historical purposes. The software has been hacked and this documentation is not guaranteed to be correct. The module may disappear from the CGI::Builder::Auth distribution in a future release. Do not use it directly or rely on it.

CGI::Builder::Auth::Realm defines high level security realms to be used in conjunction with Apache, Netscape and NCSA Web servers. You define the realms in a central configuration file, and access their underlying databases via this module and the CGI::Builder::Auth::RealmManager library. This allows automated tools to change user passwords, groups and other information without regard to the underlying database implementation.

Important note: Do not use these modules to adjust the Unix password or group files. They do not have the same format as the Web access databases.

CONFIGURATION FILE

A typical configuration file is shown below. It is human readable and similar in form to conventional Apache and NCSA HTTPD configuration files. Directives are separated from their arguments by white space (tabs or spaces), and comments begin with hash marks (#). By convention, the standard configuration file is named "realms.conf", but you can give it any name you prefer.

# realms.conf <Realm main> Type text Authentication Basic Users /home/httpd/security/passwd Groups /home/httpd/security/group </Realm>

<Realm development> Type DBM Authentication Basic Users /home/httpd/security/devel.passwd Groups /home/httpd/security/devel.group </Realm>

<Realm members@capricorn.org> Type text Authentication Digest Users /home/httpd/1.1/passwd Groups /home/httpd/1.1/group </Realm>

<Realm subscriptions> Type MSQL Authentication Basic Database web_accounts@localhost Users table=users uid=name passwd=pass Groups table=groups group=group Fields Name Age:i Paid:s1 </Realm>

realms.conf is made up of one or more <Realm> sections. The opening <Realm> tag must contain the realm's name, which can be any set of non-whitespace characters. Each section contains directives that tells the module what type of authentication to use for the realm, what type of database to use, and where to find the files or database tables used for the realm. The users and groups defined in one realm are independent of those defined in another, giving you a lot of flexibility in setting up access control for your site.

The example shown here defines four different security realms. The first, named "main", uses human readable text files and the Basic Authentication protocol. The second, "development", also uses Basic Authentication, but stores users and groups in DBM files rather than in text files. The realm named "members@capricorn.org" uses Digest Authentication on top of textfiles. By convention, Digest realms look like e-mail addresses, but you don't have to follow this convention. The last realm definition uses Basic Authentication on top of an mSQL database.

The directives allowed within a <Realm> section are listed here:

Directive Example Param Description Type DBM Database type Authentication Basic Authentication scheme Users /etc/httpd/passwd Path to user database Groups /etc/httpd/group Path to group database Database www@capricorn.com Location of mSQL db Server NCSA Type of server Driver mSQL DBI driver Fields name age paid Additional user fields Mode 0644 Mode for new files Default Default realm

Type

This directive specifies the database type. It can be any of "text," "DBM," "DB," or "SQL." Although these are the only databases currently recognized by Apache, other Unix DBM-like formats, including "GDBM," and "SDBM" are recognized for future compatibility. You may use "MSQL" as an alias for "SQL."

Authentication

This directives specifies the type of authentication to use. It can be either "Basic" or "Digest."

Users

This is the path to the file or database table that holds user names and passwords. For everything but SQL databases, it's a physical path to a file on your system. If the database file doesn't exist (and the process has sufficient privileges), it will be created. For example:

Users /home/httpd/security/passwd

For mSQL databases, the value of the directive should have the format:

Users table=table_name uid=user_field password=password_field

The value of table is the name of the table in which to look for the user. The value of uid and password are the fields in which Apache will look for the user ID and password. For lookup efficiency, the uid field should be defined as the primary key field in mSQL.

You may optionally place a colon and field width after any of the table names. These field widths are used as hints by the user_manage script to create a nicely-laid out fill-out form. If not provided, reasonable defaults are assumed

Here's an example of a valid directive in which the user ID field is given a width of 40:

Users table=Members uid=Name:40 password=Pass

mSQL tables are not created automatically. You have to define them yourself (using the msql application) before using them.

Groups

This is the path to the file or database table that holds group assignments. If you don't need groups, just leave the directive out. For everything but MSQL databases, the argument physical path to a file on your system. If the database file doesn't exist (and the process has sufficient privileges), it will be created. For example:

Groups /home/httpd/security/groups

For mSQL databases, the directive points to a previously-defined table and field in the database in the format

Groups table=table_name group=group_field

The value of table is the name of the table in which to look up the user. The value of group is the field in which Apache find the group that the user belongs to. Apache will look for the user name in the same field as declared in the Users directive, so don't declare another uid field here. You can use the same table for both Users and Groups, or use separate ones. In the latter case, you can have several records for each user, allowing the one user to belong to multiple groups.

As for the User directive, you can provide an optional field width for the group field when using mSQL databases.

Database

This directive is valid for SQL databases only and indicates where the authentication database can be found. It should be in the format database@host. If the hostname is omitted, "localhost" is assumed. For mSQL databases, performance will be much better if database and Web server are on the same machine because in this case, the client and server use a Unix socket to communicate rather than a TCP/IP socket.

Server

Web servers differ slightly in the format of the users and groups databases. This directive indicates which server you are using. Recognized values include "apache", "ncsa", "cern" and "netscape." Example:

Server cern

If no server is specified, "apache" is assumed. If your server is not on this list, try "ncsa".

Driver

For SQL databases only, this directive specifies what DBD (database driver) module to use. It defaults to "mSQL". You can use any database for which a DBD module is available. You must also, of course, compile and configure the Web server to correctly use the driver.

Fields

This directive lists other fields that can be found in the user table. These fields can then be read and set automatically by the user_manage application. Note that this works reliably in SQL databases only. Large fields, or fields that contain the "=" character, will fail when applied to text or DBM files.

This directive expects a list of field names in the format name[:type][width]. The field type and width are hints used by the user_manage application to format the field values correctly. The type can be one of "i", for an integer value, "s" for a string value and "f" for a floating point number. If not specified, the field is assumed to be of type string. The field value must be an integer.

In this example, we define three fields named "Name", "Age" and "Paid". The first is a string value of default length. The second is an integer. The third is a string of length one (it's assumed to be a "Y" or "N"):

Fields	Name Age:i Paid:s1

Other fields may be present in the database. The Fields directive tells the user_manage script which fields should be made visible to the user interface.

Mode

This directive sets the mode that Realm.pm will use to create the database files, if it needs to. The mode should be in octal form. This value can be overriden with the -mode argument in the connect() method. The default is 0644 (-rw-r--r--).

Default

If this directive is present, the current realm becomes the default to use when no realm is explicitly indicated. If no section in the configuration file contains this directive, the first defined realm becomes the default. It is a fatal error for Default to appear in more than one section.

CLASSES

There are two closely tied classes in Realm.pm. CGI::Builder::Auth::Realm parses the configuration file, maintains lists of realms, responds to inquiries about realms, and opens up connections to realms' underlying databases. CGI::Builder::Auth::RealmDef defines the object that holds information about a particular realm.

CGI::Builder::Auth::Realm METHODS

new()
$realms = CGI::Builder::Auth::Realm->new(-config=>'/path/to/config/file');

Create a new set of realm definitions from the given configuration file.

exists()
$exists = $realms->exists(-realm=>'subscribers');

Returns true if the named realm exists. Otherwise returns undef. Arguments:

-realm    Name of the realm.

An alternative form is to use the name of the realm without the named argument:

$exists = $realms->exists('subscribers');
list()
@realms = $realms->list();

Returns the list of realm names defined in the configuration file.

realm()
$realmdef = $realms->realm(-realm=>'subscribers');

Returns the RealmDef object that defines the realm. See the discussion below for more details. An alternative form is to use the name of the realm alone:

$realmdef = $realms->realm('subscribers');
connect()
$database = $realms->connect(-realm=>'subscribers',
                             -writable=>1,
                             -mode=>0600);

Connect to the named realm, returning a database handle (actually, a RealmManager object). Recognized named arguments are:

-realm     Name of the realm.
-mode      Mode with which to create file, if necessary.
-writable  Whether this realm is to be writable.

By default, realms are opened read-only. If you choose to open it for writing, you can provide a mode for creting the file, overriding the mode defined in the configuration file. If the realm is not listed in the configuration file, this routine returns undef.

CGI::Builder::Auth::RealmDef METHODS

new()
$realmdef = CGI::Builder::Auth::RealmDef->new('subscribers');

Create a new RealmDef and assign it a name. This method is usually called internally.

name()
$name = $realmdef->name();

Return the name of this realm.

userdb()
$userdata = $realmdef->userdb();

Return the path to the user database defined in the configuration file. For non-SQL databases, this is the path to the database or text file. For SQL databases, this is the table and field definition line. You can get a pre-parsed version of this information using SQLdata(), see below.

groupdb()
$groupdata = $realmdef->groupdb();

Return the path to the group database defined in the configuration file. For non-SQL databases, this is the path to the database or text file. For SQL databases, this is the table and field definition line. You can get a pre-parsed version of this information using SQLdata(),

mode()
$mode = $realmdef->mode();

Return the mode for creating the database file.

database()
$database = $realmdef->database();

Return the database name and host (SQL databases only).

fields()
$fields = $realmdef->fields();

Return the additional field definition line (SQL databases only). No additional parsing is performed.

usertype()
$type = $realmdef->usertype();

Return the type of the user/password database, for example "NDBM".

grouptype()
$type = $realmdef->grouptype();

Return the type of the group database, for example "NDBM".

authentication()
$authentication = $realmdef->authentication();

Returns the authentication in use for this realm. May be either "Basic" or "Digest".

server()
$server = $realmdef->server();

Return the type of Web server this realm is designed for.

crypt()
$crypt = $realmdef->crypt();

Return the cryptography type for this realm, either "crypt" or "MD5".

SQLdata()
$data = $realmdef->SQLdata();

For SQL databases only, return the parsed information from the Users and Groups directives. The value returned is an associative array containing the following fields:

database        name of the SQL database
host            name of the SQL database host
dblogin
dbpassword
usertable       name of the SQL table containing users & passwords
grouptable      name of the SQL table containing groups
userfield       name of the field containing the user ID
groupuserfield
groupfield      name of the field containing the group name
passwdfield     name of the field containing the encrypted password
userfield_len   length of the user ID field
groupfield_len  length of the group field
passwdfield_len length of the password field
connect()
$database = $realmdef->connect(-writable=>1,
                               -mode=>0600,
                               -server=>'ncsa');

Establish a connection to the realm database, returning a RealmManager object. You can open up a connection read-only or read-write. Optional arguments allow you to the values of the Mode and Server directives.

-writable      Open read/write if true.
-mode          Override file creation mode.
-server        Override server type.

SEE ALSO

CGI::Builder::Auth::RealmManager(3) CGI::Builder::Auth::UserAdmin(3) CGI::Builder::Auth::GroupAdmin(3), CGI::Builder::Auth::Authen(3)

AUTHOR

Lincoln Stein <lstein@cshl.org>

Copyright (c) 1997, Lincoln D. Stein

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.