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 • authfile
56 Routines associated with loading of RSA SSH1 keys (both public and
58 private) from keyfiles. Contains "_load_public_key",
59 "_load_private_key", and "_save_private_key".
60 Note that this interface is deprecated in favor of the
62 Net::SSH::Perl::Key interface to loading keys.
63 • all
65 All routines. Contains all of the routines listed below.
67
69 _crc32($data)
70 Returns a CRC32 checksum of $data. This uses String::CRC32 internally
71 to do its magic, with the caveat that the "init state" of the checksum
72 is 0xFFFFFFFF, and the result is xor-ed with 0xFFFFFFFF.
73 This is used in SSH1.
75 _compute_session_id($check_bytes, $host_key, $public_key)
77 Given the check bytes ($check_bytes) and the server host and public
78 keys ($host_key and $public_key, respectively), computes the session ID
79 that is then used to uniquely identify the session between the server
80 and client.
81 $host_key and $public_key should be Net::SSH::Perl::Key::RSA1 objects;
83 $check_bytes is an 8-byte string.
84 Returns the session ID.
86 _mp_linearize($int)
88 Converts a multiple-precision integer $int into a byte string. $int
89 should be a Math::GMP object.
90 Returns the byte string.
92 _check_host_in_hostfile($host, $host_file, $host_key)
94 Looks up $host in $host_file and checks the stored host key against
95 $host_key to determine the status of the host.
96 $host_key should be an object of some subclass of Net::SSH::Perl::Key;
98 in particular, it must support the extract_public class method and the
99 equal object method.
100 If the host is not found, returns HOST_NEW.
102 If the host is found, and the keys match, returns HOST_OK.
104 If the host is found, and the keys don't match, returns HOST_CHANGED,
106 which generally indicates a security problem (ie. man-in-the-middle
107 attack).
108 _add_host_to_hostfile($host, $host_file, $host_key)
110 Opens up the known hosts file $host_file and adds an entry for $host
111 with host key $host_key. Dies if $host_file can't be opened for
112 writing.
113 $host_key should be an object of some subclass of Net::SSH::Perl::Key;
115 in particular, it must support the dump_public object method.
116 _load_public_key($key_file)
118 Given the location of a public key file $key_file, reads the RSA public
119 key from that file.
120 If called in list context, returns the key and the comment associated
122 with the key. If called in scalar context, returns only the key.
123 Dies if: the key file $key_file can't be opened for reading; or the key
125 file is "bad" (the ID string in the file doesn't match the
126 PRIVATE_KEY_ID_STRING constant).
127 Returns the RSA key (a Net::SSH::Perl::Key::RSA1 object).
129 _load_private_key($key_file [, $passphrase ])
131 Given the location of a private key file $key_file, and an optional
132 passphrase to decrypt the key, reads the private key from that file. If
133 $passphrase is not supplied, an empty passphrase (the empty string) is
134 tried instead.
135 If called in list context, returns the key and the comment associated
137 with the key. If called in scalar context, returns only the key.
138 Dies if: the key file $key_file can't be opened for reading; the key
140 file is "bad" (the ID string in the file doesn't match the
141 PRIVATE_KEY_ID_STRING constant); the file is encrypted using an
142 unsupported encryption cipher; or the passphrase $passphrase is
143 incorrect.
144 Returns the RSA key (a Net::SSH::Perl::Key::RSA1 object).
146 _save_private_key($key_file, $key, [ $passphrase [, $comment ]])
148 Given a private key $key, and the location of the private key file
149 $key_file, writes out an SSH1 RSA key file to $key_file.
150 If $passphrase is supplied, the private key portion of the file is
152 encrypted with 3DES encryption, using the passphrase $passphrase. If
153 the passphrase is not supplied, an empty passphrase will be used
154 instead. This is useful when using RSA authentication in a non-
155 interactive process, for example.
156 $comment is an optional string that, if supplied, is inserted into the
158 key file and can be used by clients when prompting for the passphrase
159 upon loading the private key, etc. It should be somewhat descriptive of
160 this key file.
161 $key should be a Net::SSH::Perl::Key::RSA1 object.
163 _prompt($prompt [, $default [, $echo ]])
165 Emits an interactive prompt $prompt with an optional default $default.
166 If $echo is true, reads normally from STDIN; if $echo is false, calls
167 _read_passphrase internally to read sensitive information with echo
168 off.
169 Returns the user's answer to the prompt, $default if no answer was
171 provided.
172 _read_passphrase($prompt)
174 Uses Term::ReadKey with echo off to read a passphrase, after issuing
175 the prompt $prompt. Echo is restored once the passphrase has been read.
176 _read_yes_or_no($prompt)
178 Issues the prompt $prompt, which should be a yes/no question; then
179 reads the response, and returns true if the response is yes (or rather,
180 anything starting with 'y', case insensitive).
181 _respond_to_rsa_challenge($ssh, $challenge, $key)
183 Decrypts the RSA challenge $challenge using $key, then the response
184 (MD5 of decrypted challenge and session ID) to the server, using the
185 $ssh object, in an RSA response packet.
186 _rsa_public_encrypt($data, $key)
188 Encrypts the multiple-precision integer $data (a Math::GMP object)
189 using $key.
190 Returns the encrypted data, also a Math::GMP object.
192 _rsa_private_decrypt($data, $key)
194 Decrypts the multiple-precision integer $data (a Math::GMP object)
195 using $key.
196 Returns the decrypted data, also a Math::GMP object.
198
200 Please see the Net::SSH::Perl manpage for author, copyright, and
201 license information.
202perl v5.36.0 2023-01-20 Net::SSH::Perl::Util(3)