view release on metacpan or  search on metacpan

lib/RPC/pServer.pm  view on Meta::CPAN

    # Get the current encryption mode
    $mode = $server->Encrypt();

    # Currently disable encryption
    $server->Encrypt(undef);

    # Switch back to the old mode
    $server->Encrypt($mode);

=back

=head2 Server attributes

Server attributes will typically be supplied with the C<new>
constructor.

=over 4

=item configFile

RPC::pServer has a builtin authorization mechanism based on
a configuration file. If you want to use this mechanism,
just supply the name of a configuration file with the attribute
configFile and the server will accept or deny connections
based on the configuration file.

The authorization scheme is host based, but you may add
user based functionality with the user and password
attributes. See L</CONFIGURATION FILE> below.

=item client

This attribute is useful in conjunction with the I<configFile>.
If the server has authorized a client by using the config file,
he will create a hash ref with all the client attributes
and store a reference to this hash under the key I<client>.
Thus you can easily extend the configuration file for your
own purposes, at least as long as host based configuration is
sufficient for you.

=item sock

An object of type IO::Socket, if this program is running
as a daemon. An accept() call will be executed on this
socket in order to wait for connections. See L<IO::Socket(3)>.

An inetd based server should leave this attribute empty:
The method will use STDIN and STDOUT instead.

B<Note:> The latter is not yet functionable, I first need
to work out how to create an object of type IO::socket for
an inetd based server's STDIN and STDOUT. It seems this
is currently not supported by IO::Socket.

=item cipher

This attribute can be used to add encryption quite easily. pRPC is not
bound to a certain encryption method, but to a block encryption API. The
attribute is an object supporting the methods I<blocksize>, I<encrypt>
and I<decrypt>. For example, the modules Crypt::DES and Crypt::IDEA
support such an interface.

Do B<not> modify this attribute directly, use the I<encrypt> method
instead!  However, it is legal to pass the attribute to the constructor.

Example:

    use Crypt::DES;
    $crypt = DES->new(pack("H*", "0123456789abcdef"));
    $client->Encrypt($crypt);

    # or, to stop encryption
    $client->Encrypt(undef);

You might prefer encryption being client dependent, so there is the
additional possibility to setup encryption in the server configuration
file. See L</CONFIGURATION FILE>. Client encryption definitions take
precedence over the I<cipher> attribute.

However, you can set or remove encryption on the fly (putting C<undef>
as attribute value will stop encryption), but you have to be sure,
that both sides change the encryption mode.

=item funcTable

This attribute is a hash reference. The hash keys are the
names of methods, that the client may execute on the server.
The hash values are hash references (again). The RPC::pServer
module will use the key 'code' only: It contains a code reference
to the function performing the clients function call. The first
argument of the function call will be the connection object
itself, the second will be the 'funcTable' value. You are free
to use this hash reference in any way you want, the exception
being the 'code' key. The function must return a list: In case
of errors the results will be the values 0, followed by a
textual error message. In case of success, it ought to return
nonzero, followed by the result list being sent to the client.

=item stderr

a value of TRUE will enable logging messages to STDERR, the
default is using syslog(); if the stderr attribute is FALSE,
you might call openlog() to configure the application name
and facility. See L<Sys::Syslog(3)>.

=item debug

this will cause the server to log debugging information
about client requests using the I<Log> method. A value
of 0 disables debugging.

=item application

=item version

=item user

=item password

it is part of the pRPC authorization process, that the client
must obeye a login procedure where he will pass an application
name, a protocol version and optionally a user name and password.
These are not used by pRPC, but when the new method returns with
a connection object, the main program may use these for additional
authorization.

These attributes are read-only.

=item io

this attribute is a Storable object created for communication
with the client. You may use this, for example, when you want to
change the encryption mode with Storable::Encrypt(). See
L<Storable(3)>.

=back

=head1 CONFIGURATION FILE

The server configuration file is currently not much more than a
collection of client names or ip numbers that should be permitted
or denied to connect to the server. Any client is represented by
a definition like the following:

        accept .*\.neckar-alb\.de
            encryption    DES
            key           063fde7982defabc
            encryptModule Crypt::DES

        deny .*

In other words a client definition begins with either C<accept pattern>
or C<deny pattern>, followed by some client attributes, each of the
attributes being on a separate line, followed by the attribute value.
The C<pattern> is a perl regular expression matching either the
clients host name or IP number. In particular this means that you
have to escape dots, for example a client with IP number
194.77.118.1 is represented by the pattern C<194\.77\.118\.1>.

Currently known attributes are:

=over 4

=item encryption

=item key

=item encryptionModule

These will be used for creating an encryption object which is used
for communication with the client, see L<Storable(3)> for
details. The object is created with a sequence like

        use $encryptionModule;
        $cipher = $encryption->new(pack("H*", $key));

I<encryptionModule> defaults to I<encryption>, the reason why we need
both is the brain damaged design of the L<Crypt::IDEA> and L<Crypt::DES>
modules, which use different module and package names without any
obvious reason.

=back

You may add any other attribute you want, thus extending your authorization
file. The RPC::pServer module will simply ignore them, but your main
program will find them in the I<client> attribute of the RPC::pServer
object. This can be used for additional client dependent configuration.

=head1 PREDEFINED FUNCTIONS

RPC::pServer offers some predefined methods which are designed
for ease in work with objects. In short they allow creation of
objects on the server, passing handles to the client and working
with these handles in a fashion similar to the use of the true
objects.

The handle functions need to share some common data, namely a hash
array of object handles (keys) and objects (values). The problem
is, how to allocate these variables. By keeping a multithreaded
environment in mind, we suggest to store the hash on the stack
of the server's main loop.

The handle functions get access to this loop, by looking into
the 'handles' attribute of the respective entry in the
'funcTables' hash. See above for a description of the
'funcTables' hash.

See below for an example of using the handle functions.

=over 4

=item NewHandle

This method can be inserted into the servers function table. The
client may call this function to create objects and receive handles
to the objects. The corresponding entry in the function table 
must have a key I<classes>: This is a list reference with
class names. The client is restricted to create objects of these
classes only.

The I<NewHandle> function expects, that the constructor returns
an object in case of success or 'undef' otherwise. Note, that
this isn't true in all cases, for example the RPC::pServer
and Net::pRPC::Client classes behave different. In that cases
you have to write your own constructor with a special error
handling. The I<StoreHandle> method below will help you.
Constructors with a different name than I<new> are another
example when you need I<StoreHandle> directly.

=item StoreHandle

After you have created an object on behave of the clients request,
you'd like to store it for later use. This is what I<StoreHandle>
does for you. It returns an object handle which may be passed back
to the client. The client can pass the objects back to the server
for use in I<CallMethod> or I<UseHandle>.

=item NewHandle