ssh2.knownhost

class ssh2.knownhost.KnownHost

Manage known host entries.

add(self, bytes host, bytes salt, bytes key, int typemask)

Deprecated - use self.addc

addc(self, bytes host, bytes key, int typemask, bytes salt=None, bytes comment=None)

Adds a host and its key to known hosts collection.

Note - libssh2 expects correct use of hashed hosts when LIBSSH2_KNOWNHOST_TYPE_SHA1 is part of typemask. Incorrect use of hashed host typemask without appropriate hashed host and salt values will result in host entries being added to the collection without a host name.

Parameters

  • host (bytes) – Host to add key for.

  • key (bytes) – Key to add.

  • typemask – Bitmask of one of each from ssh2.knownhost.LIBSSH2_KNOWNHOST_TYPE_*, ssh2.knownhost.LIBSSH2_KNOWNHOST_KEYENC_* and ssh2.knownhost.LIBSSH2_KNOWNHOST_KEY_* for example for plain text host, raw key encoding and SSH RSA key type would be LIBSSH2_KNOWNHOST_TYPE_PLAIN | LIBSSH2_KNOWNHOST_KEYENC_RAW | LIBSSH2_KNOWNHOST_KEY_SSHRSA.

  • salt (bytes) – Salt used for host hashing if host is hashed. Defaults to None.

  • comment (bytes) – Comment to add for host. Defaults to None.

Raises

ssh2.exceptions.KnownHostAddError on errors adding known host entry.

check(self, bytes host, bytes key, int typemask)

Deprecated - use self.checkp

checkp(self, bytes host, int port, bytes key, int typemask)

Check a host and its key against the known hosts collection and return known host entry, if any.

Note that server key provided to this function must be base64 encoded only if checking against a self.addc added known public key. When using self.readfile and a known_hosts file, encoding is not needed.

ssh2.exceptions.KnownHostCheckError is base class for all host check error exceptions and can be used to catch all host check errors.

Parameters

  • host (bytes) – Host to check.

  • key (bytes) – Key of host to check.

  • typemask – Bitmask of one of each from ssh2.knownhost.LIBSSH2_KNOWNHOST_TYPE_*, ssh2.knownhost.LIBSSH2_KNOWNHOST_KEYENC_* and ssh2.knownhost.LIBSSH2_KNOWNHOST_KEY_* for example for plain text host, raw key encoding and SSH RSA key type would be LIBSSH2_KNOWNHOST_TYPE_PLAIN | LIBSSH2_KNOWNHOST_KEYENC_RAW | LIBSSH2_KNOWNHOST_KEY_SSHRSA.

Raises

ssh2.exceptions.KnownHostCheckMisMatchError on provided key mis-match error with found key from known hosts.

Raises

ssh2.exceptions.KnownHostCheckNotFoundError on host not found in known hosts.

Raises

ssh2.exceptions.KnownHostCheckFailure on failure checking known host entry.

Raises

ssh2.exceptions.KnownHostCheckError on unknown errors checking known host.

Return type

ssh2.knownhost.KnownHostEntry

delete(self, KnownHostEntry entry)

Delete given known host entry from collection of known hosts.

Parameters

entry (ssh2.knownhost.KnownHostEntry) – Known host entry to delete.

Raises

ssh2.exceptions.KnownHostDeleteError on errors deleting host entry.

get(self, KnownHostEntry prev=None)

Retrieve all host entries in known hosts collection.

Parameters

prev – (Optional) Existing known host entry to start retrieval from. All hosts are retrieved when prev is None which is the default.

Raises

ssh2.exceptions.KnownHostGetError on errors retrieving known host collection.

Return type

list(ssh2.knownhost.KnownHostEntry)

readfile(self, filename, int f_type=c_ssh2.LIBSSH2_KNOWNHOST_FILE_OPENSSH)

Read known hosts file and add hosts to known hosts collection. Only OpenSSH known hosts file format is currently supported.

Returns number of successfully read host entries.

Parameters

filename (str) – File name to read.

Raises

ssh2.exceptions.KnownHostReadFileError on errors reading file.

Return type

int

readline(self, bytes line, int f_type=c_ssh2.LIBSSH2_KNOWNHOST_FILE_OPENSSH)

Read line from known hosts file and add to known hosts collection. Only OpenSSH known hosts file format is currently supported.

Note - When using readline, the key values returned by self.get will need to be base64 encoded as libssh2’s readline does not encode them when adding, unlike self.readfile and self.addc.

Parameters

line (bytes) – Byte string representing line to read.

Raises

ssh2.exceptions.KnownHostReadLineError on errors reading line.

writefile(self, filename, int f_type=c_ssh2.LIBSSH2_KNOWNHOST_FILE_OPENSSH)

Write all known host entries to file. Only OpenSSH known hosts file format is currently supported.

Parameters

filename (str) – File name to write known hosts to.

Raises

ssh2.exceptions.KnownHostWriteFileError on errors writing to file.

writeline(self, KnownHostEntry entry, int f_type=c_ssh2.LIBSSH2_KNOWNHOST_FILE_OPENSSH, size_t buf_len=1024)

Convert a single known host entry to a single line of output for writing. Only OpenSSH known hosts file format is currently supported.

Parameters

entry (ssh2.knownhost.KnownHostEntry) – Known host entry to write line for.

Raises

ssh2.exceptions.KnownHostWriteLineError on errors writing line.

Return type

bytes

class ssh2.knownhost.KnownHostEntry

Class representing a single known host entry.

key

Key byte string.

Key is stored base64 encoded according to libssh2 documentation and is returned by this property as a base64 decoded byte string.

Note that in some cases, like keys added by ssh2.knownhost.KnownHost.readline(), the stored key is not base64 encoded, contrary to documentation, and KnownHostEntry.key will need to be re-encoded as base64 to get actual key.

magic

Entry magic number.

name

Name of host.

typemask

Type mask of host entry.