/ 
Net-SSH-Perl-1.02
River stage two • 11 direct dependents • 12 total dependents
/ Net::SSH::Perl::Util

NAME

Net::SSH::Perl::Util - Shared utility functions

SYNOPSIS

use Net::SSH::Perl::Util qw( ... );

DESCRIPTION

Net::SSH::Perl::Util contains a variety of exportable utility functions used by the various Net::SSH::Perl modules. These range from hostfile routines, to RSA encryption routines, etc.

None of the routines are actually stored in the Util module itself; they are contained within sub-modules that are loaded on demand by the parent Util module, which contains a table mapping function names to sub-module names. The "on demand" is done by including either a function name, or a tag name (see below), in your use line. Net::SSH::Perl::Util will take care of loading the sub-module and importing the requested function(s) into your namespace.

The routines are exportable by themselves, ie.

use Net::SSH::Perl::Util qw( routine_name );

In addition, some of the routines are grouped into bundles that you can pull in by export tag, ie.

use Net::SSH::Perl::Util qw( :bundle );

The groups are:

  • hosts

    Routines associated with hostfile-checking, addition, etc. Contains _check_host_in_hostfile and _add_host_to_hosfile.

  • rsa

    Routines associated with RSA encryption, decryption, and authentication. Contains _rsa_public_encrypt, _rsa_private_decrypt, and _respond_to_rsa_challenge.

  • ssh1mp

    Routines associated with multiple-precision integers and the generation and manipulation of same. Contains _mp_linearize and _compute_session_id.

    Because the SSH1 implementation uses Math::GMP for its big integers, the functions in ssh1mp all deal with Math::GMP objects.

  • ssh2mp

    Routines associated with SSH2 big integers, which are Math::Pari objects. Contains bitsize, bin2mp, and mp2bin.

  • authfile

    Routines associated with loading of RSA SSH1 keys (both public and private) from keyfiles. Contains _load_public_key, _load_private_key, and _save_private_key.

    Note that this interface is deprecated in favor of the Net::SSH::Perl::Key interface to loading keys.

  • all

    All routines. Contains all of the routines listed below.

FUNCTIONS

_crc32($data)

Returns a CRC32 checksum of $data. This uses String::CRC32 internally to do its magic, with the caveat that the "init state" of the checksum is 0xFFFFFFFF, and the result is xor-ed with 0xFFFFFFFF.

This is used in SSH1.

_compute_session_id($check_bytes, $host_key, $public_key)

Given the check bytes ($check_bytes) and the server host and public keys ($host_key and $public_key, respectively), computes the session ID that is then used to uniquely identify the session between the server and client.

$host_key and $public_key should be Net::SSH::Perl::Key::RSA objects; $check_bytes is an 8-byte string.

Returns the session ID.

_mp_linearize($int)

Converts a multiple-precision integer $int into a byte string. $int should be a Math::GMP object.

Returns the byte string.

bitsize($int)

Returns the number of bits in $int, which should be a Math::Pari object.

bin2mp($octet_string)

Treats $octet_string as a representation of a big integer in base 256, and converts the string into that integer. Returns the integer, a Math::Pari object.

mp2bin($int)

Converts $int, a Math::Pari object, into an octet string (ie. the reverse of bin2mp). Returns the octet string.

_check_host_in_hostfile($host, $host_file, $host_key)

Looks up $host in $host_file and checks the stored host key against $host_key to determine the status of the host.

$host_key should be an object of some subclass of Net::SSH::Perl::Key; in particular, it must support the extract_public class method and the equal object method.

If the host is not found, returns HOST_NEW.

If the host is found, and the keys match, returns HOST_OK.

If the host is found, and the keys don't match, returns HOST_CHANGED, which generally indicates a security problem (ie. man-in-the-middle attack).

_add_host_to_hostfile($host, $host_file, $host_key)

Opens up the known hosts file $host_file and adds an entry for $host with host key $host_key. Dies if $host_file can't be opened for writing.

$host_key should be an object of some subclass of Net::SSH::Perl::Key; in particular, it must support the dump_public object method.

_load_public_key($key_file)

Given the location of a public key file $key_file, reads the RSA public key from that file.

If called in list context, returns the key and the comment associated with the key. If called in scalar context, returns only the key.

Dies if: the key file $key_file can't be opened for reading; or the key file is "bad" (the ID string in the file doesn't match the PRIVATE_KEY_ID_STRING constant).

Returns the RSA key (a Net::SSH::Perl::Key::RSA object).

_load_private_key($key_file [, $passphrase ])

Given the location of a private key file $key_file, and an optional passphrase to decrypt the key, reads the private key from that file. If $passphrase is not supplied, an empty passphrase (the empty string) is tried instead.

If called in list context, returns the key and the comment associated with the key. If called in scalar context, returns only the key.

Dies if: the key file $key_file can't be opened for reading; the key file is "bad" (the ID string in the file doesn't match the PRIVATE_KEY_ID_STRING constant); the file is encrypted using an unsupported encryption cipher; or the passphrase $passphrase is incorrect.

Returns the RSA key (a Net::SSH::Perl::Key::RSA object).

_save_private_key($key_file, $key, [ $passphrase [, $comment ]])

Given a private key $key, and the location of the private key file $key_file, writes out an SSH1 RSA key file to $key_file.

If $passphrase is supplied, the private key portion of the file is encrypted with 3DES encryption, using the passphrase $passphrase. If the passphrase is not supplied, an empty passphrase will be used instead. This is useful when using RSA authentication in a non-interactive process, for example.

$comment is an optional string that, if supplied, is inserted into the key file and can be used by clients when prompting for the passphrase upon loading the private key, etc. It should be somewhat descriptive of this key file.

$key should be a Net::SSH::Perl::Key::RSA object.

_read_passphrase($prompt)

Uses Term::ReadKey with echo off to read a passphrase, after issuing the prompt $prompt. Echo is restored once the passphrase has been read.

_read_yes_or_no($prompt)

Issues the prompt $prompt, which should be a yes/no question; then reads the response, and returns true if the response is yes (or rather, anything starting with 'y', case insensitive).

_respond_to_rsa_challenge($ssh, $challenge, $key)

Decrypts the RSA challenge $challenge using $key, then the response (MD5 of decrypted challenge and session ID) to the server, using the $ssh object, in an RSA response packet.

_rsa_public_encrypt($data, $key)

Encrypts the multiple-precision integer $data (a Math::GMP object) using $key.

Returns the encrypted data, also a Math::GMP object.

_rsa_private_decrypt($data, $key)

Decrypts the multiple-precision integer $data (a Math::GMP object) using $key.

Returns the decrypted data, also a Math::GMP object.

AUTHOR & COPYRIGHTS

Please see the Net::SSH::Perl manpage for author, copyright, and license information.