Merge pull request #9 from JuliaWeb/verify-hostname

Implement hostkey verification

Author: JamesWrigley

Project.toml

@@ -1,7 +1,7 @@
 name = "LibSSH"
 uuid = "00483490-30f8-4353-8aba-35b82f51f4d0"
 authors = ["James Wrigley <james@puiterwijk.org> and contributors"]
-version = "0.3.0"
+version = "0.4.0"
 
 [deps]
 CEnum = "fa961155-64e5-5f13-b03f-caf6b980ea82"

docs/src/changelog.md

@@ -7,6 +7,27 @@ CurrentModule = LibSSH
 This documents notable changes in LibSSH.jl. The format is based on [Keep a
 Changelog](https://keepachangelog.com).
 
+## [v0.4.0] - 2024-03-12
+
+### Added
+
+- A `throw` argument to [`poll_loop()`](@ref) ([#9]).
+- Support for some more options in [`Session`](@ref) ([#9]).
+- A new method for [`PKI.get_fingerprint_hash(::PKI.SshKey)`](@ref) to get a
+  public key fingerprint straight from a [`PKI.SshKey`](@ref) ([#9]).
+
+### Changed
+
+- Some automatically-wrapped low-level functions changed names back to retaining
+  their `ssh_` prefixes, and they now have a `throw` argument to allow disabling
+  throwing an exception upon error ([#9]).
+- [`authenticate()`](@ref) will now do host verification as well. This is
+  critical for security so it is *strongly recommend* that all dependencies
+  update to this release ([#9]).
+- All the `throw_on_*` arguments in the various `Session` and `SshChannel`
+  methods have been renamed `throw` for consistency with `Base` and the new
+  `throw` arguments in some auto-wrapped bindings ([#9]).
+
 ## [v0.3.0] - 2024-03-10
 
 ### Added

docs/src/examples.jl

@@ -28,7 +28,7 @@ session = ssh.Session("127.0.0.1", 2222)
 # the server*, which means checking its host key. The easiest way to do this is
 # by checking the server key against the users known hosts file:
 
-ssh.is_known_server(session; throw_on_failure=false)
+ssh.is_known_server(session; throw=false)
 
 # Ok, we got back a `KnownHosts_Unknown` response. That's because the demo
 # server automatically creates a dummy key to use, and that definitely won't be

gen/gen.jl

@@ -18,7 +18,8 @@ string_functions = [:ssh_message_auth_user, :ssh_message_auth_password,
                     :ssh_userauth_kbdint_getprompt]
 bool_functions = [:ssh_message_auth_kbdint_is_response]
 ssh_ok_functions = [:ssh_message_auth_reply_success, :ssh_message_auth_set_methods,
-                    :ssh_message_reply_default]
+                    :ssh_message_reply_default,
+                    :ssh_options_get, :ssh_options_set, :ssh_options_get_port]
 all_rewritable_functions = vcat(string_functions, bool_functions, ssh_ok_functions)
 
 """
@@ -92,48 +93,41 @@ function rewrite!(ctx)
             # Look for function expressions
             if @capture(expr, function name_(args__) body_ end)
                 wrapper = nothing
-                ret_type = nothing
 
                 # Check if we can rewrite the function
                 if name in string_functions
                     wrapper = quote
                         if ret == C_NULL
-                            throw(LibSSHException($("Error from $name, no string found (returned C_NULL)")))
-                        else
-                            return unsafe_string(Ptr{UInt8}(ret))
+                            if throw
+                                Base.throw(LibSSHException($("Error from $name, no string found (returned C_NULL)")))
+                            else
+                                return ret
+                            end
                         end
+
+                        return unsafe_string(Ptr{UInt8}(ret))
                     end
-                    ret_type = String
                 elseif name in bool_functions
-                    wrapper = :(return ret == 1)
-                    ret_type = Bool
+                    wrapper = :(return Bool(ret))
                 elseif name in ssh_ok_functions
                     wrapper = quote
-                        if ret != SSH_OK
+                        if ret != SSH_OK && throw
                             # This ugly concatenation is necessary because we
                             # have to interpolate the function name into the
                             # error string but also keep the return value
                             # interpolation from being escaped.
-                            throw(LibSSHException($("Error from $name, did not return SSH_OK: ") * "$(ret)"))
+                            Base.throw(LibSSHException($("Error from $name, did not return SSH_OK: ") * "$(ret)"))
                         end
+
+                        return ret
                     end
                 end
 
                 if !isnothing(wrapper)
-                    wrapper_name = Symbol(chopprefix(string(name), "ssh_"))
-                    new_expr = if isnothing(ret_type)
-                        quote
-                            function $wrapper_name($(args...))
-                                ret = $body
-                                $wrapper
-                            end
-                        end
-                    else
-                        quote
-                            function $wrapper_name($(args...))::$ret_type
-                                ret = $body
-                                $wrapper
-                            end
+                    new_expr = quote
+                        function $name($(args...); throw=true)
+                            ret = $body
+                            $wrapper
                         end
                     end
 

src/LibSSH.jl

@@ -9,7 +9,7 @@ using DocStringExtensions
 
 include("bindings.jl")
 using .lib
-import .lib: LibSSHException, ssh_options_get, ssh_options_set, SSH_OK, SSH_ERROR, SSH_AGAIN, SSH_EOF
+import .lib: LibSSHException, SSH_OK, SSH_ERROR, SSH_AGAIN, SSH_EOF
 
 
 """

src/bindings.jl

@@ -1386,30 +1386,42 @@ function ssh_options_parse_config(session, filename)
 end
 
 """
-    ssh_options_set(session, type, value)
+    ssh_options_set(session, type, value; throw = true)
 
-[Upstream documentation](https://api.libssh.org/stable/group__libssh__session.html#ga7a801b85800baa3f4e16f5b47db0a73d).
+Auto-generated wrapper around [`ssh_options_set`](https://api.libssh.org/stable/group__libssh__session.html#ga7a801b85800baa3f4e16f5b47db0a73d).
 """
-function ssh_options_set(session, type, value)
-    @ccall libssh.ssh_options_set(session::ssh_session, type::ssh_options_e, value::Ptr{Cvoid})::Cint
+function ssh_options_set(session, type, value; throw = true)
+    ret = @ccall(libssh.ssh_options_set(session::ssh_session, type::ssh_options_e, value::Ptr{Cvoid})::Cint)
+    if ret != SSH_OK && throw
+        Base.throw(LibSSHException("Error from ssh_options_set, did not return SSH_OK: " * "$(ret)"))
+    end
+    return ret
 end
 
 """
-    ssh_options_get(session, type, value)
+    ssh_options_get(session, type, value; throw = true)
 
-[Upstream documentation](https://api.libssh.org/stable/group__libssh__session.html#gaaa9d400920cad4d6e4a0fb09ff8c7b01).
+Auto-generated wrapper around [`ssh_options_get`](https://api.libssh.org/stable/group__libssh__session.html#gaaa9d400920cad4d6e4a0fb09ff8c7b01).
 """
-function ssh_options_get(session, type, value)
-    @ccall libssh.ssh_options_get(session::ssh_session, type::ssh_options_e, value::Ptr{Ptr{Cchar}})::Cint
+function ssh_options_get(session, type, value; throw = true)
+    ret = @ccall(libssh.ssh_options_get(session::ssh_session, type::ssh_options_e, value::Ptr{Ptr{Cchar}})::Cint)
+    if ret != SSH_OK && throw
+        Base.throw(LibSSHException("Error from ssh_options_get, did not return SSH_OK: " * "$(ret)"))
+    end
+    return ret
 end
 
 """
-    ssh_options_get_port(session, port_target)
+    ssh_options_get_port(session, port_target; throw = true)
 
-[Upstream documentation](https://api.libssh.org/stable/group__libssh__session.html#gaa298d8445355420d80f2d968477ba86f).
+Auto-generated wrapper around [`ssh_options_get_port`](https://api.libssh.org/stable/group__libssh__session.html#gaa298d8445355420d80f2d968477ba86f).
 """
-function ssh_options_get_port(session, port_target)
-    @ccall libssh.ssh_options_get_port(session::ssh_session, port_target::Ptr{Cuint})::Cint
+function ssh_options_get_port(session, port_target; throw = true)
+    ret = @ccall(libssh.ssh_options_get_port(session::ssh_session, port_target::Ptr{Cuint})::Cint)
+    if ret != SSH_OK && throw
+        Base.throw(LibSSHException("Error from ssh_options_get_port, did not return SSH_OK: " * "$(ret)"))
+    end
+    return ret
 end
 
 function ssh_pcap_file_close(pcap)
@@ -1862,17 +1874,20 @@ function ssh_userauth_kbdint_getinstruction(session)
 end
 
 """
-    userauth_kbdint_getname(session)::String
+    ssh_userauth_kbdint_getname(session; throw = true)
 
 Auto-generated wrapper around [`ssh_userauth_kbdint_getname`](https://api.libssh.org/stable/group__libssh__auth.html#ga5d6f5eb0ed09fe2c7a2ac69b972e130e).
 """
-function userauth_kbdint_getname(session)::String
+function ssh_userauth_kbdint_getname(session; throw = true)
     ret = @ccall(libssh.ssh_userauth_kbdint_getname(session::ssh_session)::Ptr{Cchar})
     if ret == C_NULL
-        throw(LibSSHException("Error from ssh_userauth_kbdint_getname, no string found (returned C_NULL)"))
-    else
-        return unsafe_string(Ptr{UInt8}(ret))
+        if throw
+            Base.throw(LibSSHException("Error from ssh_userauth_kbdint_getname, no string found (returned C_NULL)"))
+        else
+            return ret
+        end
     end
+    return unsafe_string(Ptr{UInt8}(ret))
 end
 
 """
@@ -1885,17 +1900,20 @@ function ssh_userauth_kbdint_getnprompts(session)
 end
 
 """
-    userauth_kbdint_getprompt(session, i, echo)::String
+    ssh_userauth_kbdint_getprompt(session, i, echo; throw = true)
 
 Auto-generated wrapper around [`ssh_userauth_kbdint_getprompt`](https://api.libssh.org/stable/group__libssh__auth.html#ga15c0f954f79d73e1ac5981ac483efb75).
 """
-function userauth_kbdint_getprompt(session, i, echo)::String
+function ssh_userauth_kbdint_getprompt(session, i, echo; throw = true)
     ret = @ccall(libssh.ssh_userauth_kbdint_getprompt(session::ssh_session, i::Cuint, echo::Ptr{Cchar})::Ptr{Cchar})
     if ret == C_NULL
-        throw(LibSSHException("Error from ssh_userauth_kbdint_getprompt, no string found (returned C_NULL)"))
-    else
-        return unsafe_string(Ptr{UInt8}(ret))
+        if throw
+            Base.throw(LibSSHException("Error from ssh_userauth_kbdint_getprompt, no string found (returned C_NULL)"))
+        else
+            return ret
+        end
     end
+    return unsafe_string(Ptr{UInt8}(ret))
 end
 
 """
@@ -1908,17 +1926,20 @@ function ssh_userauth_kbdint_getnanswers(session)
 end
 
 """
-    userauth_kbdint_getanswer(session, i)::String
+    ssh_userauth_kbdint_getanswer(session, i; throw = true)
 
 Auto-generated wrapper around [`ssh_userauth_kbdint_getanswer`](https://api.libssh.org/stable/group__libssh__auth.html#ga4f55ed8bc6f553423ab1c92598d0194b).
 """
-function userauth_kbdint_getanswer(session, i)::String
+function ssh_userauth_kbdint_getanswer(session, i; throw = true)
     ret = @ccall(libssh.ssh_userauth_kbdint_getanswer(session::ssh_session, i::Cuint)::Ptr{Cchar})
     if ret == C_NULL
-        throw(LibSSHException("Error from ssh_userauth_kbdint_getanswer, no string found (returned C_NULL)"))
-    else
-        return unsafe_string(Ptr{UInt8}(ret))
+        if throw
+            Base.throw(LibSSHException("Error from ssh_userauth_kbdint_getanswer, no string found (returned C_NULL)"))
+        else
+            return ret
+        end
     end
+    return unsafe_string(Ptr{UInt8}(ret))
 end
 
 """
@@ -3847,7 +3868,7 @@ function ssh_send_issue_banner(session, banner)
 end
 
 """
-    message_reply_default(msg)
+    ssh_message_reply_default(msg; throw = true)
 
 Auto-generated wrapper around `ssh_message_reply_default`. Original upstream documentation is below.
 
@@ -3864,15 +3885,16 @@ Use this function if you don't know what to respond or if you want to reject a r
 # See also
 [`ssh_message_get`](@ref)()
 """
-function message_reply_default(msg)
+function ssh_message_reply_default(msg; throw = true)
     ret = @ccall(libssh.ssh_message_reply_default(msg::ssh_message)::Cint)
-    if ret != SSH_OK
-        throw(LibSSHException("Error from ssh_message_reply_default, did not return SSH_OK: " * "$(ret)"))
+    if ret != SSH_OK && throw
+        Base.throw(LibSSHException("Error from ssh_message_reply_default, did not return SSH_OK: " * "$(ret)"))
     end
+    return ret
 end
 
 """
-    message_auth_user(msg)::String
+    ssh_message_auth_user(msg; throw = true)
 
 Auto-generated wrapper around `ssh_message_auth_user`. Original upstream documentation is below.
 
@@ -3887,17 +3909,20 @@ The username or NULL if an error occurred.
 # See also
 [`ssh_message_get`](@ref)(), [`ssh_message_type`](@ref)()
 """
-function message_auth_user(msg)::String
+function ssh_message_auth_user(msg; throw = true)
     ret = @ccall(libssh.ssh_message_auth_user(msg::ssh_message)::Ptr{Cchar})
     if ret == C_NULL
-        throw(LibSSHException("Error from ssh_message_auth_user, no string found (returned C_NULL)"))
-    else
-        return unsafe_string(Ptr{UInt8}(ret))
+        if throw
+            Base.throw(LibSSHException("Error from ssh_message_auth_user, no string found (returned C_NULL)"))
+        else
+            return ret
+        end
     end
+    return unsafe_string(Ptr{UInt8}(ret))
 end
 
 """
-    message_auth_password(msg)::String
+    ssh_message_auth_password(msg; throw = true)
 
 Auto-generated wrapper around `ssh_message_auth_password`. Original upstream documentation is below.
 
@@ -3916,13 +3941,16 @@ The username or NULL if an error occurred.
 # See also
 [`ssh_message_get`](@ref)(), [`ssh_message_type`](@ref)()
 """
-function message_auth_password(msg)::String
+function ssh_message_auth_password(msg; throw = true)
     ret = @ccall(libssh.ssh_message_auth_password(msg::ssh_message)::Ptr{Cchar})
     if ret == C_NULL
-        throw(LibSSHException("Error from ssh_message_auth_password, no string found (returned C_NULL)"))
-    else
-        return unsafe_string(Ptr{UInt8}(ret))
+        if throw
+            Base.throw(LibSSHException("Error from ssh_message_auth_password, no string found (returned C_NULL)"))
+        else
+            return ret
+        end
     end
+    return unsafe_string(Ptr{UInt8}(ret))
 end
 
 """
@@ -3948,13 +3976,13 @@ function ssh_message_auth_pubkey(msg)
 end
 
 """
-    message_auth_kbdint_is_response(msg)::Bool
+    ssh_message_auth_kbdint_is_response(msg; throw = true)
 
 Auto-generated wrapper around [`ssh_message_auth_kbdint_is_response`](https://api.libssh.org/stable/group__libssh__server.html#ga5132c82c49de985e9e10f51f393e52a4).
 """
-function message_auth_kbdint_is_response(msg)::Bool
+function ssh_message_auth_kbdint_is_response(msg; throw = true)
     ret = @ccall(libssh.ssh_message_auth_kbdint_is_response(msg::ssh_message)::Cint)
-    return ret == 1
+    return Bool(ret)
 end
 
 """
@@ -3972,15 +4000,16 @@ function ssh_message_auth_publickey_state(msg)
 end
 
 """
-    message_auth_reply_success(msg, partial)
+    ssh_message_auth_reply_success(msg, partial; throw = true)
 
 Auto-generated wrapper around `ssh_message_auth_reply_success`.
 """
-function message_auth_reply_success(msg, partial)
+function ssh_message_auth_reply_success(msg, partial; throw = true)
     ret = @ccall(libssh.ssh_message_auth_reply_success(msg::ssh_message, partial::Cint)::Cint)
-    if ret != SSH_OK
-        throw(LibSSHException("Error from ssh_message_auth_reply_success, did not return SSH_OK: " * "$(ret)"))
+    if ret != SSH_OK && throw
+        Base.throw(LibSSHException("Error from ssh_message_auth_reply_success, did not return SSH_OK: " * "$(ret)"))
     end
+    return ret
 end
 
 """
@@ -4002,15 +4031,16 @@ function ssh_message_auth_reply_pk_ok_simple(msg)
 end
 
 """
-    message_auth_set_methods(msg, methods)
+    ssh_message_auth_set_methods(msg, methods; throw = true)
 
 Auto-generated wrapper around [`ssh_message_auth_set_methods`](https://api.libssh.org/stable/group__libssh__server.html#gab993157d98e5b4b3399d216c9243effc).
 """
-function message_auth_set_methods(msg, methods)
+function ssh_message_auth_set_methods(msg, methods; throw = true)
     ret = @ccall(libssh.ssh_message_auth_set_methods(msg::ssh_message, methods::Cint)::Cint)
-    if ret != SSH_OK
-        throw(LibSSHException("Error from ssh_message_auth_set_methods, did not return SSH_OK: " * "$(ret)"))
+    if ret != SSH_OK && throw
+        Base.throw(LibSSHException("Error from ssh_message_auth_set_methods, did not return SSH_OK: " * "$(ret)"))
     end
+    return ret
 end
 
 """