OpenVAS Libraries  9.0.1
Data Structures | Macros | Functions
nasl_ssh.c File Reference

Implementation of an API for SSH functions. More...

#include <arpa/inet.h>
#include <netinet/in.h>
#include <sys/select.h>
#include <sys/socket.h>
#include <sys/time.h>
#include <sys/types.h>
#include <stdlib.h>
#include <fcntl.h>
#include <errno.h>
#include <stdio.h>
#include <string.h>
#include <ctype.h>
#include <unistd.h>
#include <glib.h>
#include <glib/gstdio.h>
#include "nasl_tree.h"
#include "nasl_global_ctxt.h"
#include "nasl_func.h"
#include "nasl_var.h"
#include "nasl_lex_ctxt.h"
#include "exec.h"
#include "../misc/plugutils.h"
#include "../base/kb.h"
#include "nasl_debug.h"
#include "../misc/network.h"
#include "../misc/openvas_logging.h"
#include "../misc/prefs.h"
#include "../misc/openvas_ssh.h"
#include "nasl_ssh.h"

Data Structures

struct  session_table_item_s
 

Macros

#define DIM(v)   (sizeof(v)/sizeof((v)[0]))
 
#define DIMof(type, member)   DIM(((type *)0)->member)
 
#define MAX_SSH_SESSIONS   10
 

Functions

tree_cellnasl_ssh_connect (lex_ctxt *lexic)
 Connect to the target host via TCP and setup an ssh connection. More...
 
tree_cellnasl_ssh_disconnect (lex_ctxt *lexic)
 Disconnect an ssh connection. More...
 
tree_cellnasl_ssh_session_id_from_sock (lex_ctxt *lexic)
 Given a socket, return the corresponding session id. More...
 
tree_cellnasl_ssh_get_sock (lex_ctxt *lexic)
 Given a session id, return the corresponding socket. More...
 
tree_cellnasl_ssh_set_login (lex_ctxt *lexic)
 Set the login name for the authentication. More...
 
tree_cellnasl_ssh_userauth (lex_ctxt *lexic)
 Authenticate a user on an ssh connection. More...
 
tree_cellnasl_ssh_request_exec (lex_ctxt *lexic)
 Run a command via ssh. More...
 
tree_cellnasl_ssh_get_issue_banner (lex_ctxt *lexic)
 Get the issue banner. More...
 
tree_cellnasl_ssh_get_server_banner (lex_ctxt *lexic)
 Get the server banner. More...
 
tree_cellnasl_ssh_get_host_key (lex_ctxt *lexic)
 Get the host key. More...
 
tree_cellnasl_ssh_get_auth_methods (lex_ctxt *lexic)
 Get the list of authmethods. More...
 
tree_cellnasl_ssh_shell_open (lex_ctxt *lexic)
 Request an ssh shell. More...
 
tree_cellnasl_ssh_shell_read (lex_ctxt *lexic)
 Read the output of an ssh shell. More...
 
tree_cellnasl_ssh_shell_write (lex_ctxt *lexic)
 Write string to ssh shell. More...
 
tree_cellnasl_ssh_shell_close (lex_ctxt *lexic)
 Close an ssh shell. More...
 

Detailed Description

Implementation of an API for SSH functions.

This file contains the implementaion of the Secure Shell related NASL builtin functions. They are only available if build with libssh support.

Macro Definition Documentation

◆ DIM

#define DIM (   v)    (sizeof(v)/sizeof((v)[0]))

◆ DIMof

#define DIMof (   type,
  member 
)    DIM(((type *)0)->member)

◆ MAX_SSH_SESSIONS

#define MAX_SSH_SESSIONS   10

Function Documentation

◆ nasl_ssh_connect()

tree_cell* nasl_ssh_connect ( lex_ctxt lexic)

Connect to the target host via TCP and setup an ssh connection.

NASL Function: ssh_connect

If the named argument "socket" is given, that socket will be used instead of a creating a new TCP connection. If socket is not given or 0, the port is looked up in the preferences and the KB unless overriden by the named parameter "port".

On success an ssh session to the host has been established; the caller may then run an authentication function. If the connection is no longer needed, ssh_disconnect may be used to disconnect and close the socket.

NASL Named Parameters:
  • socket If given, this socket will be used instead of creating a new connection.
  • port A non-standard port to connect to. This is only used if socket is not given or 0.
NASL Returns:
An integer to identify the ssh session. Zero on error.
Parameters
[in]lexicLexical context of NASL interpreter.
Returns
On success the function returns a tree-cell with a non-zero integer identifying that ssh session; zero is returned on a connection error. In case of an internal error NULL is returned.

◆ nasl_ssh_disconnect()

tree_cell* nasl_ssh_disconnect ( lex_ctxt lexic)

Disconnect an ssh connection.

NASL Function: ssh_disconnect

This function takes the ssh session id (as returned by ssh_connect) as its only unnamed argument. Passing 0 as session id is explicitly allowed and does nothing. If there are any open channels they are closed as well and their ids will be marked as invalid.

NASL Unnamed Parameters:
  • An ssh session id. A value of 0 is allowed and acts as a NOP.
NASL Returns:
Nothing
Parameters
[in]lexicLexical context of NASL interpreter.
Returns
Nothing.

◆ nasl_ssh_get_auth_methods()

tree_cell* nasl_ssh_get_auth_methods ( lex_ctxt lexic)

Get the list of authmethods.

NASL Function: ssh_get_auth_methods

The function returns a string with comma separated authentication methods. This is basically the same as returned by SSH_MSG_USERAUTH_FAILURE protocol element; however, it has been screened and put into a definitive order.

NASL Unnamed Parameters:
  • An ssh session id.
NASL Returns:
A string on success or NULL on error.
Parameters
[in]lexicLexical context of NASL interpreter.
Returns
A string is returned on success. NULL indicates that the connection has not yet been established.

◆ nasl_ssh_get_host_key()

tree_cell* nasl_ssh_get_host_key ( lex_ctxt lexic)

Get the host key.

NASL Function: ssh_get_host_key

The function returns a string with the MD5 host key. *

NASL Unnamed Parameters:
  • An ssh session id.
NASL Returns:
A data block on success or NULL on error.
Parameters
[in]lexicLexical context of NASL interpreter.
Returns
A string is returned on success. NULL indicates that the connection has not yet been established.

◆ nasl_ssh_get_issue_banner()

tree_cell* nasl_ssh_get_issue_banner ( lex_ctxt lexic)

Get the issue banner.

NASL Function: ssh_get_issue_banner

The function returns a string with the issue banner. This is usually displayed before authentication.

NASL Unnamed Parameters:
  • An ssh session id.
NASL Returns:
A data block on success or NULL on error.
Parameters
[in]lexicLexical context of NASL interpreter.
Returns
A string is returned on success. NULL indicates that the server did not send a banner or that the connection has not yet been established.

◆ nasl_ssh_get_server_banner()

tree_cell* nasl_ssh_get_server_banner ( lex_ctxt lexic)

Get the server banner.

NASL Function: ssh_get_server_banner

The function returns a string with the server banner. This is usually the first data sent by the server.

NASL Unnamed Parameters:
  • An ssh session id.
NASL Returns:
A data block on success or NULL on error.
Parameters
[in]lexicLexical context of NASL interpreter.
Returns
A string is returned on success. NULL indicates that the connection has not yet been established.

◆ nasl_ssh_get_sock()

tree_cell* nasl_ssh_get_sock ( lex_ctxt lexic)

Given a session id, return the corresponding socket.

NASL Function: ssh_get_sock

The socket is either a native file descriptor or a NASL connection socket (if a open socket was passed to ssh_connect). The NASL network code handles both of them.

NASL Unnamed Parameters:
  • An ssh session id.
NASL Returns:
An integer representing the socket or -1 on error.
Parameters
[in]lexicLexical context of NASL interpreter.
Returns
The socket or -1 on error.

◆ nasl_ssh_request_exec()

tree_cell* nasl_ssh_request_exec ( lex_ctxt lexic)

Run a command via ssh.

NASL Function: ssh_request_exec

The function opens a channel to the remote end and ask it to execute a command. The output of the command is then returned as a data block. The first unnamed argument is the session id. The command itself is expected as string in the named argument "cmd".

Regarding the handling of the stderr and stdout stream, this function may be used in different modes.

If either the named arguments stdout or stderr are given and that one is set to 1, only the output of the specified stream is returned.

If stdout and stderr are both given and set to 1, the output of both is returned interleaved. NOTE: The following feature has not yet been implemented: The output is guaranteed not to switch between stderr and stdout within a line.

If stdout and stderr are both given but set to 0, a special backward compatibility mode is used: First all output to stderr is collected up until any output to stdout is received. Then all output to stdout is returned while ignoring all further stderr output; at EOF the initial collected data from stderr is returned.

If the named parameters stdout and stderr are not given, the function acts exactly as if only stdout has been set to 1.

NASL Unnamed Parameters:
  • An ssh session id.
NASL Named Parameters:
  • cmd A string with the command to execute.
  • stdout An integer with value 0 or 1; see above for a full description.
  • stderr An integer with value 0 or 1; see above for a full description.
NASL Returns:
A data block on success or NULL on error.
Parameters
[in]lexicLexical context of NASL interpreter.
Returns
A data/string is returned on success. NULL indicates an error.

◆ nasl_ssh_session_id_from_sock()

tree_cell* nasl_ssh_session_id_from_sock ( lex_ctxt lexic)

Given a socket, return the corresponding session id.

NASL Function: ssh_session_id_from_sock
NASL Unnamed Parameters:
  • A NASL socket value
NASL Returns:
An integer with the corresponding ssh session id or 0 if no session id is known for the given socket.
Parameters
[in]lexicLexical context of NASL interpreter.
Returns
The session id on success or 0 if not found.

◆ nasl_ssh_set_login()

tree_cell* nasl_ssh_set_login ( lex_ctxt lexic)

Set the login name for the authentication.

NASL Function: ssh_set_login

This is an optional function and usuallay not required. However, if you want to get the banner before starting the authentication, you need to tell libssh the user because it is often not possible to chnage the user after the first call to an authentication methods - getting the banner usees an authntication function.

The named argument "login" is used for the login name; it defaults the KB entry "Secret/SSH/login". It should contain the user name to login. Given that many servers don't allow changing the login for an established connection, the "login" parameter is silently ignored on all further calls.

NASL Unnamed Parameters:
  • An ssh session id.
NASL Named Parameters:
  • login A string with the login name (optional).
NASL Returns:
None
Parameters
[in]lexicLexical context of NASL interpreter.
Returns
none.

◆ nasl_ssh_shell_close()

tree_cell* nasl_ssh_shell_close ( lex_ctxt lexic)

Close an ssh shell.

NASL Function: ssh_shell_close
NASL Unnamed Parameters:
  • An ssh session id.
Parameters
[in]lexicLexical context of NASL interpreter.

◆ nasl_ssh_shell_open()

tree_cell* nasl_ssh_shell_open ( lex_ctxt lexic)

Request an ssh shell.

NASL Function: ssh_shell_open
NASL Unnamed Parameters:
  • An ssh session id.
NASL Returns:
An int on success or NULL on error.
Parameters
[in]lexicLexical context of NASL interpreter.
Returns
Session ID on success, NULL on failure.

◆ nasl_ssh_shell_read()

tree_cell* nasl_ssh_shell_read ( lex_ctxt lexic)

Read the output of an ssh shell.

NASL Function: ssh_shell_read
NASL Unnamed Parameters:
  • An ssh session id.
NASL Returns:
A string on success or NULL on error.
Parameters
[in]lexicLexical context of NASL interpreter.
Returns
Data read from shell on success, NULL on failure.

◆ nasl_ssh_shell_write()

tree_cell* nasl_ssh_shell_write ( lex_ctxt lexic)

Write string to ssh shell.

NASL Function: ssh_shell_write
NASL Unnamed Parameters:
  • An ssh session id.
  • A string to write to shell.
NASL Returns:
An integer: 0 on success, -1 on failure.
Parameters
[in]lexicLexical context of NASL interpreter.
Returns
0 on success, -1 on failure.

◆ nasl_ssh_userauth()

tree_cell* nasl_ssh_userauth ( lex_ctxt lexic)

Authenticate a user on an ssh connection.

NASL Function: ssh_userauth

The function expects the session id as its first unnamed argument. The first time this function is called for a session id, the named argument "login" is also expected; it defaults the KB entry "Secret/SSH/login". It should contain the user name to login. Given that many servers don't allow changing the login for an established connection, the "login" parameter is silently ignored on all further calls.

To perform a password based authentication, the named argument "password" must contain a password.

To perform a public key based authentication, the named argument "privatekey" must contain a base64 encoded private key in ssh native or in PKCS#8 format.

If both, "password" and "privatekey" are given as named arguments only "password" is used. If neither are given the values are taken from the KB ("Secret/SSH/password" and "Secret/SSH/privatekey") and tried in the order {password, privatekey}. Note well, that if one of the named arguments are given, only those are used and the KB is not consulted.

If the private key is protected, its passphrase is taken from the named argument "passphrase" or, if not given, taken from the KB ("Secret/SSH/passphrase").

Note that the named argument "publickey" and the KB item ("Secret/SSH/publickey") are ignored - they are not longer required because they can be derived from the private key.

NASL Unnamed Parameters:
  • An ssh session id.
NASL Named Parameters:
  • login A string with the login name.
  • password A string with the password.
  • privatekey A base64 encoded private key in ssh native or in pkcs#8 format. This parameter is ignored if password is given.
  • passphrase A string with the passphrase used to unprotect privatekey.
NASL Returns:
An integer as status value; 0 indicates success.
Parameters
[in]lexicLexical context of NASL interpreter.
Returns
0 is returned on success. Any other value indicates an error.