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_hostfileand_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_linearizeand_compute_session_id.Because the SSH1 implementation uses Math::GMP for its big integers, the functions in ssh1mp all deal with Math::GMP objects.
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::RSA1 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.
_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::RSA1 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::RSA1 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::RSA1 object.
_prompt($prompt [, $default [, $echo ]])
Emits an interactive prompt $prompt with an optional default $default. If $echo is true, reads normally from STDIN; if $echo is false, calls _read_passphrase internally to read sensitive information with echo off.
Returns the user's answer to the prompt, $default if no answer was provided.
_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.