/ 
Symantec-PCAnywhere-Profile-0.06
River stage zero No dependents
/ Symantec::PCAnywhere::Profile

NAME

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

VERSION

Version 0.06

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.

METHODS

PUBLIC

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, optionally taking a filename.

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.

write_to_file

Writes data to a file, optionally taking a filename (if none is supplied, the filename object field is used)

decode
$chf->decode;
$chf->decode($chfdata);

Decodes the currently-loaded data or new data passed in.

encode
$chf->encode;

Returns an encoded representation of the CHF file, constructed from the attributes previously set by set_attrs or existing from a constructor or load_from_file() call.

_encode_pca_file
_decode_pca_file

Method declarations ("abstract" methods) to be implmented by subclasses

PRIVATE

_rawencode

This is the low-level engine that handles the XOR encoding of the byte stream. It knows nothing of pcAnywhere data, and it can be called on multiple sections of the file independently.

$roll - starting value of the rolling counter
$prev - the "previous byte" value upon entry to the loop
$str  - the string we're to encode
_rawdecode

This is the low-level engine that handles the XOR decoding of the byte stream. It knows nothing of pcAnywhere data, and it can be called on multiple sections of the file independently.

$roll - starting value of the rolling counter
$prev - the "previous byte" value upon entry to the loop
$str  - the string we're to decode
_edit_pca_file

Performs encoding operations (internal)

_parse_pca_file

Teases the binary format into a hash (internal)

_load

Does loading of filedata if necessary

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.

Get rid of the silly prototype definitions on the method definitions.

Create (more) tests!

SEE ALSO

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

AUTHOR

Darren Kulp, <darren at kulp.ch>, based on code from Stephen J. Friedl, (http://unixwiz.net/)

ACKNOWLEDGEMENTS

This module is based on 'pcainfo' from Stephen J. Friedl. His work, which is in the public domain, has been modified to add encoding capabilities to allow creating CHFs (pcAnywhere connection profiles). Thanks, Stephen!

The addition of encoding and an OO interface, as well as the packaging as a CPAN module and the correcting of some typographical errors, semantic redundancies, and spelling mistakes, was done by Darren Kulp.

COPYRIGHT AND LICENSE

This code is in the public domain. Contains code placed in the public domain 2002 by Stephen Friedl.

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

BUGS

Please report any bugs or feature requests to bug-symantec-pcanywhere-profile at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Symantec-PCAnywhere-Profile. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Symantec::PCAnywhere::Profile

You can also look for information at: