Net::SS...ownHosts(3)

📦

version 0.74 · 9 versions

✨ Net::SSH2::KnownHosts ✨

okay bestie, welcome to the User Contributed Perl Documentation page for Net::SSH2::KnownHosts — yes that's the manual name, and yes it's the whole vibe: it's an SSH 2 knownhosts object. 🦋 buckle up, this one's got lore.

💖 NAME 💖

Net::SSH2::KnownHosts — SSH 2 knownhosts object. that's it, that's the name, slay.

🎀 SYNOPSIS 🎀

⚠️ read this first, bestie, i'm not playing: WARNING: The API provided by Net::SSH2::KnownHosts is experimental and could change in future versions of the module!!!

like, it literally ships with its own little warning box in the source. respect.

#####################################################################
#                                                                   #
# WARNING: The API provided by Net::SSH2::KnownHosts is             #
# experimental and could change in future versions of the module!!! #
#                                                                   #
#####################################################################

my $kh = $ssh2->known_hosts;

my $n_ent = $kh->readfile($known_hosts_path);

# a non-existent known_hosts file usually is not an error...
unless (defined $n_ent) {
    if ($ssh2->error != LIBSSH2_ERROR_FILE or -f $known_hosts_path) {
        die; # propagate error;
    }
}

my ($key, $type) = $ssh2->remote_hostkey;

my $flags = ( LIBSSH2_KNOWNHOST_TYPE_PLAIN |
              LIBSSH2_KNOWNHOST_KEYENC_RAW |
              (($type + 1) << LIBSSH2_KNOWNHOST_KEY_SHIFT) );

my $check = $kh->check($hostname, $port, $key, $flags);

if ($check == LIBSSH2_KNOWNHOST_CHECK_MATCH) {
    # ok!
}
elsif ($check == LIBSSH2_KNOWNHOST_CHECK_MISMATCH) {
    die "host verification failed, the key has changed!";
}
elsif ($check == LIBSSH2_KNOWNHOST_CHECK_NOTFOUND) {
    die "host verification failed, key not found in known_hosts file"
        if $strict_host_key_checking;

    # else, save new key to file:
    unless ( $kh->add($hostname, '', $key, "Perl added me", $flags) and
             $kh->writefile($known_hosts_path) ) {
        warn "unable to save known_hosts file: " . ($ssh2->error)[1];
    }
}
else {
    die "host key verification failed, unknown reason";
}

🌈 DESCRIPTION 🌈

🚨 okay we're doing the warning AGAIN, and you know why? because it's in the original twice, and i do not skip details: WARNING: The API provided by Net::SSH2::KnownHosts is experimental and could change in future versions of the module!!!

so the knownhosts object lets you mess with the entries inside the known_host file — the one that usually lives at ~/.ssh/known_hosts — and that file is literally just the public keys of all the hosts you already know. it's the little address book of "yes i trust this server, we've met". 💅

the methods it supports rn are these ones, in order, no skips:

🌸 readfile (filename) 🌸

fills the object up with all the entries from the file you hand it. 📖

it returns the number of entries it read, or undef if it flopped. that's your failure signal, don't ignore it.

💫 writefile (filename) 💫

saves all the known host entries into the file you give it. like, it writes them out. that's the whole job. ✍️

🫶 add (hostname, salt, key, comment, key_type|host_format|key_format) 🫶

adds a host plus its associated key to the collection of known hosts. new friend, added to the list. ✨

the host_format argument decides what format the host you're passing in is:

LIBSSH2_KNOWNHOST_TYPE_PLAIN  - ascii "hostname.domain.tld"
LIBSSH2_KNOWNHOST_TYPE_SHA1   - SHA1(salt, host) base64-encoded!
LIBSSH2_KNOWNHOST_TYPE_CUSTOM - another hash

if you pick SHA1 as the host format, then you gotta hand the salt to the salt argument, and it has to be in base64 format. non-negotiable, that's just the deal.

fun fact incoming: the SHA-1 hash is literally the thing OpenSSH can be told to use in known_hosts files. iykyk. and if you're using a custom type instead? then salt gets ignored, and you must provide the host pre-hashed when you check for it in the check method. so like, do the homework yourself, bestie.

the key formats you can use are:

LIBSSH2_KNOWNHOST_KEYENC_RAW
LIBSSH2_KNOWNHOST_KEYENC_BASE64

and finally (iconic lineup honestly), the key types are:

LIBSSH2_KNOWNHOST_KEY_RSA1
LIBSSH2_KNOWNHOST_KEY_SSHRSA
LIBSSH2_KNOWNHOST_KEY_SSHDSS

oh and the comment argument? that one may be undef. no comment, no problem. 🙈

👑 check (hostname, port, key, key_type|host_format|key_format) 👑

checks a host and its associated key against the collection of known hosts. vibe check, but for cryptography. 🔥

the key_type|host_format|key_format argument means the exact same thing as it does in the add method. same rules, same energy.

undef may be passed as the port argument. yes really. it's allowed.

it returns one of these:

LIBSSH2_KNOWNHOST_CHECK_MATCH    (0)
LIBSSH2_KNOWNHOST_CHECK_MISMATCH (1)
LIBSSH2_KNOWNHOST_CHECK_NOTFOUND (2)
LIBSSH2_KNOWNHOST_CHECK_FAILURE  (3)

🧚 readline (string) 🧚

reads a single known_hosts entry out of the string you give it. one line at a time, very demure.

for instance — and this is so cute — the following chunk of code is more or less equivalent to the readfile method:

my $kh = $ssh2->known_hosts;
if (open my $fh, '<', $known_hosts_path) {
    while (<>) {
        eval { $kh->readline($_) }
           or warn "unable to parse known_hosts entry $_";
    }
}

⭐ writeline (hostname, port, key, key_type|host_format|key_format) ⭐

searches for the entry that matches the parameters you gave it (described over in the check method, go look) and formats it into a line in the known_hosts format. 📝

this method returns undef when some error happens. undef = something went wrong, okay?

🚨 and heads up: this method should be considered experimental — the interface may change. so don't build your whole personality on it.

💜 SEE ALSO 💜

Net::SSH2
sshd(8)

🌟 COPYRIGHT AND LICENSE 🌟

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.0 or, at your option, any later version of Perl 5 you may have available.

the documentation on this file is based on the comments inside the libssh2.h file from the libssh2 distribution, which has the following copyright and license:

redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
neither the name of the copyright holder nor the names of any other contributors may be used to endorse or promote products derived from this software without specific prior written permission.

and that's the whole page, bestie, you ate it. 🎀 this was perl v5.42.0, dated 2025-07-25, and it's Net::SS...ownHosts(3) signing off — go verify some host keys, you absolute main character. 💖🦋

📦 where this page comes from

fedora 43: perl-Net-SSH2 0.74-4.fc43 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms