SSH Options

options settings for a new SSH session More...


Functions

int ssh_options_allow_ssh1 (SSH_OPTIONS *opt, int allow)
 Allow or deny the connection to SSH1 servers.
int ssh_options_allow_ssh2 (SSH_OPTIONS *opt, int allow)
 Allow or deny the connection to SSH2 servers.
SSH_OPTIONS * ssh_options_copy (SSH_OPTIONS *opt)
 Duplicate an option structure.
void ssh_options_free (SSH_OPTIONS *opt)
 Frees an option structure.
int ssh_options_getopt (SSH_OPTIONS *options, int *argcptr, char **argv)
 Parse command line arguments.
SSH_OPTIONS * ssh_options_new (void)
 This structure is freed automaticaly by ssh_disconnect() when you use it.
int ssh_options_set_auth_callback (SSH_OPTIONS *opt, ssh_auth_callback cb, void *userdata)
 Set the authentication callback.
int ssh_options_set_banner (SSH_OPTIONS *opt, const char *banner)
 Set the server banner sent to clients.
int ssh_options_set_bind (SSH_OPTIONS *opt, const char *bindaddr, int port)
 Set the local address and port binding.
int ssh_options_set_dsa_server_key (SSH_OPTIONS *opt, const char *dsakey)
 Set the path to the dsa ssh host key.
int ssh_options_set_fd (SSH_OPTIONS *opt, socket_t fd)
 Set a file descriptor for connection.
int ssh_options_set_host (SSH_OPTIONS *opt, const char *hostname)
 Set destination hostname.
int ssh_options_set_identity (SSH_OPTIONS *opt, const char *identity)
 Set the identity file name.
int ssh_options_set_known_hosts_file (SSH_OPTIONS *opt, const char *dir)
 Set the known hosts file name.
int ssh_options_set_log_function (SSH_OPTIONS *opt, void(*callback)(const char *message, SSH_SESSION *session, int priority))
 Change the writer callback for logging.
int ssh_options_set_log_verbosity (SSH_OPTIONS *opt, int verbosity)
 Set the session logging priority.
int ssh_options_set_port (SSH_OPTIONS *opt, unsigned int port)
 Set port to connect or to bind for a connection.
int ssh_options_set_rsa_server_key (SSH_OPTIONS *opt, const char *rsakey)
 Set the path to the ssh host rsa key.
int ssh_options_set_ssh_dir (SSH_OPTIONS *opt, const char *dir)
 Set the ssh directory.
int ssh_options_set_status_callback (SSH_OPTIONS *opt, void(*callback)(void *arg, float status), void *arg)
 Set a callback to show connection status in realtime.
int ssh_options_set_timeout (SSH_OPTIONS *opt, long seconds, long usec)
 Set a timeout for the connection.
int ssh_options_set_username (SSH_OPTIONS *opt, const char *username)
 Set the username for authentication.
int ssh_options_set_wanted_algos (SSH_OPTIONS *opt, int algo, const char *list)
 Set the algorithms to be used for cryptography and compression.


Detailed Description

options settings for a new SSH session

Function Documentation

int ssh_options_allow_ssh1 ( SSH_OPTIONS *  opt,
int  allow 
)

Allow or deny the connection to SSH1 servers.

Default value is 0 (no connection to SSH1 servers).

Parameters:
opt The options structure to use.
allow Non zero value allow ssh1.
Returns:
0 on success, < 0 on error.

Referenced by ssh_options_getopt().

int ssh_options_allow_ssh2 ( SSH_OPTIONS *  opt,
int  allow 
)

Allow or deny the connection to SSH2 servers.

Default value is 1 (allow connection to SSH2 servers).

Parameters:
opt The options structure to use.
allow Non zero values allow ssh2.
Returns:
0 on success, < 0 on error.

Referenced by ssh_options_getopt().

SSH_OPTIONS* ssh_options_copy ( SSH_OPTIONS *  opt  ) 

Duplicate an option structure.

If you make several sessions with the same options this is useful. You cannot use twice the same option structure in ssh_session_connect.

Parameters:
opt Option structure to copy.
Returns:
New copied option structure, NULL on error.
See also:
ssh_session_connect()

References ssh_options_free(), and ssh_options_new().

Referenced by ssh_bind_accept().

void ssh_options_free ( SSH_OPTIONS *  opt  ) 

Frees an option structure.

Parameters:
opt Option structure to free.

Referenced by ssh_bind_free(), and ssh_options_copy().

int ssh_options_getopt ( SSH_OPTIONS *  options,
int *  argcptr,
char **  argv 
)

Parse command line arguments.

This is a helper for your application to generate the appropriate options from the command line arguments.
The argv array and argc value are changed so that the parsed arguments wont appear anymore in them.
The single arguments (without switches) are not parsed. thus, myssh -l user localhost
The command wont set the hostname value of options to localhost.

Parameters:
options An empty option structure pointer.
argcptr The pointer to the argument count.
argv The arguments list pointer.
Returns:
0 on success, < 0 on error.
See also:
ssh_options_new()

References ssh_options_allow_ssh1(), ssh_options_allow_ssh2(), ssh_options_set_bind(), ssh_options_set_identity(), ssh_options_set_log_verbosity(), ssh_options_set_port(), ssh_options_set_username(), and ssh_options_set_wanted_algos().

SSH_OPTIONS* ssh_options_new ( void   ) 

This structure is freed automaticaly by ssh_disconnect() when you use it.


It can be used by only one ssh_connect(), not more.
also by default, ssh1 support is not allowed

initializes a new option structure

Returns:
an empty intialized option structure.
See also:
ssh_options_getopt()

Referenced by ssh_options_copy().

int ssh_options_set_auth_callback ( SSH_OPTIONS *  opt,
ssh_auth_callback  cb,
void *  userdata 
)

Set the authentication callback.

Parameters:
opt The options structure to use.
cb The callback function to use.
userdata A pointer to some user data you can pass to the callback.
Returns:
0 on success, < 0 on error.

int ssh_options_set_banner ( SSH_OPTIONS *  opt,
const char *  banner 
)

Set the server banner sent to clients.

Parameters:
opt The options structure to use.
banner A text banner to be shown.
Returns:
0 on success, < 0 on error.

int ssh_options_set_bind ( SSH_OPTIONS *  opt,
const char *  bindaddr,
int  port 
)

Set the local address and port binding.

In case your client has multiple IP adresses, select the local address and port to use for the socket.
If the address or port is not bindable, it may be impossible to connect.

Parameters:
opt The options structure to use.
bindaddr The bind address in form of hostname or ip address.
port The port number to bind.
Returns:
0 on success, < 0 on error.

Referenced by ssh_options_getopt().

int ssh_options_set_dsa_server_key ( SSH_OPTIONS *  opt,
const char *  dsakey 
)

Set the path to the dsa ssh host key.

Parameters:
opt The options structure to use.
dsakey The path to the dsa key to set.
Returns:
0 on success, < 0 on error.

int ssh_options_set_fd ( SSH_OPTIONS *  opt,
socket_t  fd 
)

Set a file descriptor for connection.

If you wish to open the socket yourself for a reason or another, set the file descriptor. Don't forget to use ssh_option_set_hostname() as the hostname is used as a key in the known_host mechanism.

Parameters:
opt The options structure to use.
fd An opened file descriptor to use.
Returns:
0 on success, < 0 on error.

int ssh_options_set_host ( SSH_OPTIONS *  opt,
const char *  hostname 
)

Set destination hostname.

Parameters:
opt The option structure to use.
hostname The host name to connect.
Returns:
0 on succes, < 0 on error.

int ssh_options_set_identity ( SSH_OPTIONS *  opt,
const char *  identity 
)

Set the identity file name.

The identity file is used authenticate with public key.

Parameters:
opt The options structure to use.
identity The path to the file including its name. "%s" will be substitued with the user home directory.
Returns:
0 on success, < 0 on error.
See also:
ssh_options_set_user_home_dir()

Referenced by ssh_options_getopt().

int ssh_options_set_known_hosts_file ( SSH_OPTIONS *  opt,
const char *  dir 
)

Set the known hosts file name.

The known hosts file is used to certify remote hosts are genuine.

Parameters:
opt The options structure to use.
dir The path to the file including its name. "%s" will be substitued with the user home directory.
Returns:
0 on success, < 0 on error.
See also:
ssh_options_set_user_home_dir()

int ssh_options_set_log_function ( SSH_OPTIONS *  opt,
void(*)(const char *message, SSH_SESSION *session, int priority)  callback 
)

Change the writer callback for logging.

Default is a write on stderr.

Parameters:
opt The options structure to use.
callback A callback function for the printing.
Returns:
0 on success, < 0 on error.
Warning:
The message string may contain format string characters.

int ssh_options_set_log_verbosity ( SSH_OPTIONS *  opt,
int  verbosity 
)

Set the session logging priority.

Parameters:
opt The options structure to use.
verbosity The verbosity of the messages. Every log smaller or equal to verbosity will be shown
SSH_LOG_NOLOG No logging
SSH_LOG_RARE Rare conditions or warnings
SSH_LOG_ENTRY Api-accessible entrypoints
SSH_LOG_PACKET Packet id and size
SSH_LOG_FUNCTIONS function entering and leaving
Returns:
0 on success, < 0 on error.

Referenced by ssh_options_getopt().

int ssh_options_set_port ( SSH_OPTIONS *  opt,
unsigned int  port 
)

Set port to connect or to bind for a connection.

Parameters:
opt The options structure to use.
port The port to connect or to bind.
Returns:
0 on success, < 0 on error.

Referenced by ssh_options_getopt().

int ssh_options_set_rsa_server_key ( SSH_OPTIONS *  opt,
const char *  rsakey 
)

Set the path to the ssh host rsa key.

Parameters:
opt The options structure to use.
rsakey The path to the rsa key to set.
Returns:
0 on success, < 0 on error.

int ssh_options_set_ssh_dir ( SSH_OPTIONS *  opt,
const char *  dir 
)

Set the ssh directory.

The ssh directory is used for files like known_hosts and identity (public and private keys)

Parameters:
opt The options structure to use.
dir The directory to set. It may include "%s" which will be replaced by the user home directory.
Returns:
0 on success, < 0 on error.
See also:
ssh_options_set_user_home_dir()

int ssh_options_set_status_callback ( SSH_OPTIONS *  opt,
void(*)(void *arg, float status)  callback,
void *  arg 
)

Set a callback to show connection status in realtime.

During ssh_connect(), libssh will call the callback with status from 0.0 to 1.0

Parameters:
opt The options structure to use.
callback A function pointer to a callback in form f(void *userarg, float status).
arg The value to be given as argument to the callback function when it is called.
Returns:
0 on success, < 0 on error.
See also:
ssh_connect()

int ssh_options_set_timeout ( SSH_OPTIONS *  opt,
long  seconds,
long  usec 
)

Set a timeout for the connection.

Parameters:
opt The options structure to use.
seconds Number of seconds.
usec Number of micro seconds.
Returns:
0 on success, < 0 on error.
Bug:
Currently it only timeouts the socket connection, not the complete exchange.

int ssh_options_set_username ( SSH_OPTIONS *  opt,
const char *  username 
)

Set the username for authentication.

Parameters:
opt The options structure to use.
username The username to authenticate.
Returns:
0 on success, -1 on error.
Bug:
this should not be set at options time

Referenced by ssh_options_getopt().

int ssh_options_set_wanted_algos ( SSH_OPTIONS *  opt,
int  algo,
const char *  list 
)

Set the algorithms to be used for cryptography and compression.

The methods are:
KEX_HOSTKEY (server public key type) : ssh-rsa or ssh-dss
KEX_CRYPT_C_S (symmetric cipher client to server)
KEX_CRYPT_S_C (symmetric cipher server to client)
KEX_COMP_C_S (Compression client to server): zlib or none
KEX_COMP_S_C (Compression server to client): zlib or none
You don't have to use this function if using the default ciphers is okay for you
in order to enable compression client to server, do

 ret = ssh_options_set_wanted_algos(opt,KEX_COMP_C_S,"zlib");

Parameters:
opt The options structure to use.
algo The method which needs to be changed.
list A list of algorithms to be used, in order of preference and separated by commas.
Returns:
0 on success, < 0 on error

Referenced by ssh_options_getopt().


doxygen