1Net::SSH::Perl::Util(3)User Contributed Perl DocumentatioNnet::SSH::Perl::Util(3)
2
3
4

NAME

6       Net::SSH::Perl::Util - Shared utility functions
7

SYNOPSIS

9           use Net::SSH::Perl::Util qw( ... );
10

DESCRIPTION

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
16       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
24       The routines are exportable by themselves, ie.
25
26           use Net::SSH::Perl::Util qw( routine_name );
27
28       In addition, some of the routines are grouped into bundles that you can
29       pull in by export tag, ie.
30
31           use Net::SSH::Perl::Util qw( :bundle );
32
33       The groups are:
34
35       •   hosts
36
37           Routines associated with hostfile-checking, addition, etc.
38           Contains "_check_host_in_hostfile" and "_add_host_to_hosfile".
39
40       •   rsa
41
42           Routines associated with RSA encryption, decryption, and
43           authentication. Contains "_rsa_public_encrypt",
44           "_rsa_private_decrypt", and "_respond_to_rsa_challenge".
45
46       •   ssh1mp
47
48           Routines associated with multiple-precision integers and the
49           generation and manipulation of same. Contains "_mp_linearize" and
50           "_compute_session_id".
51
52           Because the SSH1 implementation uses Math::GMP for its big
53           integers, the functions in ssh1mp all deal with Math::GMP objects.
54
55       •   authfile
56
57           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
61           Note that this interface is deprecated in favor of the
62           Net::SSH::Perl::Key interface to loading keys.
63
64       •   all
65
66           All routines. Contains all of the routines listed below.
67

FUNCTIONS

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
74       This is used in SSH1.
75
76   _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
82       $host_key and $public_key should be Net::SSH::Perl::Key::RSA1 objects;
83       $check_bytes is an 8-byte string.
84
85       Returns the session ID.
86
87   _mp_linearize($int)
88       Converts a multiple-precision integer $int into a byte string.  $int
89       should be a Math::GMP object.
90
91       Returns the byte string.
92
93   _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
97       $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
101       If the host is not found, returns HOST_NEW.
102
103       If the host is found, and the keys match, returns HOST_OK.
104
105       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
109   _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
114       $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
117   _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
121       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
124       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
128       Returns the RSA key (a Net::SSH::Perl::Key::RSA1 object).
129
130   _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
136       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
139       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
145       Returns the RSA key (a Net::SSH::Perl::Key::RSA1 object).
146
147   _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
151       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
157       $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
162       $key should be a Net::SSH::Perl::Key::RSA1 object.
163
164   _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
170       Returns the user's answer to the prompt, $default if no answer was
171       provided.
172
173   _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
177   _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
182   _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
187   _rsa_public_encrypt($data, $key)
188       Encrypts the multiple-precision integer $data (a Math::GMP object)
189       using $key.
190
191       Returns the encrypted data, also a Math::GMP object.
192
193   _rsa_private_decrypt($data, $key)
194       Decrypts the multiple-precision integer $data (a Math::GMP object)
195       using $key.
196
197       Returns the decrypted data, also a Math::GMP object.
198

AUTHOR & COPYRIGHTS

200       Please see the Net::SSH::Perl manpage for author, copyright, and
201       license information.
202
203
204
205perl v5.36.0                      2023-01-20           Net::SSH::Perl::Util(3)
Impressum