The SSH session functions.
[The libssh API]

Functions that manage a session. More...

Functions

int ssh_blocking_flush (ssh_session session, int timeout)
 Blocking flush of the outgoing buffer.
void ssh_clean_pubkey_hash (unsigned char **hash)
 Deallocate the hash obtained by ssh_get_pubkey_hash.
int ssh_connect (ssh_session session)
 Connect to the ssh server.
void ssh_disconnect (ssh_session session)
 Disconnect from a session (client or server).
void ssh_free (ssh_session session)
 Deallocate a SSH session handle.
const char * ssh_get_disconnect_message (ssh_session session)
 Get the disconnect message from the server.
socket_t ssh_get_fd (ssh_session session)
 Get the fd of a connection.
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_get_pubkey_hash (ssh_session session, unsigned char **hash)
 Allocates a buffer with the MD5 hash of the server public key.
int ssh_get_status (ssh_session session)
 Get session status.
int ssh_get_version (ssh_session session)
 Get the protocol version of the session.
int ssh_is_blocking (ssh_session session)
 Return the blocking mode of libssh.
int ssh_is_connected (ssh_session session)
 Check if we are connected.
int ssh_is_server_known (ssh_session session)
 Check if the server is known.
ssh_session ssh_new (void)
 Create a new ssh session.
int ssh_options_copy (ssh_session src, ssh_session *dest)
 Duplicate the options of a session structure.
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_set (ssh_session session, enum ssh_options_e type, const void *value)
 This function can set all possible ssh options.
int ssh_select (ssh_channel *channels, ssh_channel *outchannels, socket_t maxfd, fd_set *readfds, struct timeval *timeout)
 A wrapper for the select syscall.
void ssh_set_blocking (ssh_session session, int blocking)
 Set the session in blocking/nonblocking mode.
void ssh_set_fd_except (ssh_session session)
 Tell the session it has an exception to catch on the file descriptor.
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_silent_disconnect (ssh_session session)
 Disconnect impolitely from a remote host by closing the socket.
int ssh_write_knownhost (ssh_session session)
 Write the current server as known in the known hosts file.

Detailed Description

Functions that manage a session.


Function Documentation

int ssh_blocking_flush ( ssh_session  session,
int  timeout 
)

Blocking flush of the outgoing buffer.

Parameters:
[in] session The SSH session
[in] timeout Set 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.

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] hash The buffer to deallocate.
See also:
ssh_get_pubkey_hash()

int ssh_connect ( ssh_session  session  ) 

Connect to the ssh server.

Parameters:
[in] session The 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()

void ssh_disconnect ( ssh_session  session  ) 

Disconnect from a session (client or server).

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

Parameters:
[in] session The SSH session to use.

void ssh_free ( ssh_session  session  ) 

Deallocate a SSH session handle.

Parameters:
[in] session The SSH session to free.
See also:
ssh_disconnect()

ssh_new()

const char* ssh_get_disconnect_message ( ssh_session  session  ) 

Get the disconnect message from the server.

Parameters:
[in] session The 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()

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] session The ssh session to use.
Returns:
The file descriptor of the connection, or -1 if it is not connected

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] session The SSH session to use.
Returns:
A newly allocated string with the banner, NULL on error.

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] session The SSH session to use.
Returns:
The version number if available, 0 otherwise.

int ssh_get_pubkey_hash ( ssh_session  session,
unsigned char **  hash 
)

Allocates a buffer with the MD5 hash of the server public key.

Parameters:
[in] session The SSH session to use.
[in] hash The buffer to allocate.
Returns:
The bytes allocated or < 0 on error.
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 wont help you at making things secure
See also:
ssh_is_server_known()

ssh_get_hexa()

ssh_print_hexa()

int ssh_get_status ( ssh_session  session  ) 

Get session status.

Parameters:
session The ssh session to use.
Returns:
A bitmask including SSH_CLOSED, SSH_READ_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.

int ssh_get_version ( ssh_session  session  ) 

Get the protocol version of the session.

Parameters:
session The ssh session to use.
Returns:
1 or 2, for ssh1 or ssh2, < 0 on error.

int ssh_is_blocking ( ssh_session  session  ) 

Return the blocking mode of libssh.

Parameters:
[in] session The SSH session
Returns:
0 if the session is nonblocking,

1 if the functions may block.

int ssh_is_connected ( ssh_session  session  ) 

Check if we are connected.

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

int ssh_is_server_known ( ssh_session  session  ) 

Check if the server is known.

Checks the user's known host file for a previous connection to the current server.

Parameters:
[in] session The SSH session to use.
Returns:
SSH_SERVER_KNOWN_OK: The server is known and has not changed.
SSH_SERVER_KNOWN_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_SERVER_FOUND_OTHER: The server gave use a key of a type while we had an other type recorded. It is a possible attack.
SSH_SERVER_NOT_KNOWN: The server is unknown. User should confirm the MD5 is correct.
SSH_SERVER_FILE_NOT_FOUND: The known host file does not exist. The host is thus unknown. File will be created if host key is accepted.
SSH_SERVER_ERROR: Some error happened.
See also:
ssh_get_pubkey_hash()
Bug:
There is no current way to remove or modify an entry into the known host table.

ssh_session ssh_new ( void   ) 

Create a new ssh session.

Returns:
A new ssh_session pointer, NULL on error.

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_session_connect.

Parameters:
src The session to use to copy the options.
dest The session to copy the options to.
Returns:
0 on sucess, -1 on error with errno set.
See also:
ssh_session_connect()

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 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:
session The session to configure.
argcptr The pointer to the argument count.
argv The arguments list pointer.
Returns:
0 on success, < 0 on error.
See also:
ssh_session_new()

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_host().

Parameters:
session SSH session handle
filename The options file to use, if NULL the default ~/.ssh/config will be used.
Returns:
0 on success, < 0 on error.
See also:
ssh_options_set_host()

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

This function can set all possible ssh options.

Parameters:
session An allocated SSH session structure.
type The option type to set. This could be one of the following:

Parameters:
value The 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.

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 functions acts more or less like the select(2) syscall.
There is no support for writing or exceptions.

Parameters:
[in] channels Arrays of channels pointers terminated by a NULL. It is never rewritten.
[out] outchannels Arrays of same size that "channels", there is no need to initialize it.
[in] maxfd Maximum +1 file descriptor from readfds.
[in] readfds A fd_set of file descriptors to be select'ed for reading.
[in] timeout A timeout for the select.
Returns:
-1 if an error occured. SSH_EINTR if it was interrupted, in that case, just restart it.
Warning:
libssh is not threadsafe here. That means that if a signal is caught during the processing of this function, you cannot call ssh functions on sessions that are busy with ssh_select().
See also:
select(2)

void ssh_set_blocking ( ssh_session  session,
int  blocking 
)

Set the session in blocking/nonblocking mode.

Parameters:
[in] session The ssh session to change.
[in] blocking Zero for nonblocking mode.
Bug:
nonblocking code is in development and won't work as expected

void ssh_set_fd_except ( ssh_session  session  ) 

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

Parameters:
[in] session The ssh session to use.

void ssh_set_fd_toread ( ssh_session  session  ) 

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

Parameters:
[in] session The ssh session to use.

void ssh_set_fd_towrite ( ssh_session  session  ) 

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

Parameters:
[in] session The ssh session to use.

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] session The SSH session to disconnect.

int ssh_write_knownhost ( ssh_session  session  ) 

Write the current server as known in the known hosts file.

This will create the known hosts file if it does not exist. You generaly use it when ssh_is_server_known() answered SSH_SERVER_NOT_KNOWN.

Parameters:
[in] session The ssh session to use.
Returns:
SSH_OK on success, SSH_ERROR on error.


Generated on 19 Dec 2014 for libssh by  doxygen 1.4.7