GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  NET::SSH2::KNOWNHOSTS (3)

.ds Aq ’

NAME

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

CONTENTS

SYNOPSIS



  #####################################################################
  #                                                                   #
  # 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 $ok = eval {
      $kh->readfile($known_hosts_path);
  };

  # a non-existent known_hosts file usually is not an error...
  unless (defined $ok) {
      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_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:
      eval {
          $kh->add($hostname, , $key, "Perl added me", $flags);
          $kh->writefile($known_hosts_path);
      } or warn "unable to save known_hosts file: " . ($ssh2->error)[1];
  }
  else {
      die "host key verification failed, unknown reason";
  }



DESCRIPTION



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



The knownhosts object allows one to manipulate the entries in the known_host file usually located at ~/.ssh/known_hosts and which contains the public keys of the already known hosts.

The methods currently supported are as follows:

    readfile (filename)

Populates the object with the entries in the given file.

This method dies when some error happens. On success it returns the number or entries read.

    writefile (filename)

Saves the known host entries to the given file.

This method dies when some error happens.

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

Add a host and its associated key to the collection of known hosts.

The host_format argument specifies the format of the given host:



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



If SHA1 is selected as host format, the salt must be provided to the salt argument. This too base64 encoded.

The SHA-1 hash is what OpenSSH can be told to use in known_hosts files. If a custom type is used, salt is ignored and you must provide the host pre-hashed when checking for it in the check method.

The available key formats are as follow:



    LIBSSH2_KNOWNHOST_KEYENC_RAW
    LIBSSH2_KNOWNHOST_KEYENC_BASE64



Finally, the available key types are as follow:



    LIBSSH2_KNOWNHOST_KEY_RSA1
    LIBSSH2_KNOWNHOST_KEY_SSHRSA
    LIBSSH2_KNOWNHOST_KEY_SSHDSS



The comment argument may be undef.

This method dies when some error happens.

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

Check a host and its associated key against the collection of known hosts.

The key_type|host_format|key_format argument has the same meaning as in the add method.

undef may be passed as the port argument.

Returns:



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



    readline (string)

Read a known_hosts entry from the given string.

This method dies when some error happens.

For instance, the following piece 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 the entry matching the given parameters (as described in the check method) and formats it into a line in the known_hosts format.

This method dies when some error happens.

This method should be considered experimental, the interface may change.

SEE ALSO

Net::SSH2, sshd(8).

COPYRIGHT AND LICENSE

Copyright (C) 2013 Salvador Fandinõ; all rights reserved.

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 libssh2.h file from the libssh2 distribution which has the following copyright and license:

Copyright (c) 2004-2009, Sara Golemon <sarag@libssh2.org> Copyright (c) 2009-2012 Daniel Stenberg Copyright (c) 2010 Simon Josefsson <simon@josefsson.org> All rights reserved.

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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 NET::SSH2::KNOWNHOSTS (3) 2015-12-20

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.