Linux Certif

Toute la documentation sur la certification Linux LPI

ssh_session

NAME

Ssh_session - functions that manage a session

Functions

int pubkey_get_hash (SSH_SESSION *session, unsigned char hash[MD5_DIGEST_LEN])

int ssh_connect (SSH_SESSION *session)
connect to the ssh server
void ssh_disconnect (SSH_SESSION *session)
disconnect from a session (client or server)
const char * ssh_get_disconnect_message (SSH_SESSION *session)
get the disconnect message from the server
int ssh_get_fd (SSH_SESSION *session)
recover the fd of connection
char * ssh_get_issue_banner (SSH_SESSION *session)
get the issue banner from the server
int ssh_get_pubkey_hash (SSH_SESSION *session, unsigned char hash[MD5_DIGEST_LEN])
get 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_is_server_known (SSH_SESSION *session)
test if the server is known
SSH_SESSION * ssh_new ()
creates a new ssh session
int ssh_select (CHANNEL **channels, CHANNEL **outchannels, int maxfd, fd_set *readfds, struct timeval *timeout)
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_set_options (SSH_SESSION *session, SSH_OPTIONS *options)
set the options for the current session
void ssh_silent_disconnect (SSH_SESSION *session)
disconnect impolitely from remote host
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

*

defgroup ssh_session

Function Documentation

int pubkey_get_hash (SSH_SESSION * session, unsigned char hash[MD5_DIGEST_LEN])

Deprecated

same as ssh_get_pubkey_hash()

int ssh_connect (SSH_SESSION * session)

connect to the ssh server

Parameters:

session ssh session

Returns:

0 on success, SSH_ERROR on error

See also:

ssh_new()
ssh_disconnect()

void ssh_disconnect (SSH_SESSION * session)

disconnect from a session (client or server)

Parameters:

session ssh session

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

int ssh_get_fd (SSH_SESSION * session)

recover the fd of connection

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

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, typicaly their right or the fact that they will be monitored

Parameters:

session ssh session

Returns:

NULL if there is no issue banner, else a string containing it.

int ssh_get_pubkey_hash (SSH_SESSION * session, unsigned char hash[MD5_DIGEST_LEN])

get the md5 hash of the server public key

Parameters:

session ssh session
hash destination for the md5 hash

Returns:

size of the hash in bytes

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

See also:

ssh_is_server_known()

int ssh_get_status (SSH_SESSION * session)

get session status

Parameters:

session ssh session

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 ssh session

Returns:

1 or 2, for ssh1 or ssh2

int ssh_handle_packets (SSH_SESSION * session)

Warning:

I don't remember if this should be internal or not

int ssh_is_server_known (SSH_SESSION * session)

test 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_ERROR : Some error happened 

See also:

ssh_options_set_wanted_algo()
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 ()

creates a new ssh session

Returns:

new ssh_session pointer

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

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 finished by an NULL. It is never rewritten/
outchannels arrays of same size that 'channels', it hasn't to be initialized
maxfd maximum +1 file descriptor from readfds
readfds an fd_set of file descriptors to be select'ed for reading
timeout a timeout for the select

See also:

select(2)

Returns:

-1 if an error occured. E_INTR if it was interrupted. In that case, just restart it.

Warning:

libssh is not threadsafe. 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()

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_set_options (SSH_SESSION * session, SSH_OPTIONS * options)

set the options for the current session

Parameters:

session ssh session
options options structure

See also:

ssh_new()
ssh_options_new()

void ssh_silent_disconnect (SSH_SESSION * session)

disconnect impolitely from remote host

Parameters:

session current ssh session

int ssh_write_knownhost (SSH_SESSION * session)

write the current server as known in the known hosts file

You generaly uses it when ssh_is_server_known() answered SSH_SERVER_NOT_KNOWN

Parameters:

session ssh session

Returns:

0 on success, -1 on error