libssh  0.10.90
The SSH library
Loading...
Searching...
No Matches
Functions
The SSH session functions
The libssh API
Collaboration diagram for The SSH session functions:

Functions

int ssh_connect (ssh_session session)
 Connect to the ssh server.
 
char * ssh_get_issue_banner (ssh_session session)
 Get the issue banner from the server.
 
int ssh_get_openssh_version (ssh_session session)
 Get the version of the OpenSSH server, if it is not an OpenSSH server then 0 will be returned.
 
int ssh_request_no_more_sessions (ssh_session session)
 Most SSH connections will only ever request a single session, but an attacker may abuse a running ssh client to surreptitiously open additional sessions under their control. OpenSSH provides a global request "no-more-sessions@openssh.com" to mitigate this attack.
 
int ssh_session_set_disconnect_message (ssh_session session, const char *message)
 Add disconnect message when ssh_session is disconnected To add a disconnect message to give peer a better hint.
 
void ssh_disconnect (ssh_session session)
 Disconnect from a session (client or server).
 
const char * ssh_copyright (void)
 Copyright information.
 
int ssh_select (ssh_channel *channels, ssh_channel *outchannels, socket_t maxfd, fd_set *readfds, struct timeval *timeout)
 A wrapper for the select syscall.
 
bool ssh_dh_is_known_group (bignum modulus, bignum generator)
 
ssh_key ssh_dh_get_current_server_publickey (ssh_session session)
 
int ssh_dh_get_current_server_publickey_blob (ssh_session session, ssh_string *pubkey_blob)
 
ssh_key ssh_dh_get_next_server_publickey (ssh_session session)
 
int ssh_dh_get_next_server_publickey_blob (ssh_session session, ssh_string *pubkey_blob)
 
char * ssh_get_fingerprint_hash (enum ssh_publickey_hash_type type, unsigned char *hash, size_t len)
 Get a hash as a human-readable hex- or base64-string.
 
void ssh_print_hash (enum ssh_publickey_hash_type type, unsigned char *hash, size_t len)
 Print a hash as a human-readable hex- or base64-string.
 
int ssh_is_server_known (ssh_session session)
 This function is deprecated.
 
char * ssh_dump_knownhost (ssh_session session)
 This function is deprecated.
 
int ssh_write_knownhost (ssh_session session)
 This function is deprecated.
 
void ssh_knownhosts_entry_free (struct ssh_knownhosts_entry *entry)
 Free an allocated ssh_knownhosts_entry.
 
struct ssh_list * ssh_known_hosts_get_algorithms (ssh_session session)
 
char * ssh_known_hosts_get_algorithms_names (ssh_session session)
 
int ssh_known_hosts_parse_line (const char *hostname, const char *line, struct ssh_knownhosts_entry **entry)
 Parse a line from a known_hosts entry into a structure.
 
enum ssh_known_hosts_e ssh_session_has_known_hosts_entry (ssh_session session)
 Check if the set hostname and port match an entry in known_hosts.
 
int ssh_session_export_known_hosts_entry (ssh_session session, char **pentry_string)
 Export the current session information to a known_hosts string.
 
int ssh_session_update_known_hosts (ssh_session session)
 Adds the currently connected server to the user known_hosts file.
 
enum ssh_known_hosts_e ssh_session_get_known_hosts_entry (ssh_session session, struct ssh_knownhosts_entry **pentry)
 Get the known_hosts entry for the currently connected session.
 
enum ssh_known_hosts_e ssh_session_get_known_hosts_entry_file (ssh_session session, const char *filename, struct ssh_knownhosts_entry **pentry)
 Get the known_hosts entry for the current connected session from the given known_hosts file.
 
enum ssh_known_hosts_e ssh_session_is_known_server (ssh_session session)
 Check if the servers public key for the connected session is known.
 
int ssh_options_copy (ssh_session src, ssh_session *dest)
 Duplicate the options of a session structure.
 
int ssh_options_set_algo (ssh_session session, enum ssh_kex_types_e algo, const char *list, char **place)
 
int ssh_options_set (ssh_session session, enum ssh_options_e type, const void *value)
 This function can set all possible ssh options.
 
int ssh_options_get_port (ssh_session session, unsigned int *port_target)
 This function can get ssh the ssh port. It must only be used on a valid ssh session. This function is useful when the session options have been automatically inferred from the environment or configuration files and one.
 
int ssh_options_get (ssh_session session, enum ssh_options_e type, char **value)
 This function can get ssh options, it does not support all options provided for ssh options set, but mostly those which a user-space program may care about having trusted the ssh driver to infer these values from underlying configuration files. It operates only on those SSH_OPTIONS_* which return char*. If you wish to receive the port then please use ssh_options_get_port() which returns an unsigned int.
 
int ssh_options_getopt (ssh_session session, int *argcptr, char **argv)
 Parse command line arguments.
 
int ssh_options_parse_config (ssh_session session, const char *filename)
 Parse the ssh config file.
 
int ssh_options_apply (ssh_session session)
 
ssh_session ssh_new (void)
 Create a new ssh session.
 
void ssh_free (ssh_session session)
 Deallocate a SSH session handle.
 
const char * ssh_get_clientbanner (ssh_session session)
 get the client banner
 
const char * ssh_get_serverbanner (ssh_session session)
 get the server banner
 
const char * ssh_get_kex_algo (ssh_session session)
 get the name of the current key exchange algorithm.
 
const char * ssh_get_cipher_in (ssh_session session)
 get the name of the input cipher for the given session.
 
const char * ssh_get_cipher_out (ssh_session session)
 get the name of the output cipher for the given session.
 
const char * ssh_get_hmac_in (ssh_session session)
 get the name of the input HMAC algorithm for the given session.
 
const char * ssh_get_hmac_out (ssh_session session)
 get the name of the output HMAC algorithm for the given session.
 
void ssh_silent_disconnect (ssh_session session)
 Disconnect impolitely from a remote host by closing the socket.
 
void ssh_set_blocking (ssh_session session, int blocking)
 Set the session in blocking/nonblocking mode.
 
int ssh_is_blocking (ssh_session session)
 Return the blocking mode of libssh.
 
int ssh_blocking_flush (ssh_session session, int timeout)
 Blocking flush of the outgoing buffer.
 
int ssh_is_connected (ssh_session session)
 Check if we are connected.
 
socket_t ssh_get_fd (ssh_session session)
 Get the fd of a connection.
 
void ssh_set_fd_toread (ssh_session session)
 Tell the session it has data to read on the file descriptor without blocking.
 
void ssh_set_fd_towrite (ssh_session session)
 Tell the session it may write to the file descriptor without blocking.
 
void ssh_set_fd_except (ssh_session session)
 Tell the session it has an exception to catch on the file descriptor.
 
int ssh_handle_packets (ssh_session session, int timeout)
 
int ssh_handle_packets_termination (ssh_session session, int timeout, ssh_termination_function fct, void *user)
 
int ssh_get_status (ssh_session session)
 Get session status.
 
int ssh_get_poll_flags (ssh_session session)
 Get poll flags for an external mainloop.
 
const char * ssh_get_disconnect_message (ssh_session session)
 Get the disconnect message from the server.
 
int ssh_get_version (ssh_session session)
 Get the protocol version of the session.
 
void ssh_socket_exception_callback (int code, int errno_code, void *user)
 
int ssh_send_ignore (ssh_session session, const char *data)
 Send a message that should be ignored.
 
int ssh_send_debug (ssh_session session, const char *message, int always_display)
 Send a debug message.
 
void ssh_set_counters (ssh_session session, ssh_counter scounter, ssh_counter rcounter)
 Set the session data counters.
 
int ssh_get_pubkey_hash (ssh_session session, unsigned char **hash)
 
void ssh_clean_pubkey_hash (unsigned char **hash)
 Deallocate the hash obtained by ssh_get_pubkey_hash.
 
int ssh_get_server_publickey (ssh_session session, ssh_key *key)
 Get the server public key from a session.
 
int ssh_get_publickey (ssh_session session, ssh_key *key)
 
int ssh_get_publickey_hash (const ssh_key key, enum ssh_publickey_hash_type type, unsigned char **hash, size_t *hlen)
 Allocates a buffer with the hash of the public key.
 

Detailed Description

Functions that manage a session.

Function Documentation

◆ ssh_blocking_flush()

int ssh_blocking_flush ( ssh_session session,
int timeout )

Blocking flush of the outgoing buffer.

Parameters
[in]sessionThe SSH session
[in]timeoutSet an upper limit on the time for which this function will block, in milliseconds. Specifying -1 means an infinite timeout. This parameter is passed to the poll() function.
Returns
SSH_OK on success, SSH_AGAIN if timeout occurred, SSH_ERROR otherwise.

◆ ssh_clean_pubkey_hash()

void ssh_clean_pubkey_hash ( unsigned char ** hash)

Deallocate the hash obtained by ssh_get_pubkey_hash.

This is required under Microsoft platform as this library might use a different C library than your software, hence a different heap.

Parameters
[in]hashThe buffer to deallocate.
See also
ssh_get_pubkey_hash()

◆ ssh_connect()

int ssh_connect ( ssh_session session)

Connect to the ssh server.

Parameters
[in]sessionThe ssh session to connect.
Returns
SSH_OK on success, SSH_ERROR on error.
SSH_AGAIN, if the session is in nonblocking mode, and call must be done again.
See also
ssh_new()
ssh_disconnect()

◆ ssh_copyright()

const char * ssh_copyright ( void )

Copyright information.

Returns copyright information

Returns
SSH_STRING copyright

◆ ssh_disconnect()

void ssh_disconnect ( ssh_session session)

Disconnect from a session (client or server).

The session can then be reused to open a new session.

Note
Note that this function won't close the socket if it was set with ssh_options_set and SSH_OPTIONS_FD. You're responsible for closing the socket. This is new behavior in libssh 0.10.
Parameters
[in]sessionThe SSH session to use.

◆ ssh_dump_knownhost()

char * ssh_dump_knownhost ( ssh_session session)

This function is deprecated.

Deprecated
Please use ssh_session_export_known_hosts_entry()

◆ ssh_free()

void ssh_free ( ssh_session session)

Deallocate a SSH session handle.

Parameters
[in]sessionThe SSH session to free.
See also
ssh_disconnect()
ssh_new()

◆ ssh_get_cipher_in()

const char * ssh_get_cipher_in ( ssh_session session)

get the name of the input cipher for the given session.

Parameters
[in]sessionThe SSH session.
Returns
Returns cipher name or NULL.

◆ ssh_get_cipher_out()

const char * ssh_get_cipher_out ( ssh_session session)

get the name of the output cipher for the given session.

Parameters
[in]sessionThe SSH session.
Returns
Returns cipher name or NULL.

◆ ssh_get_clientbanner()

const char * ssh_get_clientbanner ( ssh_session session)

get the client banner

Parameters
[in]sessionThe SSH session
Returns
Returns the client banner string or NULL.

◆ ssh_get_disconnect_message()

const char * ssh_get_disconnect_message ( ssh_session session)

Get the disconnect message from the server.

Parameters
[in]sessionThe ssh session to use.
Returns
The message sent by the server along with the disconnect, or NULL in which case the reason of the disconnect may be found with ssh_get_error.
See also
ssh_get_error()

◆ ssh_get_fd()

socket_t ssh_get_fd ( ssh_session session)

Get the fd of a connection.

In case you'd need the file descriptor of the connection to the server/client.

Parameters
[in]sessionThe ssh session to use.
Returns
The file descriptor of the connection, or -1 if it is not connected

◆ ssh_get_fingerprint_hash()

char * ssh_get_fingerprint_hash ( enum ssh_publickey_hash_type type,
unsigned char * hash,
size_t len )

Get a hash as a human-readable hex- or base64-string.

This gets an allocated fingerprint hash. If it is a SHA sum, it will return an unpadded base64 string. If it is a MD5 sum, it will return a hex string. Either way, the output is prepended by the hash-type.

Warning
Do NOT use MD5 or SHA1! Those hash functions are being deprecated.
Parameters
typeWhich sort of hash is given, use SSH_PUBLICKEY_HASH_SHA256 or better.
hashThe hash to be converted to fingerprint.
lenLength of the buffer to convert.
Returns
Returns the allocated fingerprint hash or NULL on error. The caller needs to free the memory using ssh_string_free_char().
See also
ssh_string_free_char()

◆ ssh_get_hmac_in()

const char * ssh_get_hmac_in ( ssh_session session)

get the name of the input HMAC algorithm for the given session.

Parameters
[in]sessionThe SSH session.
Returns
Returns HMAC algorithm name or NULL if unknown.

◆ ssh_get_hmac_out()

const char * ssh_get_hmac_out ( ssh_session session)

get the name of the output HMAC algorithm for the given session.

Parameters
[in]sessionThe SSH session.
Returns
Returns HMAC algorithm name or NULL if unknown.

◆ ssh_get_issue_banner()

char * ssh_get_issue_banner ( ssh_session session)

Get the issue banner from the server.

This is the banner showing a disclaimer to users who log in, typically their right or the fact that they will be monitored.

Parameters
[in]sessionThe SSH session to use.
Returns
A newly allocated string with the banner, NULL on error.

◆ ssh_get_kex_algo()

const char * ssh_get_kex_algo ( ssh_session session)

get the name of the current key exchange algorithm.

Parameters
[in]sessionThe SSH session
Returns
Returns the key exchange algorithm string or NULL.

◆ ssh_get_openssh_version()

int ssh_get_openssh_version ( ssh_session session)

Get the version of the OpenSSH server, if it is not an OpenSSH server then 0 will be returned.

You can use the SSH_VERSION_INT macro to compare version numbers.

Parameters
[in]sessionThe SSH session to use.
Returns
The version number if available, 0 otherwise.
int openssh = ssh_get_openssh_version();
if (openssh == SSH_INT_VERSION(6, 1, 0)) {
printf("Version match!\m");
}
ssh_get_openssh_version
LIBSSH_API int ssh_get_openssh_version(ssh_session session)
Get the version of the OpenSSH server, if it is not an OpenSSH server then 0 will be returned.
Definition client.c:695

◆ ssh_get_poll_flags()

int ssh_get_poll_flags ( ssh_session session)

Get poll flags for an external mainloop.

Parameters
sessionThe ssh session to use.
Returns
A bitmask including SSH_READ_PENDING or SSH_WRITE_PENDING. For SSH_READ_PENDING, your invocation of poll() should include POLLIN. For SSH_WRITE_PENDING, your invocation of poll() should include POLLOUT.

◆ ssh_get_pubkey_hash()

int ssh_get_pubkey_hash ( ssh_session session,
unsigned char ** hash )
Deprecated
Use ssh_get_publickey_hash()

◆ ssh_get_publickey()

int ssh_get_publickey ( ssh_session session,
ssh_key * key )
Deprecated
Use ssh_get_server_publickey()

◆ ssh_get_publickey_hash()

int ssh_get_publickey_hash ( const ssh_key key,
enum ssh_publickey_hash_type type,
unsigned char ** hash,
size_t * hlen )

Allocates a buffer with the hash of the public key.

This function allows you to get a hash of the public key. You can then print this hash in a human-readable form to the user so that he is able to verify it. Use ssh_get_hexa() or ssh_print_hash() to display it.

Parameters
[in]keyThe public key to create the hash for.
[in]typeThe type of the hash you want.
[out]hashA pointer to store the allocated buffer. It can be freed using ssh_clean_pubkey_hash().
[in]hlenThe length of the hash.
Returns
0 on success, -1 if an error occurred.
Warning
It is very important that you verify at some moment that the hash matches a known server. If you don't do it, cryptography won't help you at making things secure. OpenSSH uses SHA256 to print public key digests.
See also
ssh_session_update_known_hosts()
ssh_get_hexa()
ssh_print_hash()
ssh_clean_pubkey_hash()

◆ ssh_get_server_publickey()

int ssh_get_server_publickey ( ssh_session session,
ssh_key * key )

Get the server public key from a session.

Parameters
[in]sessionThe session to get the key from.
[out]keyA pointer to store the allocated key. You need to free the key using ssh_key_free().
Returns
SSH_OK on success, SSH_ERROR on error.
See also
ssh_key_free()

◆ ssh_get_serverbanner()

const char * ssh_get_serverbanner ( ssh_session session)

get the server banner

Parameters
[in]sessionThe SSH session
Returns
Returns the server banner string or NULL.

◆ ssh_get_status()

int ssh_get_status ( ssh_session session)

Get session status.

Parameters
sessionThe ssh session to use.
Returns
A bitmask including SSH_CLOSED, SSH_READ_PENDING, SSH_WRITE_PENDING or SSH_CLOSED_ERROR which respectively means the session is closed, has data to read on the connection socket and session was closed due to an error.

◆ ssh_get_version()

int ssh_get_version ( ssh_session session)

Get the protocol version of the session.

Parameters
sessionThe ssh session to use.
Returns
The SSH version as integer, < 0 on error.

◆ ssh_is_blocking()

int ssh_is_blocking ( ssh_session session)

Return the blocking mode of libssh.

Parameters
[in]sessionThe SSH session
Returns
0 if the session is nonblocking,
1 if the functions may block.

◆ ssh_is_connected()

int ssh_is_connected ( ssh_session session)

Check if we are connected.

Parameters
[in]sessionThe session to check if it is connected.
Returns
1 if we are connected, 0 if not.

◆ ssh_is_server_known()

int ssh_is_server_known ( ssh_session session)

This function is deprecated.

Deprecated
Please use ssh_session_is_known_server()
See also
ssh_session_is_known_server()

◆ ssh_known_hosts_parse_line()

int ssh_known_hosts_parse_line ( const char * hostname,
const char * line,
struct ssh_knownhosts_entry ** entry )

Parse a line from a known_hosts entry into a structure.

This parses a known_hosts entry into a structure with the key in a libssh consumeable form. You can use the PKI key function to further work with it.

Parameters
[in]hostnameThe hostname to match the line to
[in]lineThe line to compare and parse if we have a hostname match.
[in]entryA pointer to store the allocated known_hosts entry structure. The user needs to free the memory using SSH_KNOWNHOSTS_ENTRY_FREE().
Returns
SSH_OK on success, SSH_ERROR otherwise.

◆ ssh_knownhosts_entry_free()

void ssh_knownhosts_entry_free ( struct ssh_knownhosts_entry * entry)

Free an allocated ssh_knownhosts_entry.

Use SSH_KNOWNHOSTS_ENTRY_FREE() to set the pointer to NULL.

Parameters
[in]entryThe entry to free.

◆ ssh_new()

ssh_session ssh_new ( void )

Create a new ssh session.

Returns
A new ssh_session pointer, NULL on error.

◆ ssh_options_copy()

int ssh_options_copy ( ssh_session src,
ssh_session * dest )

Duplicate the options of a session structure.

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

Parameters
srcThe session to use to copy the options.
destA pointer to store the allocated session with duplicated options. You have to free the memory using ssh_free()
Returns
0 on success, -1 on error with errno set.
See also
ssh_connect()
ssh_free()

◆ ssh_options_get()

int ssh_options_get ( ssh_session session,
enum ssh_options_e type,
char ** value )

This function can get ssh options, it does not support all options provided for ssh options set, but mostly those which a user-space program may care about having trusted the ssh driver to infer these values from underlying configuration files. It operates only on those SSH_OPTIONS_* which return char*. If you wish to receive the port then please use ssh_options_get_port() which returns an unsigned int.

Parameters
sessionAn allocated SSH session structure.
typeThe option type to get. This could be one of the following:
  • SSH_OPTIONS_HOST: The hostname or ip address to connect to (const char *).
  • SSH_OPTIONS_USER: The username for authentication (const char *).

    when not explicitly set this will be inferred from the ~/.ssh/config file.
  • SSH_OPTIONS_IDENTITY: Get the first identity file name (const char *).

    By default id_rsa, id_ecdsa and id_ed25519 files are used.
  • SSH_OPTIONS_PROXYCOMMAND: Get the proxycommand necessary to log into the remote host. When not explicitly set, it will be read from the ~/.ssh/config file.
  • SSH_OPTIONS_GLOBAL_KNOWNHOSTS: Get the path to the global known_hosts file being used.
  • SSH_OPTIONS_KNOWNHOSTS: Get the path to the known_hosts file being used.
  • SSH_OPTIONS_CONTROL_PATH: Get the path to the control socket being used for connection multiplexing.
Parameters
valueThe value to get into. As a char**, space will be allocated by the function for the value, it is your responsibility to free the memory using ssh_string_free_char().
Returns
SSH_OK on success, SSH_ERROR on error.

◆ ssh_options_get_port()

int ssh_options_get_port ( ssh_session session,
unsigned int * port_target )

This function can get ssh the ssh port. It must only be used on a valid ssh session. This function is useful when the session options have been automatically inferred from the environment or configuration files and one.

Parameters
sessionAn allocated SSH session structure.
port_targetAn unsigned integer into which the port will be set from the ssh session.
Returns
0 on success, < 0 on error.

◆ ssh_options_getopt()

int ssh_options_getopt ( ssh_session session,
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 won't appear anymore in them.
The single arguments (without switches) are not parsed. thus, myssh -l user localhost
The command won't set the hostname value of options to localhost.

Parameters
sessionThe session to configure.
argcptrThe pointer to the argument count.
argvThe arguments list pointer.
Returns
0 on success, < 0 on error.
See also
ssh_session_new()

◆ ssh_options_parse_config()

int ssh_options_parse_config ( ssh_session session,
const char * filename )

Parse the ssh config file.

This should be the last call of all options, it may overwrite options which are already set. It requires that the host name is already set with ssh_options_set(SSH_OPTIONS_HOST).

Parameters
sessionSSH session handle
filenameThe options file to use, if NULL the default ~/.ssh/config and /etc/ssh/ssh_config will be used.
Returns
0 on success, < 0 on error.
See also
ssh_options_set()

◆ ssh_options_set()

int ssh_options_set ( ssh_session session,
enum ssh_options_e type,
const void * value )

This function can set all possible ssh options.

Parameters
sessionAn allocated SSH session structure.
typeThe option type to set. This could be one of the following:
  • SSH_OPTIONS_HOST: The hostname or ip address to connect to (const char *).
  • SSH_OPTIONS_PORT: The port to connect to (unsigned int *).
  • SSH_OPTIONS_PORT_STR: The port to connect to (const char *).
  • SSH_OPTIONS_FD: The file descriptor to use (socket_t).

    If you wish to open the socket yourself for a reason or another, set the file descriptor and take care of closing it (this is new behavior in libssh 0.10). Don't forget to set the hostname as the hostname is used as a key in the known_host mechanism.
  • SSH_OPTIONS_BINDADDR: The address to bind the client to (const char *).
  • SSH_OPTIONS_USER: The username for authentication (const char *).

    If the value is NULL, the username is set to the default username.
  • SSH_OPTIONS_SSH_DIR: Set the ssh directory (const char *,format string).

    If the value is NULL, the directory is set to the default ssh directory.

    The ssh directory is used for files like known_hosts and identity (private and public key). It may include "%s" which will be replaced by the user home directory.
  • SSH_OPTIONS_KNOWNHOSTS: Set the known hosts file name (const char *,format string).

    If the value is NULL, the directory is set to the default known hosts file, normally ~/.ssh/known_hosts.

    The known hosts file is used to certify remote hosts are genuine. It may include "%d" which will be replaced by the user home directory.
  • SSH_OPTIONS_GLOBAL_KNOWNHOSTS: Set the global known hosts file name (const char *,format string).

    If the value is NULL, the directory is set to the default global known hosts file, normally /etc/ssh/ssh_known_hosts.

    The known hosts file is used to certify remote hosts are genuine.
  • SSH_OPTIONS_ADD_IDENTITY (or SSH_OPTIONS_IDENTITY): Add a new identity file (const char *, format string) to the identity list.

    By default id_rsa, id_ecdsa and id_ed25519 files are used.

    The identity used to authenticate with public key will be prepended to the list. It may include "%s" which will be replaced by the user home directory.
  • SSH_OPTIONS_CERTIFICATE: Add a new certificate file (const char *, format string) to the certificate list.

    By default id_rsa-cert.pub, id_ecdsa-cert.pub and id_ed25519-cert.pub files are used, when the underlying private key is present.

    The certificate itself can not be used to authenticate to remote server so it needs to be paired with private key (aka identity file) provided with separate option, from agent or from PKCS#11 token. It may include "%s" which will be replaced by the user home directory.
  • SSH_OPTIONS_TIMEOUT: Set a timeout for the connection in seconds (long).
  • SSH_OPTIONS_TIMEOUT_USEC: Set a timeout for the connection in micro seconds (long).
  • SSH_OPTIONS_SSH1: Deprecated
  • SSH_OPTIONS_SSH2: Unused
  • SSH_OPTIONS_LOG_VERBOSITY: Set the session logging verbosity (int).

    The verbosity of the messages. Every log smaller or equal to verbosity will be shown.
    • SSH_LOG_NOLOG: No logging
    • SSH_LOG_WARNING: Only warnings
    • SSH_LOG_PROTOCOL: High level protocol information
    • SSH_LOG_PACKET: Lower level protocol information, packet level
    • SSH_LOG_FUNCTIONS: Every function path The default is SSH_LOG_NOLOG.
  • SSH_OPTIONS_LOG_VERBOSITY_STR: Set the session logging verbosity via a string that will be converted to a numerical value (e.g. "3") and interpreted according to the values of SSH_OPTIONS_LOG_VERBOSITY above (const char *).
  • SSH_OPTIONS_CIPHERS_C_S: Set the symmetric cipher client to server (const char *, comma-separated list). The list can be prepended by +,-,^ which can append, remove or move to the beginning (prioritizing) of the default list respectively. Giving an empty list after + and ^ will cause error.
  • SSH_OPTIONS_CIPHERS_S_C: Set the symmetric cipher server to client (const char *, comma-separated list). The list can be prepended by +,-,^ which can append, remove or move to the beginning (prioritizing) of the default list respectively. Giving an empty list after + and ^ will cause error.
  • SSH_OPTIONS_KEY_EXCHANGE: Set the key exchange method to be used (const char *, comma-separated list). ex: "ecdh-sha2-nistp256,diffie-hellman-group14-sha1,diffie-hellman-group1-sha1" The list can be prepended by +,-,^ which will append, remove or move to the beginning (prioritizing) of the default list respectively. Giving an empty list after + and ^ will cause error.
  • SSH_OPTIONS_HMAC_C_S: Set the Message Authentication Code algorithm client to server (const char *, comma-separated list). The list can be prepended by +,-,^ which will append, remove or move to the beginning (prioritizing) of the default list respectively. Giving an empty list after + and ^ will cause error.
  • SSH_OPTIONS_HMAC_S_C: Set the Message Authentication Code algorithm server to client (const char *, comma-separated list). The list can be prepended by +,-,^ which will append, remove or move to the beginning (prioritizing) of the default list respectively. Giving an empty list after + and ^ will cause error.
  • SSH_OPTIONS_HOSTKEYS: Set the preferred server host key types (const char *, comma-separated list). ex: "ssh-rsa,ecdh-sha2-nistp256". The list can be prepended by +,-,^ which will append, remove or move to the beginning (prioritizing) of the default list respectively. Giving an empty list after + and ^ will cause error.
  • SSH_OPTIONS_PUBLICKEY_ACCEPTED_TYPES: Set the preferred public key algorithms to be used for authentication (const char *, comma-separated list). ex: "ssh-rsa,rsa-sha2-256,ecdh-sha2-nistp256" The list can be prepended by +,-,^ which will append, remove or move to the beginning (prioritizing) of the default list respectively. Giving an empty list after + and ^ will cause error.
  • SSH_OPTIONS_COMPRESSION_C_S: Set the compression to use for client to server communication (const char *, "yes", "no" or a specific algorithm name if needed ("zlib","zlib@openssh.com","none").
  • SSH_OPTIONS_COMPRESSION_S_C: Set the compression to use for server to client communication (const char *, "yes", "no" or a specific algorithm name if needed ("zlib","zlib@openssh.com","none").
  • SSH_OPTIONS_COMPRESSION: Set the compression to use for both directions communication (const char *, "yes", "no" or a specific algorithm name if needed ("zlib","zlib@openssh.com","none").
  • SSH_OPTIONS_COMPRESSION_LEVEL: Set the compression level to use for zlib functions. (int, value from 1 to 9, 9 being the most efficient but slower).
  • SSH_OPTIONS_STRICTHOSTKEYCHECK: Set the parameter StrictHostKeyChecking to avoid asking about a fingerprint (int, 0 = false).
  • SSH_OPTIONS_PROXYCOMMAND: Set the command to be executed in order to connect to server (const char *).
  • SSH_OPTIONS_GSSAPI_SERVER_IDENTITY Set it to specify the GSSAPI server identity that libssh should expect when connecting to the server (const char *).
  • SSH_OPTIONS_GSSAPI_CLIENT_IDENTITY Set it to specify the GSSAPI client identity that libssh should expect when connecting to the server (const char *).
  • SSH_OPTIONS_GSSAPI_DELEGATE_CREDENTIALS Set it to specify that GSSAPI should delegate credentials to the server (int, 0 = false).
  • SSH_OPTIONS_PASSWORD_AUTH Set it if password authentication should be used in ssh_userauth_auto_pubkey(). (int, 0=false). Currently without effect (ssh_userauth_auto_pubkey doesn't use password authentication).
  • SSH_OPTIONS_PUBKEY_AUTH Set it if pubkey authentication should be used in ssh_userauth_auto_pubkey(). (int, 0=false).
  • SSH_OPTIONS_KBDINT_AUTH Set it if keyboard-interactive authentication should be used in ssh_userauth_auto_pubkey(). (int, 0=false). Currently without effect (ssh_userauth_auto_pubkey doesn't use keyboard-interactive authentication).
  • SSH_OPTIONS_GSSAPI_AUTH Set it if gssapi authentication should be used in ssh_userauth_auto_pubkey(). (int, 0=false). Currently without effect (ssh_userauth_auto_pubkey doesn't use gssapi authentication).
  • SSH_OPTIONS_NODELAY Set it to disable Nagle's Algorithm (TCP_NODELAY) on the session socket. (int, 0=false)
  • SSH_OPTIONS_PROCESS_CONFIG Set it to false to disable automatic processing of per-user and system-wide OpenSSH configuration files. LibSSH automatically uses these configuration files unless you provide it with this option or with different file (bool).
  • SSH_OPTIONS_REKEY_DATA Set the data limit that can be transferred with a single key in bytes. RFC 4253 Section 9 recommends 1GB of data, while RFC 4344 provides more specific restrictions, that are applied automatically. When specified, the lower value will be used. (uint64_t, 0=default)
  • SSH_OPTIONS_REKEY_TIME Set the time limit for a session before initializing a rekey in seconds. RFC 4253 Section 9 recommends one hour. (uint32_t, 0=off)
  • SSH_OPTIONS_RSA_MIN_SIZE Set the minimum RSA key size in bits to be accepted by the client for both authentication and hostkey verification. The values under 768 bits are not accepted even with this configuration option as they are considered completely broken. Setting 0 will revert the value to defaults. Default is 1024 bits or 2048 bits in FIPS mode. (int *)
  • SSH_OPTIONS_IDENTITY_AGENT Set the path to the SSH agent socket. If unset, the SSH_AUTH_SOCK environment is consulted. (const char *)
  • SSH_OPTIONS_IDENTITIES_ONLY Use only keys specified in the SSH config, even if agent offers more. (bool)

  • SSH_OPTIONS_CONTROL_MASTER Set the option to enable the sharing of multiple sessions over a single network connection using connection multiplexing.

    The possible options are among the following:

    • SSH_CONTROL_MASTER_AUTO: enable connection sharing if possible
    • SSH_CONTROL_MASTER_YES: enable connection sharing unconditionally
    • SSH_CONTROL_MASTER_ASK: ask for confirmation if connection sharing is to be enabled
    • SSH_CONTROL_MASTER_AUTOASK: enable connection sharing if possible, but ask for confirmation
    • SSH_CONTROL_MASTER_NO: disable connection sharing unconditionally

    The default is SSH_CONTROL_MASTER_NO.

  • SSH_OPTIONS_CONTROL_PATH Set the path to the control socket used for connection sharing. Set to "none" to disable connection sharing. (const char *)
Parameters
valueThe value to set. This is a generic pointer and the datatype which is used should be set according to the type set.
Returns
0 on success, < 0 on error.

◆ ssh_print_hash()

void ssh_print_hash ( enum ssh_publickey_hash_type type,
unsigned char * hash,
size_t len )

Print a hash as a human-readable hex- or base64-string.

This prints an unpadded base64 strings for SHA sums and hex strings for MD5 sum. Either way, the output is prepended by the hash-type.

Parameters
typeWhich sort of hash is given. Use SSH_PUBLICKEY_HASH_SHA256 or better.
hashThe hash to be converted to fingerprint.
lenLength of the buffer to convert.
See also
ssh_get_publickey_hash()
ssh_get_fingerprint_hash()

◆ ssh_request_no_more_sessions()

int ssh_request_no_more_sessions ( ssh_session session)

Most SSH connections will only ever request a single session, but an attacker may abuse a running ssh client to surreptitiously open additional sessions under their control. OpenSSH provides a global request "no-more-sessions@openssh.com" to mitigate this attack.

Parameters
[in]sessionThe SSH session to use.
Returns
SSH_OK on success, SSH_ERROR on error.
SSH_AGAIN, if the session is in nonblocking mode, and call must be done again.

◆ ssh_select()

int ssh_select ( ssh_channel * channels,
ssh_channel * outchannels,
socket_t maxfd,
fd_set * readfds,
struct timeval * timeout )

A wrapper for the select syscall.

This function acts more or less like the select(2) syscall.
There is no support for writing or exceptions.

Parameters
[in]channelsArrays of channels pointers terminated by a NULL. It is never rewritten.
[out]outchannelsArrays of the same size as "channels", there is no need to initialize it.
[in]maxfdMaximum +1 file descriptor from readfds.
[in]readfdsA fd_set of file descriptors to be select'ed for reading.
[in]timeoutThe timeout in milliseconds.
Returns
SSH_OK on success, SSH_ERROR on error, SSH_EINTR if it was interrupted. In that case, just restart it.
Warning
libssh is not reentrant here. That means that if a signal is caught during the processing of this function, you cannot call libssh functions on sessions that are busy with ssh_select().
See also
select(2)

◆ ssh_send_debug()

int ssh_send_debug ( ssh_session session,
const char * message,
int always_display )

Send a debug message.

Parameters
[in]sessionThe SSH session
[in]messageData to be sent
[in]always_displayMessage SHOULD be displayed by the server. It SHOULD NOT be displayed unless debugging information has been explicitly requested.
Returns
SSH_OK on success, SSH_ERROR otherwise.

◆ ssh_send_ignore()

int ssh_send_ignore ( ssh_session session,
const char * data )

Send a message that should be ignored.

Parameters
[in]sessionThe SSH session
[in]dataData to be sent
Returns
SSH_OK on success, SSH_ERROR otherwise.

◆ ssh_session_export_known_hosts_entry()

int ssh_session_export_known_hosts_entry ( ssh_session session,
char ** pentry_string )

Export the current session information to a known_hosts string.

This exports the current information of a session which is connected so a ssh server into an entry line which can be added to a known_hosts file.

Parameters
[in]sessionThe session with information to export.
[in]pentry_stringA pointer to a string to store the allocated line of the entry. The user must free it using ssh_string_free_char().
Returns
SSH_OK on success, SSH_ERROR otherwise.

◆ ssh_session_get_known_hosts_entry()

enum ssh_known_hosts_e ssh_session_get_known_hosts_entry ( ssh_session session,
struct ssh_knownhosts_entry ** pentry )

Get the known_hosts entry for the currently connected session.

Parameters
[in]sessionThe session to validate.
[in]pentryA pointer to store the allocated known hosts entry.
Returns
SSH_KNOWN_HOSTS_OK: The server is known and has not changed.
SSH_KNOWN_HOSTS_CHANGED: The server key has changed. Either you are under attack or the administrator changed the key. You HAVE to warn the user about a possible attack.
SSH_KNOWN_HOSTS_OTHER: The server gave use a key of a type while we had an other type recorded. It is a possible attack.
SSH_KNOWN_HOSTS_UNKNOWN: The server is unknown. User should confirm the public key hash is correct.
SSH_KNOWN_HOSTS_NOT_FOUND: The known host file does not exist. The host is thus unknown. File will be created if host key is accepted.
SSH_KNOWN_HOSTS_ERROR: There had been an error checking the host.
See also
ssh_knownhosts_entry_free()

◆ ssh_session_get_known_hosts_entry_file()

enum ssh_known_hosts_e ssh_session_get_known_hosts_entry_file ( ssh_session session,
const char * filename,
struct ssh_knownhosts_entry ** pentry )

Get the known_hosts entry for the current connected session from the given known_hosts file.

Parameters
[in]sessionThe session to validate.
[in]filenameThe filename to parse.
[in]pentryA pointer to store the allocated known hosts entry.
Returns
SSH_KNOWN_HOSTS_OK: The server is known and has not changed.
SSH_KNOWN_HOSTS_CHANGED: The server key has changed. Either you are under attack or the administrator changed the key. You HAVE to warn the user about a possible attack.
SSH_KNOWN_HOSTS_OTHER: The server gave use a key of a type while we had an other type recorded. It is a possible attack.
SSH_KNOWN_HOSTS_UNKNOWN: The server is unknown. User should confirm the public key hash is correct.
SSH_KNOWN_HOSTS_NOT_FOUND: The known host file does not exist. The host is thus unknown. File will be created if host key is accepted.
SSH_KNOWN_HOSTS_ERROR: There had been an error checking the host.
See also
ssh_knownhosts_entry_free()

◆ ssh_session_has_known_hosts_entry()

enum ssh_known_hosts_e ssh_session_has_known_hosts_entry ( ssh_session session)

Check if the set hostname and port match an entry in known_hosts.

This check if the set hostname and port have an entry in the known_hosts file. You need to set at least the hostname using ssh_options_set().

Parameters
[in]sessionThe session with the values set to check.
Returns
A ssh_known_hosts_e return value.

◆ ssh_session_is_known_server()

enum ssh_known_hosts_e ssh_session_is_known_server ( ssh_session session)

Check if the servers public key for the connected session is known.

This checks if we already know the public key of the server we want to connect to. This allows to detect if there is a MITM attach going on of if there have been changes on the server we don't know about.

Parameters
[in]sessionThe SSH to validate.
Returns
SSH_KNOWN_HOSTS_OK: The server is known and has not changed.
SSH_KNOWN_HOSTS_CHANGED: The server key has changed. Either you are under attack or the administrator changed the key. You HAVE to warn the user about a possible attack.
SSH_KNOWN_HOSTS_OTHER: The server gave use a key of a type while we had an other type recorded. It is a possible attack.
SSH_KNOWN_HOSTS_UNKNOWN: The server is unknown. User should confirm the public key hash is correct.
SSH_KNOWN_HOSTS_NOT_FOUND: The known host file does not exist. The host is thus unknown. File will be created if host key is accepted.
SSH_KNOWN_HOSTS_ERROR: There had been an error checking the host.

◆ ssh_session_set_disconnect_message()

int ssh_session_set_disconnect_message ( ssh_session session,
const char * message )

Add disconnect message when ssh_session is disconnected To add a disconnect message to give peer a better hint.

Parameters
sessionThe SSH session to use.
messageThe message to send after the session is disconnected. If no message is passed then a default message i.e "Bye Bye" will be sent.

◆ ssh_session_update_known_hosts()

int ssh_session_update_known_hosts ( ssh_session session)

Adds the currently connected server to the user known_hosts file.

This adds the currently connected server to the known_hosts file by appending a new line at the end. The global known_hosts file is considered read-only so it is not touched by this function.

Parameters
[in]sessionThe session to use to write the entry.
Returns
SSH_OK on success, SSH_ERROR otherwise.

◆ ssh_set_blocking()

void ssh_set_blocking ( ssh_session session,
int blocking )

Set the session in blocking/nonblocking mode.

Parameters
[in]sessionThe ssh session to change.
[in]blockingZero for nonblocking mode.

◆ ssh_set_counters()

void ssh_set_counters ( ssh_session session,
ssh_counter scounter,
ssh_counter rcounter )

Set the session data counters.

This function sets the counter structures to be used to calculate data which comes in and goes out through the session at different levels.

struct ssh_counter_struct scounter = {
.in_bytes = 0,
.out_bytes = 0,
.in_packets = 0,
.out_packets = 0
};
struct ssh_counter_struct rcounter = {
.in_bytes = 0,
.out_bytes = 0,
.in_packets = 0,
.out_packets = 0
};
ssh_set_counters(session, &scounter, &rcounter);
ssh_set_counters
LIBSSH_API void ssh_set_counters(ssh_session session, ssh_counter scounter, ssh_counter rcounter)
Set the session data counters.
Definition session.c:1014
Parameters
[in]sessionThe SSH session.
[in]scounterCounter for byte data handled by the session sockets.
[in]rcounterCounter for byte and packet data handled by the session, prior compression and SSH overhead.

◆ ssh_set_fd_except()

void ssh_set_fd_except ( ssh_session session)

Tell the session it has an exception to catch on the file descriptor.

Parameters
[in]sessionThe ssh session to use.

◆ ssh_set_fd_toread()

void ssh_set_fd_toread ( ssh_session session)

Tell the session it has data to read on the file descriptor without blocking.

Parameters
[in]sessionThe ssh session to use.

◆ ssh_set_fd_towrite()

void ssh_set_fd_towrite ( ssh_session session)

Tell the session it may write to the file descriptor without blocking.

Parameters
[in]sessionThe ssh session to use.

◆ ssh_silent_disconnect()

void ssh_silent_disconnect ( ssh_session session)

Disconnect impolitely from a remote host by closing the socket.

Suitable if you forked and want to destroy this session.

Parameters
[in]sessionThe SSH session to disconnect.

◆ ssh_write_knownhost()

int ssh_write_knownhost ( ssh_session session)

This function is deprecated.

Deprecated
Please use ssh_session_update_known_hosts()
Generated by doxygen 1.10.0