NAME
Arc::Connection - Abstract base class for connection handling for ARCv2
DESCRIPTION
ARC allows non-privileged users to run privileged commands on the server. The server decides if the user is allowed to run this command through ACL.
This file is a part of the Perl ARCv2 module suite. ARCv2 is a rewrite of ARC by R.Toebbicke, CERN, Switzerland in Perl.
ABSTRACT
From ARC by R. Toebbicke, modified by me: User requests are shipped from a client machine to a server using a SASL-authenticated socket connection. The purpose is to convey requests such as privileged commands (e.g. AFS, Crontab) to be executed on the server under appropriate privileges. Given that all privileges are confined to the server and the server can be programmed as to filter and check the command to be executed, the client machine can be less trusted than the server.
Because ARC-v1-Commands are written in perl anyway, implementing the client/server in perl makes sense. Platform-independence and "easy-to-read" source code are welcome too. This package provides two perl command line scripts (arcx, arcxd). They can be used for working with the ARC server from the command line, resp. to start the server.
SYNOPSIS
This module is part of the module suite ARCv2.
This is the connection module from ARCv2. If we would use C++, we would say this is an abstract class of an ARCv2 Connection. This class provides common methods to its derived classes. Such as for authentication and basic ARCv2 protocols.
Class VARIABLES
PUBLIC MEMBERS
- protocol
-
Description: Which protocol is used (0 = ARC/2.0, 1 = ARC/2.1)
Default value: undef
- service
-
Description: name of the server (for SASL)
Default value: undef
- timeout
-
Description: timeout for all connections (ARCv2 and command) in seconds
Default value: undef
- logdestination inherited from Arc
-
Description: Where should all the log output go to ('stderr','syslog')
Default value: 'syslog'
- logfileprefix inherited from Arc
-
Description: Prepended to every log entry
Default value: ""
- loglevel inherited from Arc
-
Description: loglevel is combination of bits (1=AUTH,2=USER,4=ERR,8=CMDDEBUG,16=VERBSIDE,32=DEBUG) see _Log method
Default value: 7
PROTECTED MEMBERS
- _authenticated
-
Description: Are we authenticated
- _cmdclientsock
-
Description: IO::Socket for the command connection (encrypted)
Default value: undef
- _cmdparameter
-
Description: parameter after the command
Default value: undef
- _connected
-
Description: are we connected
- _connection
-
Description: IO::Socket for the ARCv2 Connection
Default value: undef
- _expectedcmds
-
Description: array, which ARCv2 protocol commands are allowed to come next
Default value: undef
- _select
-
Description: IO::Select for the ARCv2 Connection
Default value: undef
- _username
-
Description: username extracted from SASL
Default value: "anonymous"
- _error inherited from Arc
-
Description: contains the error message
Default value: undef
- _syslog inherited from Arc
-
Description: log to syslog or to STDERR
Default value: 1
PRIVATE MEMBERS
- __linequeue
-
Description: internal line buffer (idea From Net::Cmd)
Default value: []
- __partial
-
Description: a partial line (idea From Net::Cmd)
Default value: ""
- __sasl
-
Description: Authen::SASL Handle
Default value: undef
Class METHODS
PUBLIC METHODS
- clean ( )
- IsConnected ( )
-
Description: are we connected?
Returns: true, if the ARCv2 control connection is connected, otherwise false
Example:
last unless $arc->IsConnected;
- DESTROY ( ) inherited from Arc
-
Description: Destructor
- IsError ( ) inherited from Arc
-
Description: User function to get the error msg.
Returns: the error message if any otherwise undef
Example:
unless (my $err = $arc->IsError()) { .. } else { print STDERR $err; }
- Log ( $facility, ... (message) ) inherited from Arc
-
Description: Log function. Logs messages to 'logdestination' if 'loglevel' is is set appropriatly. loglevel behaviour has changed in the 1.0 release of ARCv2, the "Arc"-class can export LOG_AUTH (authentication information), LOG_USER (connection information), LOG_ERR (errors), LOG_CMD (ARCv2 addition internal command information), LOG_SIDE (verbose client/server-specific information), LOG_DEBUG (verbose debug information). It possible to combine the levels with or (resp. +) to allow a message to appear when not all loglevels are requested by the user. Commonly used for logging errors from application level.
Returns: always false
Example:
return $arc->Log(LOG_ERR,"Message");
- new ( %hash, key => val, ... ) inherited from Arc
-
Description: Constructor. Initializes the object and returns it blessed. For all sub classes, please override
_Init
to check the parameter which are passed to thenew
function. This is necessary because you are not able to call the the new method of a parent class, when having a class name (new $class::SUPER::new, does not work.).Returns: blessed object of the class
Example:
my $this = new Arc::Class ( key => value, key2 => value2 );
PROTECTED METHODS
- _CommandConnection ( )
-
Description: initializes command connection. (protocol) Starts listen on the Command socket and sends the CMDPASV command.
Returns: true if everything went like expected, otherwise false.
Example:
$this->_CommandConnection();
- _Init ( ) reimplemented from Arc
- _PrepareAuthentication ( )
-
Description: initialize sasl. This function initializes the
__sasl
member with an object ofAuthen::SASL
.Returns: true if successful, otherwise false
Example:
$this->_PrepareAuthentication() || return;
- _ProcessLine ( $cmd )
-
Description: process an ARCv2 command. (protocol) Process a command by evaling $this->_R$cmd. Also checks if this command was expected now (looks into the $this->{_expectedcmds} array). Used by client and server.
Returns: true, if ARCv2 command has been in place, otherwise false
Example:
while (my $cmd = $this->_RecvCommand() && $this->_ProcessLine($cmd)) {}
- _ReadWriteBinary ( *locfdin, *locfdout )
-
Description: function for reading and writing on the command connection. This function is always used by the
Arc::Connection::Server
to handle command data. When calling theProcessCommand
fromArc::Connection::Client
this function is also used. Data is read from the local socket resp. pipe and is written encrypted to the network socket. The other side reads the data from network socket, decrypts it and writes it to its local socket. This function behaves differently on client and server sides, when the local or network socket is closed.Returns: always true
Example:
$this->ReadWriteBinary(*STDIN,*STDOUT);
- _RecvCommand ( )
-
Description: receives an ARCv2 Command. (protocol) This function gets a line from
_RecvLine
and extracts the ARCv2 command and the optional command parameter_cmdparameter
.Returns: ARCv2 command and true if everything works fine, otherwise false
Example:
while (my $cmd = $this->_RecvCommand()) { ... }
- _RecvLine ( )
-
Description: receive a line (command). (protocol) This function receives data from the ARCv2 connection and fills the internal
__linequeue
and__partial
. It returns a line from the internal buffer if there is any. It also handles timeouts and "connection closed by foreign host"'s.Returns: true (and the line) if everything worked fine, otherwise false (undef)
Example:
if (my $line = $this->_RecvLine()) { ... }
- _Sasl ( $saslstr )
-
Description: send the ARCv2 SASL command. (protocol) This function encodes the output from sasl_*_start and sasl_*_step with Base-64 and sends it to the other side
Returns: true if successful, otherwise false
Example:
$this->_Sasl($sasl->client_start());
- _SendCommand ( $cmd, $parameter )
-
Description: send a command. (protocol) Send a command to the ARCv2 socket.
Returns: true if successful, otherwise false
Example:
$this->_SendCommand("CMDPASV",$consock->sockhost.':'.$consock->sockport);
- _SendLine ( ... (line) )
-
Description: send a line. (protocol) This function sends a command line to the ARCv2 socket.
Returns: true if writing has succeeded, otherwise false.
Example:
$this->_SendLine($cmd,"test");
- _Debug ( ... (message) ) inherited from Arc
-
Description: Debug function. Logs messages with "DEBUG"
Returns: always false
Example:
$this->_Debug("hello","world"); # message will be "hello world"
- _SetError ( ... (message) ) inherited from Arc
-
Description: SetError function. This function prepends the error message (@_) to an existing error message (if any) and logs the message with LOG_ERR facility. Use this function for setting an error from class level. Users should use IsError to get the message if a function failed.
Returns: always false
Example:
return $this->_SetError("User is not allowed to do this."); # breaks when an error occured
PRIVATE METHODS
SEE ALSO
Arc, Arc::Command, Arc::Connection, Arc::Connection::Server, Arc::Connection::Client, arcx, arcxd, Authen::SASL, Authen::SASL::Cyrus Net::Server::PreFork
AUTHOR
Patrick Boettcher <patrick.boettcher@desy.de>
COPYRIGHT AND LICENSE
Copyright (c) 2003-5 Patrick Boettcher <patrick.boettcher@desy.de> and others. All rights reserved. Zeuthen, Germany, (old) Europe
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
Special thanks go to:
DESY Zeuthen, in particular:
- Wolfgang Friebel for bleeding edge testing and heavy bug reporting (and the idea of reimplementing ARC).
- Waltraut Niepraschk and Andreas Haupt for their help and support during the development.