Arc::Connection::Server - Class to handle one connection on the server side
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.
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.
Arc::Connection::Server - Server handle for ARCv2. This class is called by Arc::Server for each incoming connection.
Description: hash of assignment between Command Name and Command Class. See Arc::Command
Default value: undef
Default value: "server"
Description: Callback for SASL (if PLAIN (or equal) mechanisms are used). See Authen::SASL(::Cyrus).
Default value: ""
Description: array of allowed SASL mechanisms
Description: Which protocol is used (0 = ARC/2.0, 1 = ARC/2.1)
Description: name of the server (for SASL)
Description: timeout for all connections (ARCv2 and command) in seconds
Description: Where should all the log output go to ('stderr','syslog')
Default value: 'syslog'
Description: loglevel is combination of bits (1=AUTH,2=USER,4=ERR,8=CMDDEBUG,16=VERBSIDE,32=DEBUG) see _Log method
Default value: 7
Description: Name of the SASL realm, if the user is from the default realm, this is empty
Description: Are we authenticated
Description: IO::Socket for the command connection (encrypted)
Description: parameter after the command
Description: are we connected
Description: IO::Socket for the ARCv2 Connection
Description: array, which ARCv2 protocol commands are allowed to come next
Description: IO::Select for the ARCv2 Connection
Description: username extracted from SASL
Default value: "anonymous"
Description: contains the error message
Description: log to syslog or to STDERR
Default value: 1
Description: Public function, gets the clientsocket (from Arc::Server) and handles it. Handles a connection (main loop).
Returns: true on success, otherwise false
Example:
$arc->HandleClient(sock);
Description: Ends the connection. Do some cleanup.
Returns: always true
$arc->Quit();
Description: See source code for this method. /dev/null for unwanted output.
Description: are we connected?
Returns: true, if the ARCv2 control connection is connected, otherwise false
last unless $arc->IsConnected;
Description: Destructor
Description: User function to get the error msg.
Returns: the error message if any otherwise undef
unless (my $err = $arc->IsError()) { .. } else { print STDERR $err; }
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
return $arc->Log(LOG_ERR,"Message");
Description: Constructor. Initializes the object and returns it blessed. For all sub classes, please override _Init to check the parameter which are passed to the new 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.).
_Init
new
Returns: blessed object of the class
my $this = new Arc::Class ( key => value, key2 => value2 );
Description: send the available SASL mechanisms. Protocol command: AUTH <comma-seperated list of SASL mechansims>\r\n
Returns: true when succesful, otherwise false
$this->_Auth();
Description: tell the client, which SASL mechanism is used. Protocol command: AUTHTYPE <SASL mechansism>\r\n
$this->_Authtype();
Description: Callback function to canonicalize the username (SASL) see Authen::SASL(::Cyrus) for parameter list and how to use.
Description: send a command error msg to client. Protocol command: CMDERR <msg>\r\n
$this->_CmdError("failure.");
Description: command is ready. When the ARCv2 command is ready with its work, the server sends the DONE command on the control connection. Protocol command: DONE\r\n
$this->_Done();
Description: send an error msg to client (Server error). Protocol command: ERR <msg>\r\n
$this->_Error("failure.");
Description: parses the AUTHENTICATE[ <SASL mech>]\r\n, sent by the client. Checks if the demanded SASL mechanism is allowed and returns the selected mechanism.
Description: parses the CMD <cmd>\r\n, sent by the client. check if the command exists, prepares the command connection, executes the command and does cleanups after execution.
Description: does nothing, placeholder for QUIT\r\n command, sent by the client.
Description: parses the SASL <base64 encoded SASL string>\r\n, sent by the client. Sasl challenge/response from the client
Description: Creates the sasl object (server_new) and sends the first sasl challenge/response. Protocol command: SASL <base64 encoded SASL output>\r\n
$this->_StartAuthentication();
Description: Another SASL step Response of a SASL command from the client Protocol command: SASL <base64 encoded SASL outout>\r\n
$this->_StepAuthentication(1);
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.
$this->_CommandConnection();
Description: initialize sasl. This function initializes the __sasl member with an object of Authen::SASL.
__sasl
Authen::SASL
Returns: true if successful, otherwise false
$this->_PrepareAuthentication() || return;
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
while (my $cmd = $this->_RecvCommand() && $this->_ProcessLine($cmd)) {}
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 the ProcessCommand from Arc::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.
Arc::Connection::Server
ProcessCommand
Arc::Connection::Client
$this->ReadWriteBinary(*STDIN,*STDOUT);
Description: receives an ARCv2 Command. (protocol) This function gets a line from _RecvLine and extracts the ARCv2 command and the optional command parameter _cmdparameter.
_RecvLine
_cmdparameter
Returns: ARCv2 command and true if everything works fine, otherwise false
while (my $cmd = $this->_RecvCommand()) { ... }
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.
__linequeue
__partial
Returns: true (and the line) if everything worked fine, otherwise false (undef)
if (my $line = $this->_RecvLine()) { ... }
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
$this->_Sasl($sasl->client_start());
Description: send a command. (protocol) Send a command to the ARCv2 socket.
$this->_SendCommand("CMDPASV",$consock->sockhost.':'.$consock->sockport);
Description: send a line. (protocol) This function sends a command line to the ARCv2 socket.
Returns: true if writing has succeeded, otherwise false.
$this->_SendLine($cmd,"test");
Description: Debug function. Logs messages with "DEBUG"
$this->_Debug("hello","world"); # message will be "hello world"
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.
return $this->_SetError("User is not allowed to do this."); # breaks when an error occured
Arc, Arc::Command, Arc::Connection, Arc::Connection::Server, Arc::Connection::Client, arcx, arcxd, Authen::SASL, Authen::SASL::Cyrus Net::Server::PreFork
Patrick Boettcher <patrick.boettcher@desy.de>
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.
To install Arc, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Arc
CPAN shell
perl -MCPAN -e shell install Arc
For more information on module installation, please visit the detailed CPAN module installation guide.