1Net::SSH2::KnownHosts(3U)ser Contributed Perl DocumentatiNoent::SSH2::KnownHosts(3)
2
3
4

NAME

6       Net::SSH2::KnownHosts - SSH 2 knownhosts object
7

SYNOPSIS

9         #####################################################################
10         #                                                                   #
11         # WARNING: The API provided by Net::SSH2::KnownHosts is             #
12         # experimental and could change in future versions of the module!!! #
13         #                                                                   #
14         #####################################################################
15
16         my $kh = $ssh2->known_hosts;
17
18         my $n_ent = $kh->readfile($known_hosts_path);
19
20         # a non-existent known_hosts file usually is not an error...
21         unless (defined $n_ent) {
22             if ($ssh2->error != LIBSSH2_ERROR_FILE or -f $known_hosts_path) {
23                 die; # propagate error;
24             }
25         }
26
27         my ($key, $type) = $ssh2->remote_hostkey;
28
29         my $flags = ( LIBSSH2_KNOWNHOST_TYPE_PLAIN |
30                       LIBSSH2_KNOWNHOST_KEYENC_RAW |
31                       (($type + 1) << LIBSSH2_KNOWNHOST_KEY_SHIFT) );
32
33         my $check = $kh->check($hostname, $port, $key, $flags);
34
35         if ($check == LIBSSH2_KNOWNHOST_CHECK_MATCH) {
36             # ok!
37         }
38         elsif ($check == LIBSSH2_KNOWNHOST_CHECK_MISMATCH) {
39             die "host verification failed, the key has changed!";
40         }
41         elsif ($check == LIBSSH2_KNOWNHOST_CHECK_NOTFOUND) {
42             die "host verification failed, key not found in known_hosts file"
43                 if $strict_host_key_checking;
44
45             # else, save new key to file:
46             unless ( $kh->add($hostname, '', $key, "Perl added me", $flags) and
47                      $kh->writefile($known_hosts_path) ) {
48                 warn "unable to save known_hosts file: " . ($ssh2->error)[1];
49             }
50         }
51         else {
52             die "host key verification failed, unknown reason";
53         }
54

DESCRIPTION

56         #####################################################################
57         #                                                                   #
58         # WARNING: The API provided by Net::SSH2::KnownHosts is             #
59         # experimental and could change in future versions of the module!!! #
60         #                                                                   #
61         #####################################################################
62
63       The "knownhosts" object allows one to manipulate the entries in the
64       "known_host" file usually located at "~/.ssh/known_hosts" and which
65       contains the public keys of the already known hosts.
66
67       The methods currently supported are as follows:
68
69   readfile (filename)
70       Populates the object with the entries in the given file.
71
72       It returns the number or entries read or undef on failure.
73
74   writefile (filename)
75       Saves the known host entries to the given file.
76
77   add (hostname, salt, key, comment, key_type|host_format|key_format)
78       Add a host and its associated key to the collection of known hosts.
79
80       The "host_format" argument specifies the format of the given host:
81
82           LIBSSH2_KNOWNHOST_TYPE_PLAIN  - ascii "hostname.domain.tld"
83           LIBSSH2_KNOWNHOST_TYPE_SHA1   - SHA1(salt, host) base64-encoded!
84           LIBSSH2_KNOWNHOST_TYPE_CUSTOM - another hash
85
86       If "SHA1" is selected as host format, the salt must be provided to the
87       salt argument in base64 format.
88
89       The SHA-1 hash is what OpenSSH can be told to use in known_hosts files.
90       If a custom type is used, salt is ignored and you must provide the host
91       pre-hashed when checking for it in the "check" method.
92
93       The available key formats are as follow:
94
95           LIBSSH2_KNOWNHOST_KEYENC_RAW
96           LIBSSH2_KNOWNHOST_KEYENC_BASE64
97
98       Finally, the available key types are as follow:
99
100           LIBSSH2_KNOWNHOST_KEY_RSA1
101           LIBSSH2_KNOWNHOST_KEY_SSHRSA
102           LIBSSH2_KNOWNHOST_KEY_SSHDSS
103
104       The comment argument may be undef.
105
106   check (hostname, port, key, key_type|host_format|key_format)
107       Checks a host and its associated key against the collection of known
108       hosts.
109
110       The "key_type|host_format|key_format" argument has the same meaning as
111       in the "add" method.
112
113       "undef" may be passed as the port argument.
114
115       Returns:
116
117           LIBSSH2_KNOWNHOST_CHECK_MATCH    (0)
118           LIBSSH2_KNOWNHOST_CHECK_MISMATCH (1)
119           LIBSSH2_KNOWNHOST_CHECK_NOTFOUND (2)
120           LIBSSH2_KNOWNHOST_CHECK_FAILURE  (3)
121
122   readline (string)
123       Read a known_hosts entry from the given string.
124
125       For instance, the following piece of code is more or less equivalent to
126       the readfile method:
127
128         my $kh = $ssh2->known_hosts;
129         if (open my $fh, '<', $known_hosts_path) {
130             while (<>) {
131                 eval { $kh->readline($_) }
132                    or warn "unable to parse known_hosts entry $_";
133             }
134         }
135
136   writeline (hostname, port, key, key_type|host_format|key_format)
137       Searches the entry matching the given parameters (as described in the
138       "check" method) and formats it into a line in the known_hosts format.
139
140       This method returns undef when some error happens.
141
142       This method should be considered experimental, the interface may
143       change.
144

SEE ALSO

146       Net::SSH2, sshd(8).
147
149       Copyright (C) 2013-2015 Salvador FandiƱo; all rights reserved.
150
151       This library is free software; you can redistribute it and/or modify it
152       under the same terms as Perl itself, either Perl version 5.8.0 or, at
153       your option, any later version of Perl 5 you may have available.
154
155       The documentation on this file is based on the comments inside
156       "libssh2.h" file from the libssh2 distribution which has the following
157       copyright and license:
158
159       Copyright (c) 2004-2009, Sara Golemon <sarag@libssh2.org> Copyright (c)
160       2009-2012 Daniel Stenberg Copyright (c) 2010 Simon Josefsson
161       <simon@josefsson.org> All rights reserved.
162
163       Redistribution and use in source and binary forms, with or without
164       modification, are permitted provided that the following conditions are
165       met:
166
167       Redistributions of source code must retain the above copyright notice,
168       this list of conditions and the following disclaimer.
169
170       Redistributions in binary form must reproduce the above copyright
171       notice, this list of conditions and the following disclaimer in the
172       documentation and/or other materials provided with the distribution.
173
174       Neither the name of the copyright holder nor the names of any other
175       contributors may be used to endorse or promote products derived from
176       this software without specific prior written permission.
177
178
179
180perl v5.36.0                      2023-01-20          Net::SSH2::KnownHosts(3)
Impressum