---
name: "ssh_session"
section: "3"
platform: "linux"
package: "libssh-2-doc"
version: "0.2+svn20070321-4"
release: "Debian 5.0 (Lenny)"
platforms: ["linux"]
url: "https://new.carta.tech/ssh_session"
---

# ssh\_session(3)

functions that manage a 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

\*

\*

## 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)](/select/2.md) 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)](/select/2.md)

**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