NAME

Symantec::PCAnywhere::Profile - Base class for pcAnywhere utility functions

SYNOPSIS

This class should not be instantiated or used by itself. Use one of its subclasses instead.

DESCRIPTION

Provides methods common to pcAnywhere utility functions. See METHODS. Below is an overview of the general decoding mechaism.

FILE OBSCURING ALGORITHM

The general idea of the file obscuring algorithm is that each byte is XOR'd with the previous byte plus an incrementing eight-bit counter. For reasons unknown to us, there seems to be some kind of shift in the algorithm starting at byte 448, so we split up our decoding into a "first part" and a "second part).

for each byte 
do
	char = thisbyte (XOR) prevbyte (XOR)  counter++
done

FIELD BREAKDOWN

The interesting fields appear to be in fixed positions: this was very helpful.

String fields seem to be terminated with a NUL byte, and we have observed that changing a long value to a short one leaves the tail end of the long field inside the file. In some cases we do not ever care about the "old" value, but since passwords and login names are disabled by NULing out the first byte, the bytes that remain might be interesting. See "FIELD DECODING" for further discussion.

We believe that some fields are slightly overloaded - we have seen overlap - and they mainly revolve around the GATEWAY fields. We don't know how pcAnywhere gateways work well enough to really know what to make of it.

FIELD DECODING

We define all the fields of interest in a hash to allow us to do a bit more than just decode: perhaps a bit of reporting or double-checking for overlaps and the like.

Each entry has a name, which is used as the key to the user-returned hash, plus the zero-based offset into the setring, the length, and a "type". The type is one of:

0 = string, strip everything after first NUL byte
1 = string, strip trailing NUL bytes
2 = binary
3 = little-endian 16-bit word

The reason we allow for type #1 is to avoid stripping NUL bytes from a few fields, such as passwords. If you enter a login name or password, but then disable the "auto-login", pcAnywhere simply NULs out the first byte: this is still useful information.

The original code on which this module is based was used for penetration testing, and so Type 1 was useful for recovering partly-obscured credentials. However, using Type 1 hampers the more likely use of this module, so the Hostname, Domain_Logname, and Password fields have been changed from Type 1 to Type 0.

Type 3 currently exists only for decoding port numbers.

EXPORT

None.

METHODS

new

The "new" constructor takes any number of arguments and sets the appropriate flags internally before returning a new object. The object is implemented as a blessed hash; if more than one argument is passed in, the arguments are considered as a list of key-value pairs which are inserted into the object data. Both "regular" and dash-style arguments are supported.

load_from_file

$chf->load_from_file($filename);

Loads a file for processing.

set_attrs

$chf->set_attrs(
	PhoneNumber	=> 5551234,
	AreaCode	=> 800,
	IPAddress	=> '172.0.0.11',
	ControlPort	=> '4763'
);

Sets the attributes of the file; pass in any number of key-value pairs.

set_attr

$chf->set_attr($attr	=> $value);

This convenience method sets the value for only one attribute. Note that set_attrs() can be called with exactly the same arguments as this method.

get_attrs

my @query = qw(PhoneNumber AreaCode IPAddress ControlPort);
my $attr = $chf->get_attrs(@query);
my $attrs = $chf->get_attrs(@query);

Pass in a list of items whose attributes you wish to retrieve. Returns a reference to a hash whose keys are the values you passed in and whose values are the attributes retrieved.

get_attr

my $value = $chf->get_attr($attr);

This helper method gets the value for only one attribute and returns it as a scalar.

get_fields

my @fields = $self->get_fields;

Returns (in hash order) the names of fields that can be read from or written to the file.

TO DO

Our understanding of the decoding process just looks incomplete: it's complicated enough for no good reason that we really just suspect that we have done it wrong. There are a couple of glitches even in the current decoding that it requires a bit more thought.

Implement better error handling.

Explain the default values for certain special fields.

Create (more) tests!

SEE ALSO

See Symantec::PCAnywhere::Profile::CHF for a useful subclass of this module.

AUTHOR

Darren Kulp, <kulp@thekulp.com>, based on code from Stephen J. Friedl, (http://unixwiz.net/)

COPYRIGHT AND LICENSE

Copyright (C) 2006 by Darren Kulp

Contains code placed in the public domain 2002 by Stephen Friedl

"Symantec" and "pcAnywhere" are trademarks of Symantec Corp.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.