1Net::SSH2::KnownHosts(3U)ser Contributed Perl DocumentatiNoent::SSH2::KnownHosts(3)
2
6 Net::SSH2::KnownHosts - SSH 2 knownhosts object
7
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 my $kh = $ssh2->known_hosts;
17 my $n_ent = $kh->readfile($known_hosts_path);
19 # 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 my ($key, $type) = $ssh2->remote_hostkey;
28 my $flags = ( LIBSSH2_KNOWNHOST_TYPE_PLAIN |
30 LIBSSH2_KNOWNHOST_KEYENC_RAW |
31 (($type + 1) << LIBSSH2_KNOWNHOST_KEY_SHIFT) );
32 my $check = $kh->check($hostname, $port, $key, $flags);
34 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 # 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
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 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 The methods currently supported are as follows:
68 readfile (filename)
70 Populates the object with the entries in the given file.
71 It returns the number or entries read or undef on failure.
73 writefile (filename)
75 Saves the known host entries to the given file.
76 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 The "host_format" argument specifies the format of the given host:
81 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 If "SHA1" is selected as host format, the salt must be provided to the
87 salt argument in base64 format.
88 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 The available key formats are as follow:
94 LIBSSH2_KNOWNHOST_KEYENC_RAW
96 LIBSSH2_KNOWNHOST_KEYENC_BASE64
97 Finally, the available key types are as follow:
99 LIBSSH2_KNOWNHOST_KEY_RSA1
101 LIBSSH2_KNOWNHOST_KEY_SSHRSA
102 LIBSSH2_KNOWNHOST_KEY_SSHDSS
103 The comment argument may be undef.
105 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 The "key_type|host_format|key_format" argument has the same meaning as
111 in the "add" method.
112 "undef" may be passed as the port argument.
114 Returns:
116 LIBSSH2_KNOWNHOST_CHECK_MATCH (0)
118 LIBSSH2_KNOWNHOST_CHECK_MISMATCH (1)
119 LIBSSH2_KNOWNHOST_CHECK_NOTFOUND (2)
120 LIBSSH2_KNOWNHOST_CHECK_FAILURE (3)
121 readline (string)
123 Read a known_hosts entry from the given string.
124 For instance, the following piece of code is more or less equivalent to
126 the readfile method:
127 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 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 This method returns undef when some error happens.
141 This method should be considered experimental, the interface may
143 change.
144
146 Net::SSH2, sshd(8).
147
149 Copyright (C) 2013-2015 Salvador Fandiño; all rights reserved.
150 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 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 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 Redistribution and use in source and binary forms, with or without
164 modification, are permitted provided that the following conditions are
165 met:
166 Redistributions of source code must retain the above copyright notice,
168 this list of conditions and the following disclaimer.
169 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 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.
177perl v5.36.0 2023-01-20 Net::SSH2::KnownHosts(3)