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.
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.mp
Routines associated with multiple-precision integers and the generation and manipulation of same. Contains
_mp_linearizeand_compute_session_id.authfile
Routines associated with loading of RSA SSH keys (both public and private) from keyfiles. Contains
_load_public_key,_load_private_key, and_save_private_key.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.
_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 hash references with three keys: bits, n, and e. n and e should be multiple-precision integers (Math::GMP objects).
Returns the session ID.
_mp_linearize($length, $key)
Converts a multiple-precision integer $key into a byte string. $length should be the number of bytes to linearize, which is generally the number of bytes in the key.
Note that, unlike the key arguments to _compute_session_id, $key here is just the multiple-precision integer, not the hash reference.
Returns the linearized 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.
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 problem.
_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.
_load_public_key($key_file)
Given the location of a public key file $key_file, reads the 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).
The key returned is in the form of a public key--a hash reference with three keys: bits, n, and e. n and e and multiple-precision integers (Math::GMP objects).
_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.
The key returned is in the form of a private key--a hash reference with seven keys: bits, n, e, d, u, p, and q. All but bits are multiple-precision integers (Math::GMP objects).
_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 SSH 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 hash reference with seven keys: bits, n, e, d, u, p, and q. All but bits are multiple-precision integers (Math::GMP objects).
_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.
_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.