Known host API implementation, tests and documentation.

Author: Pan

.travis.yml

@@ -29,7 +29,7 @@ script:
   - cd dist; pip install *; cd ..
 jobs:
   include:
-    - stage: OSX 10.12 wheel build
+    - stage: OSX wheel build
       os: osx
       if: tag IS present
       before_install:
@@ -54,7 +54,7 @@ jobs:
           fi
       language: generic
       python: skip
-    - stage: OSX 10.11 wheel build
+    - stage: OSX wheel build
       os: osx
       osx_image: xcode8
       if: tag IS present
@@ -80,7 +80,7 @@ jobs:
           fi
       language: generic
       python: skip
-    - stage: OSX 10.10 wheel build
+    - stage: OSX wheel build
       os: osx
       osx_image: xcode6.4
       if: tag IS present

Changelog.rst

@@ -1,6 +1,17 @@
 Change Log
 =============
 
+0.8.0
+++++++
+
+Changes
+---------
+
+* Implemented known host API, all functions.
+* Added `hostkey` method on `Session` class for retrieving server host key.
+* Added server host key verification from known hosts file example.
+* Added exceptions for all known host API errors.
+
 0.7.0
 ++++++
 

doc/api.rst

@@ -10,6 +10,7 @@ API Documentation
    sftp_handle
    pkey
    listener
+   knownhost
    exceptions
    statinfo
    fileinfo

doc/knownhost.rst

@@ -0,0 +1,7 @@
+ssh2.knownhost
+===============
+
+.. automodule:: ssh2.knownhost
+   :members:
+   :undoc-members:
+   :member-order: groupwise

examples/example_host_key_verification.py

@@ -0,0 +1,58 @@
+"""Connect to localhost, verifying host by reading from ~/.ssh/known_hosts"""
+
+from __future__ import print_function
+import os
+import socket
+
+from ssh2.session import Session
+from ssh2.session import LIBSSH2_HOSTKEY_HASH_SHA1, LIBSSH2_HOSTKEY_TYPE_RSA
+from ssh2.knownhost import LIBSSH2_KNOWNHOST_TYPE_PLAIN, \
+    LIBSSH2_KNOWNHOST_KEYENC_RAW, LIBSSH2_KNOWNHOST_KEY_SSHRSA
+
+# Connection settings
+host = 'localhost'
+user = os.getlogin()
+known_hosts = os.sep.join([os.path.expanduser('~'), '.ssh', 'known_hosts'])
+
+# Make socket, connect
+sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+sock.connect((host, 22))
+
+# Initialise
+session = Session()
+session.handshake(sock)
+
+host_key, key_type = session.hostkey()
+
+server_key_type = LIBSSH2_KNOWNHOST_KEY_SSHRSA \
+                  if key_type == LIBSSH2_HOSTKEY_TYPE_RSA \
+                     else LIBSSH2_KNOWNHOST_KEY_SSHDSS
+
+kh = session.knownhost_init()
+_read_hosts = kh.readfile(known_hosts)
+print("Read %s hosts from known hosts file at %s" % (_read_hosts, known_hosts))
+
+# Verification
+type_mask = LIBSSH2_KNOWNHOST_TYPE_PLAIN | \
+            LIBSSH2_KNOWNHOST_KEYENC_RAW | \
+            server_key_type
+kh.checkp(host, 22, host_key, type_mask)
+print("Host verification passed.")
+
+# Verification passed, continue with authentication
+session.agent_auth(user)
+
+channel = session.open_session()
+channel.execute('echo me')
+channel.wait_eof()
+channel.close()
+channel.wait_closed()
+
+# Get exit status
+print("Exit status: %s" % channel.get_exit_status())
+
+# Print output
+size, data = channel.read()
+while size > 0:
+    print(data)
+    size, data = channel.read()

ssh2/c_ssh2.pxd

@@ -36,6 +36,10 @@ cdef extern from "libssh2.h" nogil:
         LIBSSH2_CHANNEL_FLUSH_ALL
         LIBSSH2_HOSTKEY_HASH_MD5
         LIBSSH2_HOSTKEY_HASH_SHA1
+        LIBSSH2_HOSTKEY_TYPE_UNKNOWN
+        LIBSSH2_HOSTKEY_TYPE_RSA
+        LIBSSH2_HOSTKEY_TYPE_DSS
+
     # ctypedef libssh2_uint64_t libssh2_struct_stat_size
     ctypedef struct libssh2_struct_stat:
         dev_t   st_dev
@@ -336,8 +340,14 @@ cdef extern from "libssh2.h" nogil:
                               unsigned int *dest_len,
                               const char *src, unsigned int src_len)
     const char *libssh2_version(int req_version_num)
-    ctypedef struct libssh2_knownhost:
-        pass
+
+    # Known host API
+    struct libssh2_knownhost:
+        unsigned int magic
+        void *node
+        char *name
+        char *key
+        int typemask
     LIBSSH2_KNOWNHOSTS *libssh2_knownhost_init(LIBSSH2_SESSION *session)
     int libssh2_knownhost_add(LIBSSH2_KNOWNHOSTS *hosts,
                               const char *host,
@@ -377,6 +387,29 @@ cdef extern from "libssh2.h" nogil:
     int libssh2_knownhost_get(LIBSSH2_KNOWNHOSTS *hosts,
                               libssh2_knownhost **store,
                               libssh2_knownhost *prev)
+    enum:
+        LIBSSH2_KNOWNHOST_FILE_OPENSSH
+        LIBSSH2_KNOWNHOST_CHECK_MATCH
+        LIBSSH2_KNOWNHOST_CHECK_MISMATCH
+        LIBSSH2_KNOWNHOST_CHECK_NOTFOUND
+        LIBSSH2_KNOWNHOST_CHECK_FAILURE
+        LIBSSH2_KNOWNHOST_TYPE_MASK
+        LIBSSH2_KNOWNHOST_TYPE_PLAIN
+        LIBSSH2_KNOWNHOST_TYPE_SHA1
+        LIBSSH2_KNOWNHOST_TYPE_CUSTOM
+        LIBSSH2_KNOWNHOST_KEYENC_MASK
+        LIBSSH2_KNOWNHOST_KEYENC_RAW
+        LIBSSH2_KNOWNHOST_KEYENC_BASE64
+        LIBSSH2_KNOWNHOST_KEY_MASK
+        LIBSSH2_KNOWNHOST_KEY_SHIFT
+        LIBSSH2_KNOWNHOST_KEY_RSA1
+        LIBSSH2_KNOWNHOST_KEY_SSHRSA
+        LIBSSH2_KNOWNHOST_KEY_SSHDSS
+    IF EMBEDDED_LIB:
+        enum:
+            LIBSSH2_KNOWNHOST_KEY_UNKNOWN
+
+    # Public Key API
     struct libssh2_agent_publickey:
         unsigned int magic
         void *node