.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.37
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::SSH::Perl::Util 3"
.TH Net::SSH::Perl::Util 3 "2008-10-02" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Net::SSH::Perl::Util \- Shared utility functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Net::SSH::Perl::Util qw( ... );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fINet::SSH::Perl::Util\fR contains a variety of exportable utility
functions used by the various \fINet::SSH::Perl\fR modules. These
range from hostfile routines, to \s-1RSA\s0 encryption routines, etc.
.PP
None of the routines are actually stored in the \fIUtil\fR module
itself; they are contained within sub-modules that are loaded
on demand by the parent \fIUtil\fR module, which contains a
table mapping function names to sub-module names. The \*(L"on
demand\*(R" is done by including either a function name, or a tag
name (see below), in your \fIuse\fR line. \fINet::SSH::Perl::Util\fR
will take care of loading the sub-module and importing the
requested function(s) into your namespace.
.PP
The routines are exportable by themselves, ie.
.PP
.Vb 1
\&    use Net::SSH::Perl::Util qw( routine_name );
.Ve
.PP
In addition, some of the routines are grouped into bundles that
you can pull in by export tag, ie.
.PP
.Vb 1
\&    use Net::SSH::Perl::Util qw( :bundle );
.Ve
.PP
The groups are:
.IP "* hosts" 4
.IX Item "hosts"
Routines associated with hostfile\-checking, addition, etc.
Contains \f(CW\*(C`_check_host_in_hostfile\*(C'\fR and \f(CW\*(C`_add_host_to_hosfile\*(C'\fR.
.IP "* rsa" 4
.IX Item "rsa"
Routines associated with \s-1RSA\s0 encryption, decryption, and
authentication. Contains \f(CW\*(C`_rsa_public_encrypt\*(C'\fR,
\&\f(CW\*(C`_rsa_private_decrypt\*(C'\fR, and \f(CW\*(C`_respond_to_rsa_challenge\*(C'\fR.
.IP "* ssh1mp" 4
.IX Item "ssh1mp"
Routines associated with multiple-precision integers and the
generation and manipulation of same. Contains \f(CW\*(C`_mp_linearize\*(C'\fR
and \f(CW\*(C`_compute_session_id\*(C'\fR.
.Sp
Because the \s-1SSH1\s0 implementation uses \fIMath::GMP\fR for its
big integers, the functions in \fIssh1mp\fR all deal with
\&\fIMath::GMP\fR objects.
.IP "* ssh2mp" 4
.IX Item "ssh2mp"
Routines associated with \s-1SSH2\s0 big integers, which are
\&\fIMath::Pari\fR objects. Contains \f(CW\*(C`bitsize\*(C'\fR, \f(CW\*(C`bin2mp\*(C'\fR, and
\&\f(CW\*(C`mp2bin\*(C'\fR.
.IP "* authfile" 4
.IX Item "authfile"
Routines associated with loading of \s-1RSA\s0 \s-1SSH1\s0 keys (both public
and private) from keyfiles. Contains \f(CW\*(C`_load_public_key\*(C'\fR,
\&\f(CW\*(C`_load_private_key\*(C'\fR, and \f(CW\*(C`_save_private_key\*(C'\fR.
.Sp
Note that this interface is deprecated in favor of the
\&\fINet::SSH::Perl::Key\fR interface to loading keys.
.IP "* all" 4
.IX Item "all"
All routines. Contains all of the routines listed below.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.Sh "_crc32($data)"
.IX Subsection "_crc32($data)"
Returns a \s-1CRC32\s0 checksum of \fI$data\fR. This uses \fIString::CRC32\fR
internally to do its magic, with the caveat that the \*(L"init state\*(R"
of the checksum is \f(CW0xFFFFFFFF\fR, and the result is xor-ed with
\&\f(CW0xFFFFFFFF\fR.
.PP
This is used in \s-1SSH1\s0.
.ie n .Sh "_compute_session_id($check_bytes, $host_key\fP, \f(CW$public_key)"
.el .Sh "_compute_session_id($check_bytes, \f(CW$host_key\fP, \f(CW$public_key\fP)"
.IX Subsection "_compute_session_id($check_bytes, $host_key, $public_key)"
Given the check bytes (\fI$check_bytes\fR) and the server host and
public keys (\fI$host_key\fR and \fI$public_key\fR, respectively),
computes the session \s-1ID\s0 that is then used to uniquely identify
the session between the server and client.
.PP
\&\fI$host_key\fR and \fI$public_key\fR should be \fINet::SSH::Perl::Key::RSA1\fR
objects; \fI$check_bytes\fR is an 8\-byte string.
.PP
Returns the session \s-1ID\s0.
.Sh "_mp_linearize($int)"
.IX Subsection "_mp_linearize($int)"
Converts a multiple-precision integer \fI$int\fR into a byte string.
\&\fI$int\fR should be a \fIMath::GMP\fR object.
.PP
Returns the byte string.
.Sh "bitsize($int)"
.IX Subsection "bitsize($int)"
Returns the number of bits in \fI$int\fR, which should be a
\&\fIMath::Pari\fR object.
.Sh "bin2mp($octet_string)"
.IX Subsection "bin2mp($octet_string)"
Treats \fI$octet_string\fR as a representation of a big integer in
base 256, and converts the string into that integer. Returns the
integer, a \fIMath::Pari\fR object.
.Sh "mp2bin($int)"
.IX Subsection "mp2bin($int)"
Converts \fI$int\fR, a \fIMath::Pari\fR object, into an octet string
(ie. the reverse of \f(CW\*(C`bin2mp\*(C'\fR). Returns the octet string.
.ie n .Sh "_check_host_in_hostfile($host, $host_file\fP, \f(CW$host_key)"
.el .Sh "_check_host_in_hostfile($host, \f(CW$host_file\fP, \f(CW$host_key\fP)"
.IX Subsection "_check_host_in_hostfile($host, $host_file, $host_key)"
Looks up \fI$host\fR in \fI$host_file\fR and checks the stored host
key against \fI$host_key\fR to determine the status of the host.
.PP
\&\fI$host_key\fR should be an object of some subclass of
\&\fINet::SSH::Perl::Key\fR; in particular, it must support the
\&\fIextract_public\fR class method and the \fIequal\fR object
method.
.PP
If the host is not found, returns \s-1HOST_NEW\s0.
.PP
If the host is found, and the keys match, returns \s-1HOST_OK\s0.
.PP
If the host is found, and the keys don't match, returns
\&\s-1HOST_CHANGED\s0, which generally indicates a security problem
(ie. man-in-the-middle attack).
.ie n .Sh "_add_host_to_hostfile($host, $host_file\fP, \f(CW$host_key)"
.el .Sh "_add_host_to_hostfile($host, \f(CW$host_file\fP, \f(CW$host_key\fP)"
.IX Subsection "_add_host_to_hostfile($host, $host_file, $host_key)"
Opens up the known hosts file \fI$host_file\fR and adds an
entry for \fI$host\fR with host key \fI$host_key\fR. Dies if
\&\fI$host_file\fR can't be opened for writing.
.PP
\&\fI$host_key\fR should be an object of some subclass of
\&\fINet::SSH::Perl::Key\fR; in particular, it must support the
\&\fIdump_public\fR object method.
.Sh "_load_public_key($key_file)"
.IX Subsection "_load_public_key($key_file)"
Given the location of a public key file \fI$key_file\fR, reads
the \s-1RSA\s0 public key from that file.
.PP
If called in list context, returns the key and the comment
associated with the key. If called in scalar context,
returns only the key.
.PP
Dies if: the key file \fI$key_file\fR can't be opened for
reading; or the key file is \*(L"bad\*(R" (the \s-1ID\s0 string in the
file doesn't match the \s-1PRIVATE_KEY_ID_STRING\s0 constant).
.PP
Returns the \s-1RSA\s0 key (a \fINet::SSH::Perl::Key::RSA1\fR object).
.ie n .Sh "_load_private_key($key_file [, $passphrase ])"
.el .Sh "_load_private_key($key_file [, \f(CW$passphrase\fP ])"
.IX Subsection "_load_private_key($key_file [, $passphrase ])"
Given the location of a private key file \fI$key_file\fR,
and an optional passphrase to decrypt the key, reads the
private key from that file. If \fI$passphrase\fR is not
supplied, an empty passphrase (the empty string) is tried
instead.
.PP
If called in list context, returns the key and the comment
associated with the key. If called in scalar context,
returns only the key.
.PP
Dies if: the key file \fI$key_file\fR can't be opened for
reading; the key file is \*(L"bad\*(R" (the \s-1ID\s0 string in the file
doesn't match the \s-1PRIVATE_KEY_ID_STRING\s0 constant); the
file is encrypted using an unsupported encryption cipher;
or the passphrase \fI$passphrase\fR is incorrect.
.PP
Returns the \s-1RSA\s0 key (a \fINet::SSH::Perl::Key::RSA1\fR object).
.ie n .Sh "_save_private_key($key_file, $key\fP, [ \f(CW$passphrase\fP [, \f(CW$comment ]])"
.el .Sh "_save_private_key($key_file, \f(CW$key\fP, [ \f(CW$passphrase\fP [, \f(CW$comment\fP ]])"
.IX Subsection "_save_private_key($key_file, $key, [ $passphrase [, $comment ]])"
Given a private key \fI$key\fR, and the location of the private
key file \fI$key_file\fR, writes out an \s-1SSH1\s0 \s-1RSA\s0 key file to
\&\fI$key_file\fR.
.PP
If \fI$passphrase\fR is supplied, the private key portion of
the file is encrypted with \fI3DES\fR encryption, using the
passphrase \fI$passphrase\fR. If the passphrase is not supplied,
an empty passphrase will be used instead. This is useful
when using \s-1RSA\s0 authentication in a non-interactive process,
for example.
.PP
\&\fI$comment\fR 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.
.PP
\&\fI$key\fR should be a \fINet::SSH::Perl::Key::RSA1\fR object.
.ie n .Sh "_prompt($prompt [, $default\fP [, \f(CW$echo ]])"
.el .Sh "_prompt($prompt [, \f(CW$default\fP [, \f(CW$echo\fP ]])"
.IX Subsection "_prompt($prompt [, $default [, $echo ]])"
Emits an interactive prompt \fI$prompt\fR with an optional
default \fI$default\fR. If \fI$echo\fR is true, reads normally
from \fI\s-1STDIN\s0\fR; if \fI$echo\fR is false, calls
\&\fI_read_passphrase\fR internally to read sensitive
information with echo off.
.PP
Returns the user's answer to the prompt, \fI$default\fR if
no answer was provided.
.Sh "_read_passphrase($prompt)"
.IX Subsection "_read_passphrase($prompt)"
Uses \fITerm::ReadKey\fR with echo off to read a passphrase,
after issuing the prompt \fI$prompt\fR. Echo is restored
once the passphrase has been read.
.Sh "_read_yes_or_no($prompt)"
.IX Subsection "_read_yes_or_no($prompt)"
Issues the prompt \fI$prompt\fR, 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).
.ie n .Sh "_respond_to_rsa_challenge($ssh, $challenge\fP, \f(CW$key)"
.el .Sh "_respond_to_rsa_challenge($ssh, \f(CW$challenge\fP, \f(CW$key\fP)"
.IX Subsection "_respond_to_rsa_challenge($ssh, $challenge, $key)"
Decrypts the \s-1RSA\s0 challenge \fI$challenge\fR using \fI$key\fR,
then the response (\s-1MD5\s0 of decrypted challenge and session
\&\s-1ID\s0) to the server, using the \fI$ssh\fR object, in an
\&\s-1RSA\s0 response packet.
.ie n .Sh "_rsa_public_encrypt($data, $key)"
.el .Sh "_rsa_public_encrypt($data, \f(CW$key\fP)"
.IX Subsection "_rsa_public_encrypt($data, $key)"
Encrypts the multiple-precision integer \fI$data\fR (a
\&\fIMath::GMP\fR object) using \fI$key\fR.
.PP
Returns the encrypted data, also a \fIMath::GMP\fR object.
.ie n .Sh "_rsa_private_decrypt($data, $key)"
.el .Sh "_rsa_private_decrypt($data, \f(CW$key\fP)"
.IX Subsection "_rsa_private_decrypt($data, $key)"
Decrypts the multiple-precision integer \fI$data\fR (a
\&\fIMath::GMP\fR object) using \fI$key\fR.
.PP
Returns the decrypted data, also a \fIMath::GMP\fR object.
.SH "AUTHOR & COPYRIGHTS"
.IX Header "AUTHOR & COPYRIGHTS"
Please see the Net::SSH::Perl manpage for author, copyright,
and license information.