NAME

Config::Access - Perform simple access control

SYNOPSIS

use strict;                  # not optional (-:
use Config::Access;

DESCRIPTION

The Config::Access module provides a method of authenticating arbitrary client/service pairs in a way very similar to that provided by the TCP wrappers by Wietse Venema <wietse@wzv.win.tue.nl> but not limited to inetd services and IP/host names.

This module can be useful for restricting access to certain parts of a script to a certain domain. For example, a front end program to some device might deny certain users access to certain commands or only allow trusted users access to dangerous commands. The semantics of what the client and service names actually mean is totally up to the programmer.

The access control language is very similar to the access control language specified in hosts_access(5) for the TCP wrappers. Two configuration files specify access rules. A file ending in .allow specifies rules to allow access and a file ending in .deny specifies rules to deny access. The prefix of these files is specified when a Config::Access object is created.

ACCESS CONTROL FILES

As per the TCP wrappers, a request for authorisation consults the .allow and .deny files. The search stops at the first match.

• Access is granted if a $client/$service matches a rule in the .allow file.

• Access is denied if a $client/$service matches a rule in the .deny file.

• Otherwise, if no match is made access is granted.

ACCESS CONTROL RULES

Access control rules appear in the configuration files in the following format.

service_list : client_list

Each item in a list is separated by a comma and optional whitespace. Newlines and lines beginning with a '#' character are ignored. A line may be continued if a backslash character is present as the end of the line.

A service or client may be specified as the string 'ALL' which means it will be matched by anything. An optional parameter to the access_query method described below allows the caller to determine whether the request was granted (or denied) using a rule containing the ALL wildcard.

Config::Access also supports IP address matching of clients and services using the network/netmask number format.

The EXCEPT operator present in the TCP wrappers access control language is not supported.

Public Methods

new

Usage:

$obj = new Config::Access($prefix);
$obj = new Config::Access($prefix, $debug);
$obj = 'Config::Access'->new($prefix);
$obj = 'Config::Access'->new($prefix, $debug);

Returns a newly-initialised Config::Access object. The configuration files are read and parsed. The allow and deny configuration file names are generated from the prefix argument by appending the string '.allow' and '.deny' to the prefix, respectively.

If the $debug parameter is true, then debugging information will be printed to standard output. A list of all access rules will be printed when a Config::Access object is created and a line will be printed for each invocation of the access_query() method.

access_query

Usage:

$result = $obj->access_query($service, $client);

Perform an access query for the specified $service/$client pair. The return value is true if access to the service is allowed for the client, and undefined otherwise.

$result = $obj->access_query($service, $client, $mtype);

Perform an access query for the $service/$client pair and return the match type for the client in the $mtype parameter. The match type refers to the type of rule that allowed or denied the match for the client and can take the following values.

MATCH_SPECIFIC

The match was made to a directly specified rule in either the allow or deny file without using the ALL wildcard.

MATCH_NET_MASK

The match was made using a network/netmask pair.

MATCH_ALL

The match was made using a rule containing the ALL wildcard.

MATCH_FALLTHRU

No matches were made in either the allow or deny file and the match fell through.

Exports

default

none

exportable

MATCH_SPECIFIC MATCH_ALL MATCH_FALLTHRU MATCH_NET_MASK

tags

none

EXAMPLE

The following scripts form a simple example of using the Config::Access module. The access controls for the example correspond to the "mostly closed" model of the TCP wrappers.

cat > test.pl << 'EOF'
#!/usr/bin/perl

use strict;
use Config::Access;

my($access) = Config::Access->new("example");
my($user) = getpwuid($UID);

if (!$access->access_query("beans", $user)) {
    print("Access to service 'beans' denied for user ", $user, "\n");
}

if ($access->access_query("ham", $user)) {
    print("Access to service 'ham' allowed for user ", $user, "\n");
}
EOF

cat > example.allow << 'EOF'
# Example allow file.  Allow all users to service 'ham' and only
# selected users to service 'beans'.
beans: tpot, markus
ham: ALL
EOF

cat > example.deny << 'EOF'
# Example deny file.  Deny all clients access to all services unless
# specifically allowed above.
ALL: ALL
EOF

COPYRIGHT

Copyright (c) 1995,1996,1997,1998 ANU and CSIRO on behalf of the
participants in the CRC for Advanced Computational Systems
('ACSys').

ACSys makes this software and all associated data and documentation
('Software') available free of charge.  You may make copies of the 
Software but you must include all of this notice on any copy.

The Software was developed for research purposes and ACSys does not
warrant that it is error free or fit for any purpose.  ACSys
disclaims any liability for all claims, expenses, losses, damages
and costs any user may incur as a result of using, copying or
modifying the Software.

AUTHOR

Tim Potter <Tim.Potter@anu.edu.au>