1Net::SSH::Perl::Util(3)User Contributed Perl DocumentatioNnet::SSH::Perl::Util(3)
2
6 Net::SSH::Perl::Util - Shared utility functions
7
9 use Net::SSH::Perl::Util qw( ... );
10
12 Net::SSH::Perl::Util contains a variety of exportable utility functions
13 used by the various Net::SSH::Perl modules. These range from hostfile
14 routines, to RSA encryption routines, etc.
15 None of the routines are actually stored in the Util module itself;
17 they are contained within sub-modules that are loaded on demand by the
18 parent Util module, which contains a table mapping function names to
19 sub-module names. The "on demand" is done by including either a
20 function name, or a tag name (see below), in your use line.
21 Net::SSH::Perl::Util will take care of loading the sub-module and
22 importing the requested function(s) into your namespace.
23 The routines are exportable by themselves, ie.
25 use Net::SSH::Perl::Util qw( routine_name );
27 In addition, some of the routines are grouped into bundles that you can
29 pull in by export tag, ie.
30 use Net::SSH::Perl::Util qw( :bundle );
32 The groups are:
34 · hosts
36 Routines associated with hostfile-checking, addition, etc.
38 Contains "_check_host_in_hostfile" and "_add_host_to_hosfile".
39 · rsa
41 Routines associated with RSA encryption, decryption, and
43 authentication. Contains "_rsa_public_encrypt",
44 "_rsa_private_decrypt", and "_respond_to_rsa_challenge".
45 · ssh1mp
47 Routines associated with multiple-precision integers and the
49 generation and manipulation of same. Contains "_mp_linearize" and
50 "_compute_session_id".
51 Because the SSH1 implementation uses Math::GMP for its big
53 integers, the functions in ssh1mp all deal with Math::GMP objects.
54 · ssh2mp
56 Routines associated with SSH2 big integers, which are Math::Pari
58 objects. Contains "bitsize", "bin2mp", and "mp2bin".
59 · authfile
61 Routines associated with loading of RSA SSH1 keys (both public and
63 private) from keyfiles. Contains "_load_public_key",
64 "_load_private_key", and "_save_private_key".
65 Note that this interface is deprecated in favor of the
67 Net::SSH::Perl::Key interface to loading keys.
68 · all
70 All routines. Contains all of the routines listed below.
72
74 _crc32($data)
75 Returns a CRC32 checksum of $data. This uses String::CRC32 internally
76 to do its magic, with the caveat that the "init state" of the checksum
77 is 0xFFFFFFFF, and the result is xor-ed with 0xFFFFFFFF.
78 This is used in SSH1.
80 _compute_session_id($check_bytes, $host_key, $public_key)
82 Given the check bytes ($check_bytes) and the server host and public
83 keys ($host_key and $public_key, respectively), computes the session ID
84 that is then used to uniquely identify the session between the server
85 and client.
86 $host_key and $public_key should be Net::SSH::Perl::Key::RSA1 objects;
88 $check_bytes is an 8-byte string.
89 Returns the session ID.
91 _mp_linearize($int)
93 Converts a multiple-precision integer $int into a byte string. $int
94 should be a Math::GMP object.
95 Returns the byte string.
97 bitsize($int)
99 Returns the number of bits in $int, which should be a Math::Pari
100 object.
101 bin2mp($octet_string)
103 Treats $octet_string as a representation of a big integer in base 256,
104 and converts the string into that integer. Returns the integer, a
105 Math::Pari object.
106 mp2bin($int)
108 Converts $int, a Math::Pari object, into an octet string (ie. the
109 reverse of "bin2mp"). Returns the octet string.
110 _check_host_in_hostfile($host, $host_file, $host_key)
112 Looks up $host in $host_file and checks the stored host key against
113 $host_key to determine the status of the host.
114 $host_key should be an object of some subclass of Net::SSH::Perl::Key;
116 in particular, it must support the extract_public class method and the
117 equal object method.
118 If the host is not found, returns HOST_NEW.
120 If the host is found, and the keys match, returns HOST_OK.
122 If the host is found, and the keys don't match, returns HOST_CHANGED,
124 which generally indicates a security problem (ie. man-in-the-middle
125 attack).
126 _add_host_to_hostfile($host, $host_file, $host_key)
128 Opens up the known hosts file $host_file and adds an entry for $host
129 with host key $host_key. Dies if $host_file can't be opened for
130 writing.
131 $host_key should be an object of some subclass of Net::SSH::Perl::Key;
133 in particular, it must support the dump_public object method.
134 _load_public_key($key_file)
136 Given the location of a public key file $key_file, reads the RSA public
137 key from that file.
138 If called in list context, returns the key and the comment associated
140 with the key. If called in scalar context, returns only the key.
141 Dies if: the key file $key_file can't be opened for reading; or the key
143 file is "bad" (the ID string in the file doesn't match the
144 PRIVATE_KEY_ID_STRING constant).
145 Returns the RSA key (a Net::SSH::Perl::Key::RSA1 object).
147 _load_private_key($key_file [, $passphrase ])
149 Given the location of a private key file $key_file, and an optional
150 passphrase to decrypt the key, reads the private key from that file. If
151 $passphrase is not supplied, an empty passphrase (the empty string) is
152 tried instead.
153 If called in list context, returns the key and the comment associated
155 with the key. If called in scalar context, returns only the key.
156 Dies if: the key file $key_file can't be opened for reading; the key
158 file is "bad" (the ID string in the file doesn't match the
159 PRIVATE_KEY_ID_STRING constant); the file is encrypted using an
160 unsupported encryption cipher; or the passphrase $passphrase is
161 incorrect.
162 Returns the RSA key (a Net::SSH::Perl::Key::RSA1 object).
164 _save_private_key($key_file, $key, [ $passphrase [, $comment ]])
166 Given a private key $key, and the location of the private key file
167 $key_file, writes out an SSH1 RSA key file to $key_file.
168 If $passphrase is supplied, the private key portion of the file is
170 encrypted with 3DES encryption, using the passphrase $passphrase. If
171 the passphrase is not supplied, an empty passphrase will be used
172 instead. This is useful when using RSA authentication in a non-
173 interactive process, for example.
174 $comment is an optional string that, if supplied, is inserted into the
176 key file and can be used by clients when prompting for the passphrase
177 upon loading the private key, etc. It should be somewhat descriptive of
178 this key file.
179 $key should be a Net::SSH::Perl::Key::RSA1 object.
181 _prompt($prompt [, $default [, $echo ]])
183 Emits an interactive prompt $prompt with an optional default $default.
184 If $echo is true, reads normally from STDIN; if $echo is false, calls
185 _read_passphrase internally to read sensitive information with echo
186 off.
187 Returns the user's answer to the prompt, $default if no answer was
189 provided.
190 _read_passphrase($prompt)
192 Uses Term::ReadKey with echo off to read a passphrase, after issuing
193 the prompt $prompt. Echo is restored once the passphrase has been read.
194 _read_yes_or_no($prompt)
196 Issues the prompt $prompt, which should be a yes/no question; then
197 reads the response, and returns true if the response is yes (or rather,
198 anything starting with 'y', case insensitive).
199 _respond_to_rsa_challenge($ssh, $challenge, $key)
201 Decrypts the RSA challenge $challenge using $key, then the response
202 (MD5 of decrypted challenge and session ID) to the server, using the
203 $ssh object, in an RSA response packet.
204 _rsa_public_encrypt($data, $key)
206 Encrypts the multiple-precision integer $data (a Math::GMP object)
207 using $key.
208 Returns the encrypted data, also a Math::GMP object.
210 _rsa_private_decrypt($data, $key)
212 Decrypts the multiple-precision integer $data (a Math::GMP object)
213 using $key.
214 Returns the decrypted data, also a Math::GMP object.
216
218 Please see the Net::SSH::Perl manpage for author, copyright, and
219 license information.
220perl v5.12.2 2008-10-02 Net::SSH::Perl::Util(3)