Before inserting ssh hooks into your programs, you must know some basics about the ssh protocol, and understand why the ssh library must implement them.
Lot of the protocols specifications are hidden by the ssh library API (of course !) but some still needs an attention from the end-user programmer.
Note that libssh is still an alpha product, and the API may vary from one version to another. The only guess I can make is that the API won't radically change.
The SSH protocol was designed for some goals which I resume here :
-Privacy of data
-Security
-Authentication of the server
-Authentication of the client.
The client MUST be sure who's speaking to before entering into any authentication way. That's where the end programmer must ensure the given fingerprints *are* from the legitimate server. A ssh connection must follow the following steps:

1- Before connecting the socket, you can set up if you wish one or other server public key authentication ie. DSA or RSA. You can choose cryptographic algorithms you trust and compression algorithms if any.
2- The connection is made. A secure handshake is made, and resulting from it, a public key from the server is gained. You MUST verify that the public key is legitimate.
3- The client must authenticate : the two implemented ways are password, and public keys (from dsa and rsa key-pairs generated by openssh). It is harmless to authenticate to a fake server with these keys because the protocol ensures the data you sign can't be used twice. It just avoids man-in-the-middle attacks.
4- Now that the user has been authenticated, you must open one or several channels. channels are different subways for information into a single ssh connection. Each channel has a standard stream (stdout) and an error stream (stderr). You can theoretically open an infinity of channel.
5- With the channel you opened, you can do several things :
-Open a shell. You may want to request a pseudo virtual terminal before
-Execute a command. The virtual terminal is usable, too
-Invoke the sftp subsystem. (look at chapter 6)
-invoke your own subsystem. This is out the scope of this document but it is easy to do.
6- When everything is finished, just close the channels, and then the connection.

At every place, a function which returns an error code (typically -1 for int values, NULL for pointers) also sets an error message and an error code. I high-lined the main steps, now that's you to follow them :)

The options mechanism will change during updates of the library, but the functions which exists now will certainly be kept.

The ssh system needs to know the preferences of the user, the trust into one or another algorithm and such. More important informations have to be given before connecting : the host name of the server, the port (if non default), the binding address, the default username, ...
The options structure is given to a ssh_connect function, then this option structure is used again and again by the ssh implementation. you shall not free it manually, and you shall not share it with multiple sessions.
Two ways are given for setting the options : the easy one (of course !) and the long-but-accurate one.

Lot of ssh options in fact come from the command line of the program...
you could parse them and then use the long way for every argument, but libssh has a mechanism to do that for you, automatically.

this function will return you a new options pointer based on the arguments you give in parameters.
better, they clean the argv array from used parameters so you can use them after in your own program
the function will return NULL if some problem is appearing.
As a matter of portability for you own programs, the hostname isn't always
the first argument from the command line, so the single arguments (not preceded by a -something) won't be parsed.
cfr the options_set_user() function in the next part for more informations about it.

This function returns an empty but initialized option structure pointer.
The structure is freed by ssh_disconnect described later, so don't use the existing function options_free() (it's an internal function).
So : use it only for one ssh_connect(), never free it.

If you need to replicate an option object before using it, use this function.

The following functions are all of the following form :
the something parameters are always internaly copied, so you don't have to strdup them.
some return eather 0 or -1, in which case an error message appears in the error functions, others never fail (return void)
the error codes and descriptions for these functions are recoverable throught ssh_get_error(NULL);
Passing an option structure, a ssh macro for the method, and a list of allowed parameters indicates libssh you want to use these.
The macros are :
KEX_ALGO
KEX_HOSTKEY Server public key type expected
KEX_CRYPT_C_S 2 Cryptographic algorithm client->server
KEX_CRYPT_S_C 3 Cryptographic algorithm server->client
KEX_MAC_C_S 4
KEX_MAC_S_C 5
KEX_COMP_C_S 6 Compression method for the stream ("zlib" or "none"), client to server
KEX_COMP_S_C 7 Compression method for the stream ("zlib" or "none"), server to client
KEX_LANG_C_S 8
KEX_LANG_S_C 9

Currently, only KEX_HOSTKEY and ,KEX_CRYPT_C_S,S_C, KEX_COMP_C_S and S_C work as expected. the list is a comma separated string of prefered algorithms/methods, in order of preference.

return value:
0 if the option is valid, -1 else.
An error is set in that case.

this function sets the server port. this function sets the hostname of the server. It also supports "user@hostname" syntax in which case the user options is set too. permits you to specify an opened file descriptor you've opened yourself.
It's a good way of bypassing the internal FD opening in libssh, but there are things you should take care of :
-The file descriptor should be returned to libssh without nonblocking settings
-If you wish to use is_server_known() You should also set options_set_host... Otherwise libssh won't have any mean of certifying the server is known or not.

this function allows you to set the binding address, in case your computer has multiple IP or interfaces. it supports both hostnames and IP's

sets username for authenticating in this session.

sets the timeout for connecting to the socket. It does not include a timeout for the name resolving or handshake.

this function sets the .ssh/ directory used by libssh. You may use a %s which will be replaced by the home directory of the user. NEVER accept parameters others than the user's one, they may contain format strings which are a security hole if a malicious agent gives it.

same than options_set_ssh_dir() for known_hosts file.

same than upper for the identity file (they come by pair, the one asked is the file without the .pub suffix)

Because more and more developpers use libssh with GUI, I've added this function to make the ssh_connect function more interactive. This permits to set a callback of the form with status going from 0 to 1 during ssh_connect. The callback won't ever be called after the connection is made.

The API provides an abstract data type, SSH_SESSION, which describes the connection to one particular server. You can make several connections to different servers under the same process because of this structure.

This function returns a handle on the newly connection. This function expects to have a pre-set options structure.
It returns NULL in case of error, in which case you can look at error messages for more informations.

This function sends a polite disconnect message, and does clean the session.
This is the proper way of finishing a ssh connection.

This function places the MD5 hash of the server public key into the hash array.
It's IMPORTANT to verify it matches the previous known value. One server always have the same hash. No other server/attacker can emulate it (or it'd be caught by the public key verification procedure automatically made by libssh).
You can skip this step if you correctly handle is_server_known()

Checks the user's known host file to look for a previous connection to the specified server. Return values:
SSH_SERVER_KNOWN_OK : the host is known and the key has not changed
SSH_SERVER_KNOWN_CHANGED : The host's key has changed. Either you are under an active attack or the key changed. The API doesn't give any way to modify the key in known hosts yet. I Urge end developers to WARN the user about the possibility of an attack.
SSH_SERVER_FOUND_OTHER: The host gave us a public key of one type, which does not exist yet in our known host file, but there is an other type of key which is know.
IE server sent a DSA key and we had a RSA key.
Be carreful it's a possible attack (coder should use option_set_wanted_method() to specify which key to use).
SSH_SERVER_NOT_KNOWN: the server is unknown in known hosts. Possible reasons : case not matching, alias, ... In any case the user MUST confirm the Md5 hash is correct.
SSH_SERVER_ERROR : Some error happened while opening known host file.

write the current connected host as known in the known host file. returns a negative value if something went wrong. You generaly use it when ssh_is_server_known returned SSH_SERVER_NOT_KNOWN.

deprecated but left for binary compatibility (will be removed in newer versions).

The ssh library supports the two most used authentication methods from SSH. In every function, there is a "username" argument. If null is given instead, the server will use the default username (which is guessed from what you gave to options_set_user or options_set_hostname or even the local user running the code).
Authentication methods :

A) Public keys

The public key is the only method which does not compromise your key if the remote host has been compromised (the server can't do anything more than getting your public key). This is not the case of a password authentication (the server can get your plaintext password).
Libssh is obviously fully compatible with the openssh public and private keys.
The things go this way : you scan a list of files which contain public keys.
For each key, you send it to ssh server until the server acknowledges a key (a key it knows). Then, you get the private key for this key and send a message proving you own that private key.
Here again, two ways for the public key authentication... the easy and the complicated one.

easy way:

This function will try the most common places for finding the public and private keys (your home directory) or eventualy the identity files asked by the options_set_identity() function.
The return values are :
SSH_AUTH_ERROR : some serious error happened during authentication
SSH_AUTH_DENIED : no key matched
SSH_AUTH_SUCCESS : you are now authenticated
SSH_AUTH_PARTIAL : some key matched but you still have to give an other mean of authentication (like password).

peanful way:

there are three steps : you get a public key, you ask the server if the key matches a known one, if true, you get the private key and authenticate with it.
will return an handle on a public key. if you give a pointer to an int, a symbolic value will be placed there. Do it because you need it in next step.

this function will offer a public key to the server. SSH_AUTH_SUCCESS is returned if the key is accepted (in which case you'll want to get the private key), SSH_AUTH_DENIED otherwise.
Still watch for SSH_AUTH_ERROR as connection problems might happen.
in case of SSH_AUTH_SUCCESS,
will get the privatekey from the filename previously set by publickey_from_next_file(). You can call it with a passphrase for unlocking the key. If passphrase==NULL, the default prompt will be used.
The function returns NULL if the private key wasn't opened (ie bad passphrase or missing file).

Will try to authenticate using the public and private key. It shall return SSH_AUTH_SUCCESS if you are authenticated, SSH_AUTH_ERROR, SSH_AUTH_DENIED or SSH_AUTH_PARTIAL depending of return condition.
each public key (of type STRING) must be freed with the libc "free" function.
The private key must be freed with private_key_free(PRIVATE_KEY *) which will clean the memory before (don't worry about passphrase leaking).

B) Password

Will return SSH_AUTH_SUCCESS if the password matched, one of other constants otherwise. It's your work to ask the password and to free it in a secure manner.

C) Keyboard-interactive

This is the main keyboard-interactive function. It will return SSH_AUTH_SUCCESS,SSH_AUTH_DENIED, SSH_AUTH_PARTIAL, SSH_AUTH_ERROR depending on the result of the request.
The keyboard-interactive authentication method of SSH2 is a feature which permits the server to ask a certain number of questions in an interactive manner to the client, until it decides to accept or deny the login.
To begin, you call this function (you can omit user if it was set previously and omit submethods - instead you know what you do - just put them to NULL) and store the answer. If the answer is SSH_AUTH_INFO, it means the server has sent a few questions to ask your user, which you can retrieve with the following functions. Then, set the answers and call back ssh_userauth_kbdint with same arguments. It may again ask a few other questions etc. until you get an other SSH_AUTH code than SSH_AUTH_INFO.
Few remarks :
-Even the first call can return SSH_AUTH_DENIED or SSH_AUTH_SUCCESS.
-The server can send an empty question set (this is the default behavior on my system) after you have sent the answers to the first questions. you must still parse the answer, it might contain some message from the server saying hello or such things. Just call ssh_userauth_kbdint() once more

After you called ssh_userauth_kbdint and got SSH_AUTH_INFO, the session contains a few questions (or prompts) from the server. This function returns the number of prompts and answers.
It could be zero, in which case you must act as said previously.
this functions returns the "name" of the message block. The meaning is explained later.
This function returns a pointer that stays valid until the next ssh_userauth_kbdint() call and must not be freed.
this functions returns the "instruction" of the message block. The meaning is explained later.
This function returns a pointer that stays valid until the next ssh_userauth_kbdint() call and must not be freed.
This functions returns a pointer to the nth prompt. The character pointed by echo, if different from null, will contain a boolean value after the call, which means that the user prompt must be echoed or not.
zero means that the echo is Off (like for a password prompt).
any other value means the echo is on.
This function returns a pointer that stays valid until the next ssh_userauth_kbdint() call and must not be freed.
This function sets the ith answer. The string you give will be duplicated, and this copy will be discarded once it is no longer necessary.
care must be taken so you discard the content of the original string after this function call.

A little note about how to use the informations from keyboard-interactive authentication

The words from the original drafts explain everything

D) "none"

In fact this mode only serve to get the list of supported authentications.
however, it also serves to get the banner message from the server, if any.
You should firstly try this method, at least for getting the banner, then to enter if there is no password at all.
if the account has no password (and the server is configured to let you pass), the function might answer SSH_AUTH_SUCCESS. That's why ssh_auth_autopubkey already calls it for you.

if during authentication, the server has given a banner, you can get it this way. the function returns NULL if no banner exists, and you have to free the returned pointer.

Maybe you want to use the sftp subsystem : all this is done for you, you better read at the end of the paper how to use the sftp functions.
You probably want to open one or more shells, or call one or more programs.
So you need a channel.
This is an handler to a channel object. it describes your channel.
This will open a channel for use into a session (which can be used for executing a command or a shell. Not for tcp forwarding).
The function returns NULL if for a reason or another the channel can't be opened.
CHANNEL *open_session_channel(...) is deprecated and should not be used in future applications.

Ask the server to tunnel a TCP connection. The server will connect to remotehost:remoteport and libssh will return an handle to the channel if it is allowed.
Otherwise, NULL will be returned. sourcehost and localport are generaly used in message debugging purpose and have no effect on the result.

When you've finished with your channel, you may send an EOF message and then close it :
sends an end of file into channel. It doesn't close the channel and you can still read it.

closes and destroy the channel.
sends an EOF and close the channel. (if you don't know what to do, use channel_free). It doesn't free the channel.

Ask the server to set the "name" environment variable to "value". For security reasons, some variables won't be accepted by the server. It returns 0 otherwise.

ask the server to allocate a pseudo terminal for the current channel.
the function returns 0 on success.

ask the server to allocate a pty. The terminal parameter is the type of pty (vt100,xterm,...), cols and rows are the size of the new terminal (80x24 by example).

changes the window size (terminal) of the current session;

This function requests a shell. After its success, a shell is running at the other side of the channel.

run a shell command without an interactive shell, ie $SHELL -c "command".
returns 0 on success.

You might ask the server to open a subsystem for you. this is done this way : There are some functions used to manipulate the channels :

writes len bytes of data into the channel. It returns the number of bytes written. The current implementation is a blocking write of the complete data buffer, but it may vary.

It makes a blocking read on the channel, of "bytes" bytes and returns the result into an allocated buffer you passed in. (with buffer_new()).
it will read on stderr, if is_stderr is set.
The function might read less bytes than "bytes" variable if an End of File happened. Otherwise, the function will always block reading until "bytes" bytes are read.
with "bytes"=0, channel_read() will read the current state of the read buffer, but will read at least one byte (and block if nothing is available, except EOF case).
You don't need to free and allocate a new buffer each time you call this function, just pass the same object each time.
look at the buffer_ functions further for the correct way of retrieving the data.

Non-blocking read on channel, at most len bytes of data are read. Returns 0 if EOF or if no data available.

returns 0 if the channel has been closed by remote host, something else otherwise.

This nonblocking function returns the number of bytes immediatly available for reading on the channel and stdin/stderr.

More interesting, if you are going to do channel multiplexing, this function is for you :

channels is an array of channel pointers, finished by a NULL pointer.
It can be used ever and ever, as it is never written.
outchannels is an array of size at least greater or equal to "channels".
It hasn't to be initialized.
maxfd is the maximum file descriptor from your own filedescriptors.
readfds is a pointer to a fd_set structure, like in the original select implementation (man select).
the struct timeval *timeout has the same meaning than in select(2) (man select).
There is no support for writing or special events as in select(2) yet.
The function returns -1 if an error occured, or SSH_EINTR if select was interrupted by a syscall. This is not an error, you may restart the function.
note about signals: libssh is not threadsafe, and most functions are not reetrant when using the same data structures : it means you *cannot* do anything with a channel from a ssh session passed to ssh_select during a signal.
take a look at sample.c on how to bypass that limitation.
the function works this way : it returns in the readfds the filedescriptors which have data ready for reading (the given filedescriptors have a greatest priority).
Then, if no file descriptor can be read, the function looks for every channel from the array to get a channel with data bufferized. If nothing is available, it waits for activity on any channel/file descriptor and returns immediatly, or waits until timeout.
You will find the channels that can be read in the outchannels array (finished by NULL) and the filedescriptors in your fd_set (man FD_ISSET).
this is the "heart" of your main loop.

The BUFFER object.

Reading is done through the BUFFER object. here is the public interface :
creates a buffer object.

returns a pointer to the begining of buffer.

returns buffer's data size.

destoys the buffer.

How to use the buffer system when you've read something:
I've seen people doing such code:
The correct way of doing this: Do not expect the buffer to be null-terminated. Don't access the internal structure of buffer. Check the sizes before copying.

SFTP is a secure implementation of a file transfer protocol. The current implemented version is 3. All functions aren't implemented yet but the most important are.

A) Opening the session

The former returns a SFTP_SESSION handle. It returns NULL if things didn't work as expected.
sftp_init makes some initialisation work. It returns 0 if things went right. Both of them must be called.

B) Opening and reading a directory

opens a directory for file listing. Returns NULL in error case.

This function reads one file attribute from an opened directory. It returns NULL if the directory is EOF, or if something wrong happened.

When a sftp_readdir() returned NULL, you can use this function to tell if an EOF occured. the function returns 0 if no EOF occured.

You have to free any SFTP_ATTRIBUTE structure given by an other function with it.

closes an opened directory. returns 0 when no error occured.

C) Opening, reading, writing files

Opens a file. The access flags are the same than the stdio flags.
see open(2) for more details.
attr are the wanted attributes for the new file. If you supply NULL, default values will be used.
rem: more work is going on parsing/making the attributes structure

read on a file. Works as the fread() function. It is blocking by default but you can change the default behaviour with sftp_file_set_nonblocking().

sets the file non blocking. reads on this file won't ever block. You can't detect end of files this way.
*** TODO more work going there for EOF ****

restore the default setting of sftp_read.

works as fwrite() function. It is a blocking write.

seek into the file for reading/writing at an other place.

returns the current offset (both writing and reading) into the opened file.

same as sftp_seek(file,0);

closes a file handle. returns 0 in no error case.

deletes a file.


deletes a directory.

makes a directory, with the given attributes. You can't pass NULL for attr and hope it works.

changes the name of a file or directory.

changes the attributes of a file or directory.

gives the canonicalized form of some path. You have to free the pointer given in return.
(returns NULL if error).

(a function to make proper SFTP_ATTRIBUTES structures is on the way )

D) Closing the session

it closes the sftp channel and subsystem.

When some function returns an error code, it's allways possible to get an english message describing the problem. the function ssh_get_error() returns a pointer to the static error buffer.
ssh_error_code() returns the error code number. it's declared as an enum:
SSH_NO_ERROR, SSH_REQUEST_DENIED, SSH_INVALID_REQUEST, SSH_CONNECTION_LOST, SSH_FATAL, SSH_INVALID_DATA.

SSH_REQUEST_DENIED means the ssh server refused your request but the situation is recoverable. the others mean something happened to the connection (some encryption problems, server problems, library bug, ...).
SSH_INVALID_REQUEST means the library got some garbage from server. (But might be recoverable).
SSH_FATAL means the connection has an important problem and isn't probably recoverable.

Most of time, the error returned are SSH_FATAL, but some functions (generaly the ssh_request_* ones) may fail because of server denying request. In these cases, SSH_REQUEST_DENIED is returned.

You'll see in the prototype SSH_SESSION *session. That's because for thread safety, error messages that can be attached to a session aren't static anymore. So, any error that could happen during ssh_getopt(), options_* or ssh_connect() will be retreavable giving NULL as argument.

returns a pointer to a static message error from the given session. No message freeing is needed.

returns the error code that last happened along with the message.

I made this library because nothing in the Open source or free software community was existing yet. This project is a very personnal one as it's the first "useful" thing I ever wrote. I hope it fits your needs, but remember the experimental state of libssh : if something doesn't work, please mail me. If something lacks, please ask for it. If something stinks, please write a patch and send it !