view release on metacpan or  search on metacpan

pNETagent.PL  view on Meta::CPAN

and exit immediately.

=back

=head1 CONFIGURATION FILE

pNETagent's configuration file is just that of I<RPC::pServer> with
some additional attributes. Currently its own use is authorization
and encryption.

=head2 Syntax

Empty lines and comment lines (starting with hashes, C<#> charactes)
are ignored. All other lines have the syntax

    var value

White space at the beginning and the end of the line will be removed,
so will white space between C<var> and C<val> be ignored. On the other
hand C<value> may contain white space, for example

    description Free form text

would be valid with C<value> = C<Free form text>.

=head2 Accepting and refusing hosts

Semantically the configuration file is a collection of host definitions,
each of them starting with

    accept|deny mask

where C<mask> is a Perl regular expression matching host names or IP
numbers (in particular this means that you have to escape dots),
C<accept> tells the server to accept connections from C<mask> and
C<deny> forces to refuse connections from C<mask>. The first match
is used, thus the following will accept connections from 192.168.1.*
only

    accept 192\.168\.1\.
    deny .*

and the following will accept all connections except those from
evil.guys.com:

    deny evil\.guys\.com
    accept .*

Default is to refuse connections, thus the C<deny .*> in the first
example is redundant, but of course good style.

=head2 Host based encryption

You can force a client to use encryption. The following example will
accept connections from 192.168.1.* only, if they are encrypted with
the DES algorithm and the key C<0123456789abcdef>:

    accept 192\.168\.1\.
        encryption DES
        key 0123456789abcdef
        encryptModule Crypt::DES

    deny .*

You are by no means bound to use DES. pNETagent just expects a certain
API, namely the methods I<new>, I<keysize>, I<blocksize>, I<encrypt>
and I<decrypt>. For example IDEA is another choice. The above example
will be mapped to this Perl source:

    $encryptModule = "Crypt::DES";
    $encryption = "DES";
    $key = "0123456789abcdef";

    eval "use $encryptModule;"
       . "$crypt = \$encryption->new(pack('H*', \$key));";

I<encryptModule> defaults to <encryption>, this is only needed because
of the brain damaged design of I<Crypt::IDEA> and I<Crypt::DES>, where
module name and class name differ.

=head2 User based authorization

The I<users> attribute allows to restrict access to certain users.
For example the following allows only the users C<joe> and C<jack>
from host C<alpha> and C<joe> and C<mike> from C<beta>:

    accept alpha
        users joe jack

    accept beta
        users joe mike

=head2 User based encryption

Although host based encryption is fine, you might still wish to force
different users to use different encryption secrets. Here's how it
goes:

    accept alpha
        users joe jack
        jack encrypt="Crypt::DES,DES,fedcba9876543210"
        joe encrypt="Crypt::IDEA,IDEA,0123456789abcdef0123456789abcdef"

This would force jack to encrypt with I<DES> and key C<fedcba9876543210>
and joe with I<IDEA> and C<0123456789abcdef0123456789abcdef>. The three
fields of the I<encrypt> entries correspond to the I<encryptionModule>,
I<encryption> and I<key> attributes of the host based encryption.

You note the problem: Of course user based encryption can only be
used when the user has already logged in. Thus we recommend to use
both host based and user based encryption: The former will be used
in the authorization phase and the latter once the client has logged
in. Without user based secrets the host based secret (if any) will
be used for the complete session.

=head2 Query restrictions

You have the possibility to restrict the queries a client may execute
to a predefined set.

Suggest the following lines in the configuration file:

    accept alpha
        sqlRestrict 1
        insert1 INSERT INTO foo VALUES (?, ?)
        insert2 INSERT INTO bla VALUES (?, ?, ?)

    accept beta
        sqlRestrict 0

This allows users connecting from C<beta> to execute any SQL query, but
users from C<alpha> can only insert values into the tables I<foo> and
I<bar>. Clients select the query by just passing the query name
(I<insert1> and I<insert2> in the example above) as an SQL statement
and binding parameters to the statement. Of course the client side must
know how much parameters should be passed. Thus you should use the
following for inserting values into foo from the client:

    my $dbh;
    my $sth = $dbh->prepare("insert1 (?, ?)");
    $sth->execute(1, "foo");
    $sth->execute(2, "bar");


=head1 AUTHOR

    Copyright (c) 1997    Jochen Wiedmann
                          Am Eisteich 9
                          72555 Metzingen
                          Germany

                          Email: wiedmann@neckar-alb.de
                          Phone: +49 7123 14881

You may distribute DBD::pNET and pNETagent under the terms of either the
GNU General Public License or the Artistic License, as specified in the
Perl README file, with the exception that it cannot be placed on a CD-ROM
or similar media for commercial distribution without the prior approval
of the author.

=head1 SEE ALSO