---
-- Provides a binding for the libssh2 library.
--
-- SSH2 is a complex protocol and libssh2 simplifies many tasks involved in
-- interacting with ssh servers. This module provides bindings for some of the
-- most commonly used libssh2 functions. You may wish to use the functionality
-- in libssh2-utility instead, which wraps many of the functions here in an easier
-- to use class, SSHConnection.
--
-- For performance reasons, the modules reuses the NSE's existing nsock socket
-- pool.
--
-- @author Devin Bjelland
-- @author Sergey Khegay
-- @copyright Same as Nmap--See https://nmap.org/book/man-legal.html

module "libssh2"

--- Creates libssh2 session and performs handshake
-- @param host Host to connect to.
-- @param port Port to connect to.
-- @return session or nil on failure
function session_open(host, port)

--- Returns SHA1 or MD5 hostkey hash of session
-- @param session Connected libssh2 session.
-- @param hashtype (optional) "sha1" or "md5" (sha1 is default)
-- @return hostkey hash of server
function hostkey_hash(session, hashtype)

--- Sets timeout of libssh2 session
-- @param session Connected libssh2 session.
-- @param timeout Timeout for session in milliseconds.
function set_timeout(session, timeout)

--- Returns list of authentication methods supported by the server
-- @param session Connected libssh2 session.
-- @return List of supported authentication methods/
function userauth_list(session)

--- Attempts to authenticate libssh2 session using provided credentials
-- @param username Username to authenticate as.
-- @param password Password to authenticate with.
-- @return true/false, depending on success
function userauth_password(session, username, password)

--- Attempts to authenticate libssh2 session using keyboard-interactive auth
-- @param username Username to authenticate as.
-- @param callback See <code>userauth_keyboard_interactive_cb</code>
-- @return true/false, depending on success
-- @return if first return was false, any errors thrown by the callback
function userauth_keyboard_interactive(session, username, callback)

--- Callback function for keyboard interaction.
--
-- This function is not implemented; it is up to you to write the appropriate
-- function. The function must not yield, and so must not use any socket
-- functions.
-- @param username string Username this authentication is for
-- @param name string from the server
-- @param instruction string from the server
-- @param prompts A table of strings, each of which is a prompt from the server.
-- @return a series of response strings, each corresponding to a prompt
function userauth_keyboard_interactive_cb(username, name, instruction, prompts)

--- Attempts to authenticate libssh2 session using provided publickey
-- @param session Connected libssh2 session
-- @param username Username to authenticate as
-- @param privatekeyfile File containing privatekey
-- @param passphrase Passphrase for privatekey
-- @param publickeyfile File containing publickey. Not necessary if libssh2 is
-- compiled against OpenSSL
-- @return true/false, depending on success
function userauth_publickey(session, username, privatekeyfile, passphrase, publickeyfile)

--- Read publickey from id_*.pub type key file
-- @param publickeyfile File containing publickey
-- @return string containing raw key data
function read_publickey(publickeyfile)

--- Checks to see if ssh server accepts public key for authentication as given user.
--  This doesn't require the private key as it doesn't finish authenticating.
-- @param session Connected libssh2 session
-- @param username Username to authenticate as
-- @param publickeydata String containing raw publickey blob
-- @return true/false, depending on whether user can authenticate with given key
function publickey_canauth(session, username, publickeydata)

--- Opens channel on authenticated ssh2 session and optionally sets it to pseudo
-- terminal mode.
-- @param session Authenticated libssh2 session
-- @param no_pty If true, skip requesting a PTY.
-- @return libssh2 channel
function open_channel(session, no_pty)

--- Reads data from stdout on libssh2 channel.
-- @param session Authenticated libssh2 session
-- @param channel Open libssh2 channel
-- @return string containing data read from channel
function channel_read(session, channel)

--- Reads data from stderr on libssh2 channel.
-- @param session Authenticated libssh2 session
-- @param channel Open libssh2 channel
-- @return string containing data read from channel
function channel_read_stderr(session, channel)

--- Writes data to libssh2 channel. Not guaranteed to write entire buffer.
-- @param session Authenticated libssh2 session
-- @param channel Open libssh2 channel
-- @param buffer String containing data to be written
-- @return Number of bytes written to channel
function channel_write(session, channel, buffer)

--- Sends a request on libssh2 channel.
--
-- Examples:
-- * request a shell: <code>channel_request(s, c, "shell")</code> (equivalent to <code>channel_shell(s, c)</code).
-- * execute a command: <code>channel_request(s, c, "exec", cmd)</code> (equivalent to <code>channel_exec(s, c, cmd)</code>).
-- * open a subsystem: <code>channel_request(s, c, "subsystem", "sftp")</code>
-- @param session Authenticated libssh2 session
-- @param channel Open libssh2 channel
-- @param request String identifier for the request, e.g. "shell", "exec", "subsystem"
-- @param message Optional string payload for the request.
function channel_request(session, channel, request, message)

--- Request a PTY on a channel
--
-- @param session Authenticated libssh2 session
-- @param channel Open libssh2 channel
-- @param term string Terminal emulation
-- @param modes optional string Terminal mode modifiers
-- @param width integer Width of pty in characters
-- @param height integer Height of pty in characters
-- @param width_ex integer Width of pty in pixels
-- @param height_px integer Height of pty in pixels
function channel_request_pty_ex(session, channel, term, modes,
    width, height, width_px, height_px)

--- Executes command on libssh2 channel
-- @param session Authenticated libssh2 session
-- @param channel Open libssh2 channel
-- @param cmd String containing command to execute
function channel_exec(session, channel, cmd)

--- Requests a shell on libssh2 channel
-- @param session Authenticated libssh2 session
-- @param channel Open libssh2 channel
function channel_shell(session, channel)

--- Sends EOF on libssh2 channel. Note that the server may continue to send data
-- until it sends its own EOF (which can be checked with channel_eof()
-- @param session Authenticated libssh2 session
-- @param channel Open libssh2 channel
function channel_send_eof(session, channel)

--- Checks if server has sent EOF on libssh2 channel
-- @param channel Open libssh2 channel
-- @return true/false depending on whether server has send EOF
function channel_eof(channel)

--- Gracefully closes open libssh2 channel
-- @param session Authenticated libssh2 session
-- @param channel Open libssh2 channel
function channel_close(session, channel)

--- Gracefully closes connected libssh2 session
-- @param session Connected libssh2 session
function session_close(session)