<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.3.1"/>
<title>libssh: Chapter 1: A typical SSH session</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">libssh
 <span id="projectnumber">0.5.5</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.3.1 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">index</a></li><li class="navelem"><a class="el" href="libssh_tutorial.html">The Tutorial</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Chapter 1: A typical SSH session </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="ssh_session"></a>
A typical SSH session</h1>
<p>A SSH session goes through the following steps:</p>
<ul>
<li>Before connecting to the server, you can set up if you wish one or other server public key authentication, i.e. DSA or RSA. You can choose cryptographic algorithms you trust and compression algorithms if any. You must of course set up the hostname.</li>
</ul>
<ul>
<li>The connection is established. 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, using for instance the MD5 fingerprint or the known hosts file.</li>
</ul>
<ul>
<li>The client must authenticate: the classical ways are password, or public keys (from dsa and rsa key-pairs generated by openssh). If a SSH agent is running, it is possible to use it.</li>
</ul>
<ul>
<li>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 channels.</li>
</ul>
<ul>
<li>With the channel you opened, you can do several things:<ul>
<li>Execute a single command.</li>
<li>Open a shell. You may want to request a pseudo-terminal before.</li>
<li>Invoke the sftp subsystem to transfer files.</li>
<li>Invoke the scp subsystem to transfer files.</li>
<li>Invoke your own subsystem. This is outside the scope of this document, but can be done.</li>
</ul>
</li>
</ul>
<ul>
<li>When everything is finished, just close the channels, and then the connection.</li>
</ul>
<p>The sftp and scp subsystems use channels, but libssh hides them to the programmer. If you want to use those subsystems, instead of a channel, you'll usually open a "sftp session" or a "scp session".</p>
<h2><a class="anchor" id="setup"></a>
Creating the session and setting options</h2>
<p>The most important object in a SSH connection is the SSH session. In order to allocate a new SSH session, you use <a class="el" href="group__libssh__session.html#gaadadc0f9601547c30db7c4d62017d32c" title="Create a new ssh session.">ssh_new()</a>. Don't forget to always verify that the allocation successed. </p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <libssh/libssh.h></span> </div>
<div class="line"><span class="preprocessor">#include <stdlib.h></span></div>
<div class="line"></div>
<div class="line"><span class="keywordtype">int</span> main()</div>
<div class="line">{</div>
<div class="line"> ssh_session my_ssh_session = <a class="code" href="group__libssh__session.html#gaadadc0f9601547c30db7c4d62017d32c" title="Create a new ssh session.">ssh_new</a>();</div>
<div class="line"> <span class="keywordflow">if</span> (my_ssh_session == NULL)</div>
<div class="line"> exit(-1);</div>
<div class="line"> ...</div>
<div class="line"> <a class="code" href="group__libssh__session.html#gae5af27a98a7488e9f5ded6b37c274156" title="Deallocate a SSH session handle.">ssh_free</a>(my_ssh_session);</div>
<div class="line">}</div>
</div><!-- fragment --><p>libssh follows the allocate-it-deallocate-it pattern. Each object that you allocate using xxxxx_new() must be deallocated using xxxxx_free(). In this case, <a class="el" href="group__libssh__session.html#gaadadc0f9601547c30db7c4d62017d32c" title="Create a new ssh session.">ssh_new()</a> does the allocation and <a class="el" href="group__libssh__session.html#gae5af27a98a7488e9f5ded6b37c274156" title="Deallocate a SSH session handle.">ssh_free()</a> does the contrary.</p>
<p>The <a class="el" href="group__libssh__session.html#ga7a801b85800baa3f4e16f5b47db0a73d" title="This function can set all possible ssh options.">ssh_options_set()</a> function sets the options of the session. The most important options are:</p>
<ul>
<li>SSH_OPTIONS_HOST: the name of the host you want to connect to</li>
<li>SSH_OPTIONS_PORT: the used port (default is port 22)</li>
<li>SSH_OPTIONS_USER: the system user under which you want to connect</li>
<li>SSH_OPTIONS_LOG_VERBOSITY: the quantity of messages that are printed</li>
</ul>
<p>The complete list of options can be found in the documentation of <a class="el" href="group__libssh__session.html#ga7a801b85800baa3f4e16f5b47db0a73d" title="This function can set all possible ssh options.">ssh_options_set()</a>. The only mandatory option is SSH_OPTIONS_HOST. If you don't use SSH_OPTIONS_USER, the local username of your account will be used.</p>
<p>Here is a small example of how to use it:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <libssh/libssh.h></span> </div>
<div class="line"><span class="preprocessor">#include <stdlib.h></span></div>
<div class="line"></div>
<div class="line"><span class="keywordtype">int</span> main()</div>
<div class="line">{</div>
<div class="line"> ssh_session my_ssh_session;</div>
<div class="line"> <span class="keywordtype">int</span> verbosity = <a class="code" href="group__libssh__log.html#gga06fc87d81c62e9abb8790b6e5713c55ba75fa79e63947b66462db977d9b5ae27c" title="High level protocol information.">SSH_LOG_PROTOCOL</a>;</div>
<div class="line"> <span class="keywordtype">int</span> port = 22;</div>
<div class="line"></div>
<div class="line"> my_ssh_session = <a class="code" href="group__libssh__session.html#gaadadc0f9601547c30db7c4d62017d32c" title="Create a new ssh session.">ssh_new</a>();</div>
<div class="line"> <span class="keywordflow">if</span> (my_ssh_session == NULL)</div>
<div class="line"> exit(-1);</div>
<div class="line"></div>
<div class="line"> <a class="code" href="group__libssh__session.html#ga7a801b85800baa3f4e16f5b47db0a73d" title="This function can set all possible ssh options.">ssh_options_set</a>(my_ssh_session, SSH_OPTIONS_HOST, <span class="stringliteral">"localhost"</span>);</div>
<div class="line"> <a class="code" href="group__libssh__session.html#ga7a801b85800baa3f4e16f5b47db0a73d" title="This function can set all possible ssh options.">ssh_options_set</a>(my_ssh_session, SSH_OPTIONS_LOG_VERBOSITY, &verbosity);</div>
<div class="line"> <a class="code" href="group__libssh__session.html#ga7a801b85800baa3f4e16f5b47db0a73d" title="This function can set all possible ssh options.">ssh_options_set</a>(my_ssh_session, SSH_OPTIONS_PORT, &port);</div>
<div class="line"></div>
<div class="line"> ...</div>
<div class="line"></div>
<div class="line"> <a class="code" href="group__libssh__session.html#gae5af27a98a7488e9f5ded6b37c274156" title="Deallocate a SSH session handle.">ssh_free</a>(my_ssh_session);</div>
<div class="line">}</div>
</div><!-- fragment --><p>Please notice that all parameters are passed to <a class="el" href="group__libssh__session.html#ga7a801b85800baa3f4e16f5b47db0a73d" title="This function can set all possible ssh options.">ssh_options_set()</a> as pointers, even if you need to set an integer value.</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="group__libssh__session.html#gaadadc0f9601547c30db7c4d62017d32c" title="Create a new ssh session.">ssh_new</a> </dd>
<dd>
<a class="el" href="group__libssh__session.html#gae5af27a98a7488e9f5ded6b37c274156" title="Deallocate a SSH session handle.">ssh_free</a> </dd>
<dd>
<a class="el" href="group__libssh__session.html#ga7a801b85800baa3f4e16f5b47db0a73d" title="This function can set all possible ssh options.">ssh_options_set</a> </dd>
<dd>
<a class="el" href="group__libssh__session.html#ga82371e723260c7572ea061edecc2e9f1" title="Parse the ssh config file.">ssh_options_parse_config</a> </dd>
<dd>
<a class="el" href="group__libssh__session.html#gaead8cef1f39e785139bc510852ce1dff" title="Duplicate the options of a session structure.">ssh_options_copy</a> </dd>
<dd>
<a class="el" href="group__libssh__session.html#ga93f7f7159893f3ce62c9b178724eff75" title="Parse command line arguments.">ssh_options_getopt</a></dd></dl>
<h2><a class="anchor" id="connect"></a>
Connecting to the server</h2>
<p>Once all settings have been made, you can connect using <a class="el" href="group__libssh__session.html#ga032e07cbd8bc3f14cb2dd375db0b03d7" title="Connect to the ssh server.">ssh_connect()</a>. That function will return SSH_OK if the connection worked, SSH_ERROR otherwise.</p>
<p>You can get the English error string with <a class="el" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error()</a> in order to show the user what went wrong. Then, use <a class="el" href="group__libssh__session.html#ga0f048a4c0dbe02cfb7e9c5b6d0db0f27" title="Disconnect from a session (client or server).">ssh_disconnect()</a> when you want to stop the session.</p>
<p>Here's an example:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <libssh/libssh.h></span></div>
<div class="line"><span class="preprocessor">#include <stdlib.h></span></div>
<div class="line"><span class="preprocessor">#include <stdio.h></span> </div>
<div class="line"></div>
<div class="line"><span class="keywordtype">int</span> main()</div>
<div class="line">{</div>
<div class="line"> ssh_session my_ssh_session;</div>
<div class="line"> <span class="keywordtype">int</span> rc;</div>
<div class="line"></div>
<div class="line"> my_ssh_session = <a class="code" href="group__libssh__session.html#gaadadc0f9601547c30db7c4d62017d32c" title="Create a new ssh session.">ssh_new</a>();</div>
<div class="line"> <span class="keywordflow">if</span> (my_ssh_session == NULL)</div>
<div class="line"> exit(-1);</div>
<div class="line"></div>
<div class="line"> <a class="code" href="group__libssh__session.html#ga7a801b85800baa3f4e16f5b47db0a73d" title="This function can set all possible ssh options.">ssh_options_set</a>(my_ssh_session, SSH_OPTIONS_HOST, <span class="stringliteral">"localhost"</span>);</div>
<div class="line"></div>
<div class="line"> rc = <a class="code" href="group__libssh__session.html#ga032e07cbd8bc3f14cb2dd375db0b03d7" title="Connect to the ssh server.">ssh_connect</a>(my_ssh_session);</div>
<div class="line"> <span class="keywordflow">if</span> (rc != SSH_OK)</div>
<div class="line"> {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Error connecting to localhost: %s\n"</span>,</div>
<div class="line"> <a class="code" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error</a>(my_ssh_session));</div>
<div class="line"> exit(-1);</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> ...</div>
<div class="line"></div>
<div class="line"> <a class="code" href="group__libssh__session.html#ga0f048a4c0dbe02cfb7e9c5b6d0db0f27" title="Disconnect from a session (client or server).">ssh_disconnect</a>(my_ssh_session);</div>
<div class="line"> <a class="code" href="group__libssh__session.html#gae5af27a98a7488e9f5ded6b37c274156" title="Deallocate a SSH session handle.">ssh_free</a>(my_ssh_session);</div>
<div class="line">}</div>
</div><!-- fragment --><h2><a class="anchor" id="serverauth"></a>
Authenticating the server</h2>
<p>Once you're connected, the following step is mandatory: you must check that the server you just connected to is known and safe to use (remember, SSH is about security and authentication).</p>
<p>There are two ways of doing this:</p>
<ul>
<li>The first way (recommended) is to use the <a class="el" href="group__libssh__session.html#ga6f37e3d7bb6b938b44d6a34a76fdfa0b" title="Check if the server is known.">ssh_is_server_known()</a> function. This function will look into the known host file (~/.ssh/known_hosts on UNIX), look for the server hostname's pattern, and determine whether this host is present or not in the list.</li>
<li>The second way is to use <a class="el" href="group__libssh__session.html#gaf8ff0e2236d54d964a82f68d7323a741" title="Allocates a buffer with the MD5 hash of the server public key.">ssh_get_pubkey_hash()</a> to get a binary version of the public key hash value. You can then use your own database to check if this public key is known and secure.</li>
</ul>
<p>You can also use the <a class="el" href="group__libssh__session.html#gaf8ff0e2236d54d964a82f68d7323a741" title="Allocates a buffer with the MD5 hash of the server public key.">ssh_get_pubkey_hash()</a> to show the public key hash value to the user, in case he knows what the public key hash value is (some paranoid people write their public key hash values on paper before going abroad, just in case ...).</p>
<p>If the remote host is being used to for the first time, you can ask the user whether he/she trusts it. Once he/she concluded that the host is valid and worth being added in the known hosts file, you use <a class="el" href="group__libssh__session.html#gaf61a9cfdc40c76ffce9f9a8543755d36" title="Write the current server as known in the known hosts file.">ssh_write_knownhost()</a> to register it in the known hosts file, or any other way if you use your own database.</p>
<p>The following example is part of the examples suite available in the examples/ directory:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <errno.h></span></div>
<div class="line"><span class="preprocessor">#include <string.h></span></div>
<div class="line"></div>
<div class="line"><span class="keywordtype">int</span> verify_knownhost(ssh_session session)</div>
<div class="line">{</div>
<div class="line"> <span class="keywordtype">int</span> state, hlen;</div>
<div class="line"> <span class="keywordtype">unsigned</span> <span class="keywordtype">char</span> *hash = NULL;</div>
<div class="line"> <span class="keywordtype">char</span> *hexa;</div>
<div class="line"> <span class="keywordtype">char</span> buf[10];</div>
<div class="line"></div>
<div class="line"> state = <a class="code" href="group__libssh__session.html#ga6f37e3d7bb6b938b44d6a34a76fdfa0b" title="Check if the server is known.">ssh_is_server_known</a>(session);</div>
<div class="line"></div>
<div class="line"> hlen = <a class="code" href="group__libssh__session.html#gaf8ff0e2236d54d964a82f68d7323a741" title="Allocates a buffer with the MD5 hash of the server public key.">ssh_get_pubkey_hash</a>(session, &hash);</div>
<div class="line"> <span class="keywordflow">if</span> (hlen < 0)</div>
<div class="line"> <span class="keywordflow">return</span> -1;</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">switch</span> (state)</div>
<div class="line"> {</div>
<div class="line"> <span class="keywordflow">case</span> SSH_SERVER_KNOWN_OK:</div>
<div class="line"> <span class="keywordflow">break</span>; <span class="comment">/* ok */</span></div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">case</span> SSH_SERVER_KNOWN_CHANGED:</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Host key for server changed: it is now:\n"</span>);</div>
<div class="line"> ssh_print_hexa(<span class="stringliteral">"Public key hash"</span>, hash, hlen);</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"For security reasons, connection will be stopped\n"</span>);</div>
<div class="line"> free(hash);</div>
<div class="line"> <span class="keywordflow">return</span> -1;</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">case</span> SSH_SERVER_FOUND_OTHER:</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"The host key for this server was not found but an other"</span></div>
<div class="line"> <span class="stringliteral">"type of key exists.\n"</span>);</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"An attacker might change the default server key to"</span></div>
<div class="line"> <span class="stringliteral">"confuse your client into thinking the key does not exist\n"</span>);</div>
<div class="line"> free(hash);</div>
<div class="line"> <span class="keywordflow">return</span> -1;</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">case</span> SSH_SERVER_FILE_NOT_FOUND:</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Could not find known host file.\n"</span>);</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"If you accept the host key here, the file will be"</span></div>
<div class="line"> <span class="stringliteral">"automatically created.\n"</span>);</div>
<div class="line"> <span class="comment">/* fallback to SSH_SERVER_NOT_KNOWN behavior */</span></div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">case</span> SSH_SERVER_NOT_KNOWN:</div>
<div class="line"> hexa = ssh_get_hexa(hash, hlen);</div>
<div class="line"> fprintf(stderr,<span class="stringliteral">"The server is unknown. Do you trust the host key?\n"</span>);</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Public key hash: %s\n"</span>, hexa);</div>
<div class="line"> free(hexa);</div>
<div class="line"> <span class="keywordflow">if</span> (fgets(buf, <span class="keyword">sizeof</span>(buf), stdin) == NULL)</div>
<div class="line"> {</div>
<div class="line"> free(hash);</div>
<div class="line"> <span class="keywordflow">return</span> -1;</div>
<div class="line"> }</div>
<div class="line"> <span class="keywordflow">if</span> (strncasecmp(buf, <span class="stringliteral">"yes"</span>, 3) != 0)</div>
<div class="line"> {</div>
<div class="line"> free(hash);</div>
<div class="line"> <span class="keywordflow">return</span> -1;</div>
<div class="line"> }</div>
<div class="line"> <span class="keywordflow">if</span> (<a class="code" href="group__libssh__session.html#gaf61a9cfdc40c76ffce9f9a8543755d36" title="Write the current server as known in the known hosts file.">ssh_write_knownhost</a>(session) < 0)</div>
<div class="line"> {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Error %s\n"</span>, strerror(errno));</div>
<div class="line"> free(hash);</div>
<div class="line"> <span class="keywordflow">return</span> -1;</div>
<div class="line"> }</div>
<div class="line"> <span class="keywordflow">break</span>;</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">case</span> SSH_SERVER_ERROR:</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Error %s"</span>, <a class="code" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error</a>(session));</div>
<div class="line"> free(hash);</div>
<div class="line"> <span class="keywordflow">return</span> -1;</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> free(hash);</div>
<div class="line"> <span class="keywordflow">return</span> 0;</div>
<div class="line">}</div>
</div><!-- fragment --><dl class="section see"><dt>See Also</dt><dd><a class="el" href="group__libssh__session.html#ga032e07cbd8bc3f14cb2dd375db0b03d7" title="Connect to the ssh server.">ssh_connect</a> </dd>
<dd>
<a class="el" href="group__libssh__session.html#ga0f048a4c0dbe02cfb7e9c5b6d0db0f27" title="Disconnect from a session (client or server).">ssh_disconnect</a> </dd>
<dd>
<a class="el" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error</a> </dd>
<dd>
<a class="el" href="group__libssh__error.html#ga036433b7bf3d4ca94206253f58d136f9" title="Retrieve the error code from the last error.">ssh_get_error_code</a> </dd>
<dd>
<a class="el" href="group__libssh__session.html#gaf8ff0e2236d54d964a82f68d7323a741" title="Allocates a buffer with the MD5 hash of the server public key.">ssh_get_pubkey_hash</a> </dd>
<dd>
<a class="el" href="group__libssh__session.html#ga6f37e3d7bb6b938b44d6a34a76fdfa0b" title="Check if the server is known.">ssh_is_server_known</a> </dd>
<dd>
<a class="el" href="group__libssh__session.html#gaf61a9cfdc40c76ffce9f9a8543755d36" title="Write the current server as known in the known hosts file.">ssh_write_knownhost</a></dd></dl>
<h2><a class="anchor" id="auth"></a>
Authenticating the user</h2>
<p>The authentication process is the way a service provider can identify a user and verify his/her identity. The authorization process is about enabling the authenticated user the access to ressources. In SSH, the two concepts are linked. After authentication, the server can grant the user access to several ressources such as port forwarding, shell, sftp subsystem, and so on.</p>
<p>libssh supports several methods of authentication:</p>
<ul>
<li>"none" method. This method allows to get the available authentications methods. It also gives the server a chance to authenticate the user with just his/her login. Some very old hardware uses this feature to fallback the user on a "telnet over SSH" style of login.</li>
<li>password method. A password is sent to the server, which accepts it or not.</li>
<li>keyboard-interactive method. The server sends several challenges to the user, who must answer correctly. This makes possible the authentication via a codebook for instance ("give code at 23:R on page 3").</li>
<li>public key method. The host knows the public key of the user, and the user must prove he knows the associated private key. This can be done manually, or delegated to the SSH agent as we'll see later.</li>
</ul>
<p>All these methods can be combined. You can for instance force the user to authenticate with at least two of the authentication methods. In that case, one speaks of "Partial authentication". A partial authentication is a response from authentication functions stating that your credential was accepted, but yet another one is required to get in.</p>
<p>The example below shows an authentication with password:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <libssh/libssh.h></span></div>
<div class="line"><span class="preprocessor">#include <stdlib.h></span></div>
<div class="line"><span class="preprocessor">#include <stdio.h></span> </div>
<div class="line"></div>
<div class="line"><span class="keywordtype">int</span> main()</div>
<div class="line">{</div>
<div class="line"> ssh_session my_ssh_session;</div>
<div class="line"> <span class="keywordtype">int</span> rc;</div>
<div class="line"> <span class="keywordtype">char</span> *password;</div>
<div class="line"></div>
<div class="line"> <span class="comment">// Open session and set options</span></div>
<div class="line"> my_ssh_session = <a class="code" href="group__libssh__session.html#gaadadc0f9601547c30db7c4d62017d32c" title="Create a new ssh session.">ssh_new</a>();</div>
<div class="line"> <span class="keywordflow">if</span> (my_ssh_session == NULL)</div>
<div class="line"> exit(-1);</div>
<div class="line"> <a class="code" href="group__libssh__session.html#ga7a801b85800baa3f4e16f5b47db0a73d" title="This function can set all possible ssh options.">ssh_options_set</a>(my_ssh_session, SSH_OPTIONS_HOST, <span class="stringliteral">"localhost"</span>);</div>
<div class="line"></div>
<div class="line"> <span class="comment">// Connect to server</span></div>
<div class="line"> rc = <a class="code" href="group__libssh__session.html#ga032e07cbd8bc3f14cb2dd375db0b03d7" title="Connect to the ssh server.">ssh_connect</a>(my_ssh_session);</div>
<div class="line"> <span class="keywordflow">if</span> (rc != SSH_OK)</div>
<div class="line"> {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Error connecting to localhost: %s\n"</span>,</div>
<div class="line"> <a class="code" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error</a>(my_ssh_session));</div>
<div class="line"> <a class="code" href="group__libssh__session.html#gae5af27a98a7488e9f5ded6b37c274156" title="Deallocate a SSH session handle.">ssh_free</a>(my_ssh_session);</div>
<div class="line"> exit(-1);</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> <span class="comment">// Verify the server's identity</span></div>
<div class="line"> <span class="comment">// For the source code of verify_knowhost(), check previous example</span></div>
<div class="line"> <span class="keywordflow">if</span> (verify_knownhost(my_ssh_session) < 0)</div>
<div class="line"> {</div>
<div class="line"> <a class="code" href="group__libssh__session.html#ga0f048a4c0dbe02cfb7e9c5b6d0db0f27" title="Disconnect from a session (client or server).">ssh_disconnect</a>(my_ssh_session);</div>
<div class="line"> <a class="code" href="group__libssh__session.html#gae5af27a98a7488e9f5ded6b37c274156" title="Deallocate a SSH session handle.">ssh_free</a>(my_ssh_session);</div>
<div class="line"> exit(-1);</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> <span class="comment">// Authenticate ourselves</span></div>
<div class="line"> password = getpass(<span class="stringliteral">"Password: "</span>);</div>
<div class="line"> rc = <a class="code" href="group__libssh__auth.html#ga50c0c150f8c4703e7ee49b3e3e3ca215" title="Try to authenticate by password.">ssh_userauth_password</a>(my_ssh_session, NULL, password);</div>
<div class="line"> <span class="keywordflow">if</span> (rc != SSH_AUTH_SUCCESS)</div>
<div class="line"> {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Error authenticating with password: %s\n"</span>,</div>
<div class="line"> <a class="code" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error</a>(my_ssh_session));</div>
<div class="line"> <a class="code" href="group__libssh__session.html#ga0f048a4c0dbe02cfb7e9c5b6d0db0f27" title="Disconnect from a session (client or server).">ssh_disconnect</a>(my_ssh_session);</div>
<div class="line"> <a class="code" href="group__libssh__session.html#gae5af27a98a7488e9f5ded6b37c274156" title="Deallocate a SSH session handle.">ssh_free</a>(my_ssh_session);</div>
<div class="line"> exit(-1);</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> ...</div>
<div class="line"></div>
<div class="line"> <a class="code" href="group__libssh__session.html#ga0f048a4c0dbe02cfb7e9c5b6d0db0f27" title="Disconnect from a session (client or server).">ssh_disconnect</a>(my_ssh_session);</div>
<div class="line"> <a class="code" href="group__libssh__session.html#gae5af27a98a7488e9f5ded6b37c274156" title="Deallocate a SSH session handle.">ssh_free</a>(my_ssh_session);</div>
<div class="line">}</div>
</div><!-- fragment --><dl class="section see"><dt>See Also</dt><dd><a class="el" href="libssh_tutor_authentication.html#authentication_details">A deeper insight on authentication</a></dd></dl>
<h2><a class="anchor" id="using_ssh"></a>
Doing something</h2>
<p>At this point, the authenticity of both server and client is established. Time has come to take advantage of the many possibilities offered by the SSH protocol: execute a remote command, open remote shells, transfer files, forward ports, etc.</p>
<p>The example below shows how to execute a remote command:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> show_remote_processes(ssh_session session)</div>
<div class="line">{</div>
<div class="line"> ssh_channel channel;</div>
<div class="line"> <span class="keywordtype">int</span> rc;</div>
<div class="line"> <span class="keywordtype">char</span> buffer[256];</div>
<div class="line"> <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> nbytes;</div>
<div class="line"></div>
<div class="line"> channel = <a class="code" href="group__libssh__channel.html#gada8ccda7bf65165fe145d3096a252dcc" title="Allocate a new channel.">ssh_channel_new</a>(session);</div>
<div class="line"> <span class="keywordflow">if</span> (channel == NULL)</div>
<div class="line"> <span class="keywordflow">return</span> SSH_ERROR;</div>
<div class="line"></div>
<div class="line"> rc = <a class="code" href="group__libssh__channel.html#gaf051dd30d75bf6dc45d1a5088cf970bd" title="Open a session channel (suited for a shell, not TCP forwarding).">ssh_channel_open_session</a>(channel);</div>
<div class="line"> <span class="keywordflow">if</span> (rc != SSH_OK)</div>
<div class="line"> {</div>
<div class="line"> <a class="code" href="group__libssh__channel.html#gad1417f9eae8928fed20faafe2d9dbfff" title="Close and free a channel.">ssh_channel_free</a>(channel);</div>
<div class="line"> <span class="keywordflow">return</span> rc;</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> rc = <a class="code" href="group__libssh__channel.html#ga567d509183ade0a77190f390e2b5747d" title="Run a shell command without an interactive shell.">ssh_channel_request_exec</a>(channel, <span class="stringliteral">"ps aux"</span>);</div>
<div class="line"> <span class="keywordflow">if</span> (rc != SSH_OK)</div>
<div class="line"> {</div>
<div class="line"> <a class="code" href="group__libssh__channel.html#ga238f07e0455456a5bfd8a49ead917732" title="Close a channel.">ssh_channel_close</a>(channel);</div>
<div class="line"> <a class="code" href="group__libssh__channel.html#gad1417f9eae8928fed20faafe2d9dbfff" title="Close and free a channel.">ssh_channel_free</a>(channel);</div>
<div class="line"> <span class="keywordflow">return</span> rc;</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> nbytes = <a class="code" href="group__libssh__channel.html#gac92381c4c5d4a7eab35f6e84686f033d" title="Reads data from a channel.">ssh_channel_read</a>(channel, buffer, <span class="keyword">sizeof</span>(buffer), 0);</div>
<div class="line"> <span class="keywordflow">while</span> (nbytes > 0)</div>
<div class="line"> {</div>
<div class="line"> <span class="keywordflow">if</span> (write(1, buffer, nbytes) != nbytes)</div>
<div class="line"> {</div>
<div class="line"> <a class="code" href="group__libssh__channel.html#ga238f07e0455456a5bfd8a49ead917732" title="Close a channel.">ssh_channel_close</a>(channel);</div>
<div class="line"> <a class="code" href="group__libssh__channel.html#gad1417f9eae8928fed20faafe2d9dbfff" title="Close and free a channel.">ssh_channel_free</a>(channel);</div>
<div class="line"> <span class="keywordflow">return</span> SSH_ERROR;</div>
<div class="line"> }</div>
<div class="line"> nbytes = <a class="code" href="group__libssh__channel.html#gac92381c4c5d4a7eab35f6e84686f033d" title="Reads data from a channel.">ssh_channel_read</a>(channel, buffer, <span class="keyword">sizeof</span>(buffer), 0);</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"> <span class="keywordflow">if</span> (nbytes < 0)</div>
<div class="line"> {</div>
<div class="line"> <a class="code" href="group__libssh__channel.html#ga238f07e0455456a5bfd8a49ead917732" title="Close a channel.">ssh_channel_close</a>(channel);</div>
<div class="line"> <a class="code" href="group__libssh__channel.html#gad1417f9eae8928fed20faafe2d9dbfff" title="Close and free a channel.">ssh_channel_free</a>(channel);</div>
<div class="line"> <span class="keywordflow">return</span> SSH_ERROR;</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> <a class="code" href="group__libssh__channel.html#ga072f82fdf3e50514f747653af2c99004" title="Send an end of file on the channel.">ssh_channel_send_eof</a>(channel);</div>
<div class="line"> <a class="code" href="group__libssh__channel.html#ga238f07e0455456a5bfd8a49ead917732" title="Close a channel.">ssh_channel_close</a>(channel);</div>
<div class="line"> <a class="code" href="group__libssh__channel.html#gad1417f9eae8928fed20faafe2d9dbfff" title="Close and free a channel.">ssh_channel_free</a>(channel);</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">return</span> SSH_OK;</div>
<div class="line">}</div>
</div><!-- fragment --><dl class="section see"><dt>See Also</dt><dd><a class="el" href="libssh_tutor_shell.html#opening_shell">Opening a remote shell</a> </dd>
<dd>
<a class="el" href="libssh_tutor_command.html#remote_command">Passing a remote command</a> </dd>
<dd>
<a class="el" href="libssh_tutor_sftp.html#sftp_subsystem">The SFTP subsystem</a> </dd>
<dd>
<a class="el" href="libssh_tutor_scp.html#scp_subsystem">The SCP subsystem</a></dd></dl>
<h2><a class="anchor" id="errors"></a>
Handling the errors</h2>
<p>All the libssh functions which return an error value also set an English error message describing the problem.</p>
<p>Error values are typically SSH_ERROR for integer values, or NULL for pointers.</p>
<p>The function <a class="el" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error()</a> returns a pointer to the static error message.</p>
<p>ssh_error_code() returns the error code number : SSH_NO_ERROR, SSH_REQUEST_DENIED, SSH_INVALID_REQUEST, SSH_CONNECTION_LOST, SSH_FATAL, or 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, ...). 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.</p>
<p>Most of time, the error returned are SSH_FATAL, but some functions (generaly the ssh_request_xxx ones) may fail because of server denying request. In these cases, SSH_REQUEST_DENIED is returned.</p>
<p><a class="el" href="group__libssh__error.html#ga9241586665bf21f823806473fc386258" title="Retrieve the error text message from the last error.">ssh_get_error()</a> and <a class="el" href="group__libssh__error.html#ga036433b7bf3d4ca94206253f58d136f9" title="Retrieve the error code from the last error.">ssh_get_error_code()</a> take a ssh_session as a parameter. That's for thread safety, error messages that can be attached to a session aren't static anymore. Any error that happens during ssh_options_xxx() or <a class="el" href="group__libssh__session.html#ga032e07cbd8bc3f14cb2dd375db0b03d7" title="Connect to the ssh server.">ssh_connect()</a> (i.e., outside of any session) can be retrieved by giving NULL as argument.</p>
<p>The SFTP subsystem has its own error codes, in addition to libssh ones. </p>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.3.1
</small></address>
</body>
</html>
