SSH Session

functions that manage a session More...

Functions

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).
int ssh_finalize (void)
 Finalize and cleanup all libssh and cryptographic data structures.
void ssh_free (ssh_session session)
 deallocate a 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)
 In case you'd need the file descriptor of the connection to the server/client.
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_handle_packets (ssh_session session)
int ssh_init (void)
 initialize global cryptographic data structures.
int ssh_is_server_known (ssh_session session)
 Check if the server is known.
ssh_session ssh_new (void)
 creates a new ssh session
int ssh_options_copy (ssh_session src, ssh_session *dest)
 Duplicate the options of a session structure.
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)
 say the session it has an exception to catch on the file descriptor
void ssh_set_fd_toread (ssh_session session)
 say to the session it has data to read on the file descriptor without blocking
void ssh_set_fd_towrite (ssh_session session)
 say the session it may write to the file descriptor without blocking
void ssh_silent_disconnect (ssh_session session)
 disconnect impolitely from remote host by closing the socket.
int ssh_write_knownhost (ssh_session session)
 You generaly use it when ssh_is_server_known() answered SSH_SERVER_NOT_KNOWN.

Detailed Description

functions that manage a session


Function Documentation

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

connect to the ssh server

Parameters:
session ssh session
Returns:
SSH_OK on success, SSH_ERROR on error
See also:
ssh_new()
ssh_disconnect()

References ssh_init(), ssh_log(), and SSH_LOG_RARE.

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

References string_free(), and string_from_char().

Referenced by ssh_silent_disconnect().

int ssh_finalize ( void   ) 

Finalize and cleanup all libssh and cryptographic data structures.

This function should only be called once, at the end of the program!

Returns:
-1 in case of error
0 otherwise
void ssh_free ( ssh_session  session  ) 

deallocate a session handle

See also:
ssh_disconnect()
ssh_new()

References buffer_free(), channel_free(), and privatekey_free().

Referenced by ssh_new().

const char* ssh_get_disconnect_message ( ssh_session  session  ) 

get the disconnect message from the server

Parameters:
session ssh session
Returns:
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  ) 

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

recover the fd of connection

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

References string_to_char().

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:
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:
session The SSH session to use.
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()

References string_len().

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_handle_packets ( ssh_session  session  ) 
Warning:
I don't remember if this should be internal or not

Referenced by channel_poll().

int ssh_init ( void   ) 

initialize global cryptographic data structures.

This function should only be called once, at the beginning of the program, in the main thread. It may be omitted if your program is not multithreaded.

Returns:
0

Referenced by ssh_bind_listen(), and ssh_connect().

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:
session ssh session
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_options_set()
ssh_get_pubkey_hash()
Bug:
There is no current way to remove or modify an entry into the known host table.

References ssh_options_set().

ssh_session ssh_new ( void   ) 

creates a new ssh session

Returns:
new ssh_session pointer

References buffer_new(), and ssh_free().

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_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 option structure.
type The option type to set. This could be one of the following:
  • SSH_OPTIONS_HOST: The hostname or ip address to connect to (string).
  • SSH_OPTIONS_PORT: The port to connect to (integer).
  • SSH_OPTIONS_PORT_STR: The port to connect to (string).
  • 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. Don't forget to set the hostname as the hostname is used as a key in the known_host mechanism.
  • SSH_OPTIONS_USER: The username for authentication (string).

    If the value is NULL, the username is set to the default username.
  • SSH_OPTIONS_SSH_DIR: Set the ssh directory (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 (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 "%s" which will be replaced by the user home directory.
  • SSH_OPTIONS_IDENTITY: Set the identity file name (format string).

    By default identity, id_dsa and id_rsa are checked.

    The identity file used authenticate with public key. It may include "%s" which will be replaced by the user home directory.
  • SSH_OPTIONS_TIMEOUT: Set a timeout for the connection in seconds (integer).
  • SSH_OPTIONS_TIMEOUT_USEC: Set a timeout for the connection in micro seconds (integer).
  • SSH_OPTIONS_SSH1: Allow or deny the connection to SSH1 servers (integer).
  • SSH_OPTIONS_SSH2: Allow or deny the connection to SSH2 servers (integer).
  • SSH_OPTIONS_LOG_VERBOSITY: Set the session logging verbosity (integer).

    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
  • SSH_OPTIONS_LOG_VERBOSITY_STR: Set the session logging verbosity (string).

    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
      See the corresponding numbers in libssh.h.
  • SSH_OPTTIONS_AUTH_CALLBACK: Set a callback to use your own authentication function (function pointer).
  • SSH_OPTTIONS_AUTH_USERDATA: Set the user data passed to the authentication function (generic pointer).
  • SSH_OPTTIONS_LOG_CALLBACK: Set a callback to use your own logging function (function pointer).
  • SSH_OPTTIONS_LOG_USERDATA: Set the user data passed to the logging function (generic pointer).
  • SSH_OPTTIONS_STATUS_CALLBACK: Set a callback to show connection status in realtime (function pointer).

                            fn(void *arg, float status)
    

    During ssh_connect(), libssh will call the callback with status from 0.0 to 1.0.
  • SSH_OPTTIONS_STATUS_ARG: Set the status argument which should be passed to the status callback (generic pointer).
  • SSH_OPTIONS_CIPHERS_C_S: Set the symmetric cipher client to server (string, comma-separated list).
  • SSH_OPTIONS_CIPHERS_S_C: Set the symmetric cipher server to client (string, comma-separated list).
  • SSH_OPTIONS_COMPRESSION_C_S: Set the compression to use for client to server communication (string, "none" or "zlib").
  • SSH_OPTIONS_COMPRESSION_S_C: Set the compression to use for server to client communication (string, "none" or "zlib").
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.

Referenced by ssh_is_server_known(), ssh_try_publickey_from_file(), ssh_userauth_agent_pubkey(), ssh_userauth_kbdint(), ssh_userauth_none(), ssh_userauth_offer_pubkey(), ssh_userauth_password(), ssh_userauth_pubkey(), and ssh_write_knownhost().

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:
channels Arrays of channels pointers terminated by a NULL. It is never rewritten.
outchannels Arrays of same size that "channels", there is no need to initialize it.
maxfd Maximum +1 file descriptor from readfds.
readfds A fd_set of file descriptors to be select'ed for reading.
timeout A timeout for the select.
Returns:
-1 if an error occured. E_INTR 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)

References channel_poll().

void ssh_set_blocking ( ssh_session  session,
int  blocking 
)

set the session in blocking/nonblocking mode

Parameters:
session ssh session
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  ) 

say the session it has an exception to catch on the file descriptor

Parameters:
session ssh session
void ssh_set_fd_toread ( ssh_session  session  ) 

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

Parameters:
session ssh session
void ssh_set_fd_towrite ( ssh_session  session  ) 

say the session it may write to the file descriptor without blocking

Parameters:
session ssh session
void ssh_silent_disconnect ( ssh_session  session  ) 

disconnect impolitely from remote host by closing the socket.

Suitable if you forked and want to destroy this session.

Parameters:
session current ssh session

References ssh_disconnect().

int ssh_write_knownhost ( ssh_session  session  ) 

You generaly use it when ssh_is_server_known() answered SSH_SERVER_NOT_KNOWN.

write the current server as known in the known hosts file. This will create the known hosts file if it does not exist.

Parameters:
session ssh session
Returns:
0 on success, -1 on error

References ssh_dirname(), ssh_mkdir(), ssh_options_set(), and string_len().

Generated on Mon Jul 5 22:12:40 2010 for libssh by  doxygen 1.6.3