NAME

Arc::Connection::Client - Client class 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

Arc::Connection::Client - Client class for ARCv2

 my $arc = new Arc::Connection::Client(
  server => "hyade11",
  port => 4242,
  timeout => 30,
  loglevel=> 7,
  logdestination => 'stderr',
  service => 'arc',
  sasl_mechanism => undef,
  sasl_cb_user => \&username,
  sasl_cb_auth => \&username,
  sasl_cb_pass => \&password,
 );

 if (my $m = $arc->IsError()) {
  die $m;
 }

 if ($arc->StartSession) {
  $arc->CommandStart("test");
  $arc->CommandWrite("hallo\n");
  if (my $t = $arc->CommandRead()) {
   print $t,"\n"; # should give 'all'
  }
  $arc->CommandEnd();
 }

 sub username
 {
  return $ENV{'USER'};
 }

 sub password
 {
  return <>;
 }

Class VARIABLES

PUBLIC MEMBERS

logdestination reimplemented from Arc

Default value: "stderr"

logfileprefix reimplemented from Arc

Default value: "client"

port

Description: Port to connect to

Default value: undef

protocol reimplemented from Arc::Connection

Description: Which protocol type the shall use.

Default value: 1

sasl_cb_auth

Description: SASL Callback for authname (PLAIN and some other mechs only)

Default value: $ENV{'USER'}

sasl_cb_pass

Description: SASL Callback for password (PLAIN and some other mechs only)

Default value: ""

sasl_cb_user

Description: SASL Callback for username (PLAIN and some other mechs only)

Default value: $ENV{'USER'}

sasl_mechanism

Description: use this mechanism for authentication

Default value: undef

server

Description: Server to connect to

Default value: undef

server_sasl_mechanisms

Description: filled by the sasl mechanisms

Default value: []

service inherited from Arc::Connection

Description: name of the server (for SASL)

Default value: undef

timeout inherited from Arc::Connection

Description: timeout for all connections (ARCv2 and command) in seconds

Default value: undef

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 inherited from Arc::Connection

Description: Are we authenticated

_cmdclientsock inherited from Arc::Connection

Description: IO::Socket for the command connection (encrypted)

Default value: undef

_cmdparameter inherited from Arc::Connection

Description: parameter after the command

Default value: undef

_connected inherited from Arc::Connection

Description: are we connected

_connection inherited from Arc::Connection

Description: IO::Socket for the ARCv2 Connection

Default value: undef

_expectedcmds inherited from Arc::Connection

Description: array, which ARCv2 protocol commands are allowed to come next

Default value: undef

_select inherited from Arc::Connection

Description: IO::Select for the ARCv2 Connection

Default value: undef

_username inherited from Arc::Connection

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

Class METHODS

PUBLIC METHODS

CommandEnd ( )

Description: end the command on the server side. Closes the command connection and ends the command.

Returns: true if successful, false if not. (IsError is set appropriatly)

Example:

$arc->CommandEnd();

CommandEOF ( )

Description: close the write part of the netsock. This function closes the write-part of the command connection.

Returns: true if successful, false if not. (IsError is set appropriatly)

Example:

last unless $arc->CommandEOF();

CommandRead ( )

Description: read data from the Command connection.

Returns: if successful the received data is returned, otherwise false.

Example:

while (my $data = $arc->CommandRead()) { ... }

CommandStart ( ... (command and its parameters) )

Description: start an ARCv2 command This function starts the given ARCv2 Command and enables the Command* functions.

Returns: true if successful, false if not. (IsError is set appropriatly)

Example:

if ($arc->CommandStart()) { ... }

CommandWrite ( ... (data) )

Description: write something to the command. Write something to the standard input of the command started by CommandStart.

Returns: true if successful, false if not. (IsError is set appropriatly)

Example:

last unless $this->CommandWrite();

ProcessCommand ( ... (command and its parameters) )

Description: process a command. This function runs a command with STDIN and STDOUT as clients in- and output control.

Returns: true if successful, false if not. (IsError is set appropriatly)

Example:

$arc->ProcessCommand("whoami");

Quit ( )

Description: ends the connection. Tells the server that we want to end the conversation. (Userlevel) Protocol command: QUIT\r\n

Returns: always true

Example:

$arc->Quit();

StartSession ( )

Description: start an ARCv2 session. This function which will change the status of the connection into a authenticated status. Users have to call this function to be able to run ARCv2 commands afterwards.

Returns: true if authentication was successful, otherwise false.

Example:

if ($arc->StartSession()) { .. }

clean ( ) inherited from Arc::Connection

IsConnected ( ) inherited from Arc::Connection

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 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.).

Returns: blessed object of the class

Example:

my $this = new Arc::Class ( key => value, key2 => value2 );

PROTECTED METHODS

_Authenticate ( )

Description: initiate the authentication. Tells the server which authtype we want to use. Protocol command: AUTHENTICATE [<authtype>]\r\n

Returns: true when succesful, otherwise false

Example:

$this->_Authenticate();

_Cmd ( ... (cmd and parameter) )

Description: send an ARCv2 command request Protocol command: CMD <cmd> <cmdparameter>\r\n

Returns: true when succesful, otherwise false

Example:

$this->_Cmd ("whoami");

_Connect ( )

Description: connects to the server

Returns: true when succesful, otherwise false

Example:

$this->_Connect();

_Init ( ) reimplemented from Arc::Connection

_InitARC2 ( )

Description: initialize the protocol. Sends the initial protocol message ARC/2.0

Returns: true when succesful, otherwise false

Example:

$this->_InitARC2();

_RAUTH ( )

Description: parses the AUTH <list of SASL mech>\r\n, sent by the server

_RAUTHTYPE ( )

Description: parses the AUTHTYPE <SASL mech>\r\n, sent by the server. Which SASL mech the server will use.

_RCMDERR ( )

Description: parses the CMDERR <msg>\r\n, sent by the server. Command specific error, which reports an error during the command

_RCMDPASV ( )

Description: parses CMDPASV <host:port>\r\n, sent by the server. Establish the encrypted command connection.

_RDONE ( )

Description: parses DONE\r\n, sent by the server. This is received when a command is done.

_RERR ( )

Description: parses the ERR <msg>\r\n, sent by the server. Server command, which reports an server-side error

_RSASL ( )

Description: parses the SASL <base64 encoded SASL string>\r\n, sent by the server. Sasl response from the server

_StartAuthentication ( )

Description: initiate the authentication (sasl) Creates the sasl object (client_new). Client begins always and sends the first SASL challenge Protocol command: SASL <base64 encoded SASL output>\r\n

Returns: true when succesful, otherwise false

Example:

$this->_StartAuthentication();

_StepAuthentication ( $first_step )

Description: another SASL step. Response of a SASL command from the server. Protocol command: SASL <base64 encoded SASL outout>\r\n

Returns: true when succesful, otherwise false

Example:

return $this->_StepAuthentication(1);

_CommandConnection ( ) inherited from Arc::Connection

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();

_PrepareAuthentication ( ) inherited from Arc::Connection

Description: initialize sasl. This function initializes the __sasl member with an object of Authen::SASL.

Returns: true if successful, otherwise false

Example:

$this->_PrepareAuthentication() || return;

_ProcessLine ( $cmd ) inherited from Arc::Connection

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 ) inherited from Arc::Connection

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.

Returns: always true

Example:

$this->ReadWriteBinary(*STDIN,*STDOUT);

_RecvCommand ( ) inherited from Arc::Connection

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 ( ) inherited from Arc::Connection

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 ) inherited from Arc::Connection

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 ) inherited from Arc::Connection

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) ) inherited from Arc::Connection

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

AUTHOR

 Patrick Boettcher <patrick.boettcher@desy.de>

COPYRIGHT AND LICENSE

 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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

ABSTRACT

SYNOPSIS

Class VARIABLES

PUBLIC MEMBERS

PROTECTED MEMBERS

PRIVATE MEMBERS

Class METHODS

PUBLIC METHODS

PROTECTED METHODS

PRIVATE METHODS

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions