phpseclib/net.html (e36c40f) - vroom360

net.html

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!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/html; charset=UTF-8" /><title>Chapter 5. Networking</title><link rel="stylesheet" href="docbook.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><link rel="start" href="index.html" title="PHP Secure Communications Library" /><link rel="up" href="index.html" title="PHP Secure Communications Library" /><link rel="prev" href="misc_crypt.html" title="Chapter 4. Miscellaneous Cryptography" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 5. Networking</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="misc_crypt.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> </td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="net"></a>Chapter 5. Networking</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="net.html#net_ssh">5.1. Net_SSH</a></span></dt><dd><dl><dt><span class="section"><a href="net.html#net_ssh_dependencies">5.1.1. Dependencies</a></span></dt><dt><span class="section"><a href="net.html#net_ssh_ssh2">5.1.2. Net_SSH2 Examples</a></span></dt><dt><span class="section"><a href="net.html#net_ssh_host_key_verify">5.1.3. Host Key Verification</a></span></dt><dt><span class="section"><a href="net.html#net_ssh_interactive">5.1.4. read() / write() vs. exec()</a></span></dt><dt><span class="section"><a href="net.html#net_ssh_sudo">5.1.5. sudo with read() / write()</a></span></dt><dt><span class="section"><a href="net.html#net_ssh_exec">5.1.6. SSH-1's exec() vs. SSH-2's exec()</a></span></dt><dt><span class="section"><a href="net.html#net_ssh_successive">5.1.7. Successive calls to SSH-2's exec()</a></span></dt><dt><span class="section"><a href="net.html#net_ssh_debug">5.1.8. Debugging SSH-2</a></span></dt></dl></dd><dt><span class="section"><a href="net.html#net_sftp">5.2. Net_SFTP</a></span></dt><dd><dl><dt><span class="section"><a href="net.html#net_sftp_intro">5.2.1. Introduction</a></span></dt><dt><span class="section"><a href="net.html#net_sftp_dependencies">5.2.2. Dependencies</a></span></dt><dt><span class="section"><a href="net.html#net_sftp_example">5.2.3. Net_SFTP Example</a></span></dt><dt><span class="section"><a href="net.html#net_sftp_put">5.2.4. put($remote_file, $data [, $mode])</a></span></dt><dt><span class="section"><a href="net.html#net_sftp_get">5.2.5. get($remote_file [, $local_file])</a></span></dt><dt><span class="section"><a href="net.html#net_sftp_pwd">5.2.6. pwd(), chdir(), mkdir() and rmdir()</a></span></dt><dt><span class="section"><a href="net.html#net_sftp_chmod">5.2.7. chmod() and size()</a></span></dt><dt><span class="section"><a href="net.html#net_sftp_nlist">5.2.8. nlist() and rawlist()</a></span></dt><dt><span class="section"><a href="net.html#net_sftp_stat">5.2.9. stat() and lstat()</a></span></dt><dt><span class="section"><a href="net.html#net_sftp_delete">5.2.10. delete() and rename()</a></span></dt><dt><span class="section"><a href="net.html#net_sftp_debug">5.2.11. Debugging SFTP</a></span></dt></dl></dd></dl></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="net_ssh"></a>5.1. Net_SSH</h2></div></div></div><p>
                The Net_SSH1 and Net_SSH2 libraries have, for the most part, an identical API.  Some functions, however, do behave differently.
            </p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="net_ssh_dependencies"></a>5.1.1. Dependencies</h3></div></div></div><p>
                    Net_SSH1/2 require, minimally, Math/BigInteger.php, Crypt/*.php, and PHP/Compat/Function/*.php.  Net_SSH1 requires PHP 4.0.0.  Net_SSH2 requires PHP 4.3.0 due to it's use of <a class="ulink" href="http://php.net/function.sha1" target="_top">sha1()</a>.
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="net_ssh_ssh2"></a>5.1.2. Net_SSH2 Examples</h3></div></div></div><pre class="programlisting">&lt;?php
include('Net/SSH2.php');

$ssh = new Net_SSH2('www.domain.tld');
if (!$ssh-&gt;login('username', 'password')) {
    exit('Login Failed');
}

echo $ssh-&gt;exec('pwd');
echo $ssh-&gt;exec('ls -la');
?&gt;</pre><pre class="programlisting">&lt;?php
include('Net/SSH2.php');

$key = new Crypt_RSA();
//$key-&gt;setPassword('whatever');
$key-&gt;loadKey(file_get_contents('privatekey'));

$ssh = new Net_SSH2('www.domain.tld');
if (!$ssh-&gt;login('username', $key)) {
    exit('Login Failed');
}

echo $ssh-&gt;read('username@username:~$');
$ssh-&gt;write("ls -la\n");
echo $ssh-&gt;read('username@username:~$');
?&gt;</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="net_ssh_host_key_verify"></a>5.1.3. Host Key Verification</h3></div></div></div><p>
                    SSH protects itself against active eavesdroppers by providing a host key.  The first time you connect the host key is supposed to be cached in some manner.  On subsequent connections, the host key being used for this connection should be checked against the cached host key.  If they match, it's the same server.  If not, it's a different one.
                </p><p>
                    In SSH-1, <code class="code">getHostKeyPublicModulus()</code> and <code class="code">getHostKeyPublicExponent()</code> will provide you with the host key.  In SSH-2, <code class="code">getServerPublicHostKey()</code> gets you the key.
                </p><p>
                    The Net_SSH1 and Net_SSH2 examples omit the key verification stage for brevity.  Also, depending on the context in which this library is used, it may even be unnecessary.  For example, if you're connecting to www.example.com:22 from www.example.com:80, eavesdroppers are not something you need to worry about.
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="net_ssh_interactive"></a>5.1.4. read() / write() vs. exec()</h3></div></div></div><p>
                    read() works a lot like <a class="ulink" href="http://en.wikipedia.org/wiki/Expect" target="_top">expect</a> in that it'll read from a stream until the pattern, as specified by the first parameter, is found.  If the second parameter is set to NET_SSH2_READ_REGEX then the first parameter will be treated as a regular expression.
                </p><p>
                    write() sends input - such as a command - to the server.  Normally, operating systems don't process commands until the Enter key is hit, so to mimic this, you'll need to send a "\n", a "\r\n" or a "\r" depending on the operating system the server you're connecting to is using.  Note that although the input will most likely be a command it doesn't have to be.  What you send will be parsed by whatever is expecting user-entered text.  So if you type in "passwd\n" the input - until "\n" is entered - will be parsed by passwd as a new or existing password - not as a command to be ran by the shell.
                </p><p>
                    exec() sends a command to the shell to be ran.  After the command has run it's course you'll get it's output and if the prompt - or whatever it is that you might alternatively read up to with read() - occurs anywhere in the output this is not a problem.
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="net_ssh_sudo"></a>5.1.5. sudo with read() / write()</h3></div></div></div><p>
                    By default, <a class="ulink" href="http://en.wikipedia.org/wiki/Sudo" target="_top">sudo</a> caches passwords for 5 minutes after they've been entered.  So while <code class="code">$ssh-&gt;read('Password:')</code> will work the first time you try it, it won't work if you try it within a five minutes after having initially ran it.  The following code sample demonstrates how to get around this:
                </p><pre class="programlisting">&lt;?php
include('Net/SSH2.php');

$sftp = new Net_SSH2('www.domain.tld');
$sftp-&gt;login('username', 'password');

echo $sftp-&gt;read('username@username:~$');
$sftp-&gt;write("sudo ls -la\n");
$output = $sftp-&gt;read('#Password:|username@username:~\$#', NET_SSH2_READ_REGEX);
echo $output;
if (preg_match('#Password:#', $lines)) {
    $ssh-&gt;write("password\n");
    echo $sftp-&gt;read('username@username:~$');
}
&gt;</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="net_ssh_exec"></a>5.1.6. SSH-1's exec() vs. SSH-2's exec()</h3></div></div></div><p>
                    <code class="code">exec()</code> works by creating a channel, issuing a command, and then subsequently destroying that channel.  Since SSH-1 <a class="ulink" href="http://www.snailbook.com/faq/ssh-1-vs-2.auto.html" target="_top">only allows one channel</a>, exec() can only be called once.  SSH-2, in contrast, allows an unlimited number of channels, and as such, you can perform as many <code class="code">exec()</code>'s as you see fit.
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="net_ssh_successive"></a>5.1.7. Successive calls to SSH-2's exec()</h3></div></div></div><p>
                    Successive calls to SSH-2's exec() may not work as expected.  Consider the following:
                </p><pre class="programlisting">&lt;?php
include('Net/SSH2.php');

$ssh = new Net_SSH2('www.domain.tld');
if (!$ssh-&gt;login('username', 'password')) {
    exit('Login Failed');
}

echo $ssh-&gt;exec('pwd');
echo $ssh-&gt;exec('cd /');
echo $ssh-&gt;exec('pwd');
?&gt;</pre><p>
                    If done on an interactive shell, the output you'd receive for the first <code class="code">pwd</code> would (depending on how your system is setup) be different than the output of the second <code class="code">pwd</code>.  The above code snippet, however, will yield two identical lines.  The reason for this is that any "state changes" you make to the one-time shell are gone once the <code class="code">exec()</code> has been ran and the channel has been deleted.
                    As such, if you want to support <code class="code">cd</code> in your program, it'd be best to just handle that internally and rewrite all commands, before they're passed to <code class="code">exec()</code> such that the relative paths are expanded to the absolute paths.
                    Alternatively, one could always run a shell script, however, that may not always be an option.
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="net_ssh_debug"></a>5.1.8. Debugging SSH-2</h3></div></div></div><p>
                    To log output, the NET_SSH2_LOGGING constant will need to be defined.  If you want full logs, you'll need to do <code class="code">define('NET_SSH2_LOGGING', NET_SSH2_LOG_COMPLEX)</code>.  <code class="code">$ssh-&gt;getLog()</code> will then return a string containing the unencrypted packets in hex and ASCII.  If you want to just record the packet types that are being sent to and fro, you'll need to do <code class="code">define('NET_SSH2_LOGGING', NET_SSH2_LOG_SIMPLE)</code>.  <code class="code">$ssh-&gt;getLog()</code> will then return an array.  Both log types include the amount of time it took to send the packet in question.  The former is useful for general diagnostics and the latter is more useful for profiling.  An example follows:
                </p><pre class="programlisting">&lt;?php
include('Net/SSH2.php');
define('NET_SSH2_LOGGING', NET_SSH2_LOG_COMPLEX);

$ssh = new Net_SSH2('www.domain.tld');
if (!$ssh-&gt;login('username', 'password')) {
    exit('Login Failed');
}

echo $ssh-&gt;exec('pwd');
echo $ssh-&gt;getLog();
?&gt;</pre><p>
                    Depending on the problem, it may be more effective to just look at the output of <code class="code">$ssh-&gt;getLastError()</code> (which returns a string) and <code class="code">$ssh-&gt;getErrors()</code> (which returns an array) than to sift through the logs.
                </p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="net_sftp"></a>5.2. Net_SFTP</h2></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="net_sftp_intro"></a>5.2.1. Introduction</h3></div></div></div><p>
                    Net_SFTP currently only supports SFTPv3, which, according to wikipedia.org, "is the most widely used 
                    version, implemented by the popular OpenSSH SFTP server".
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="net_sftp_dependencies"></a>5.2.2. Dependencies</h3></div></div></div><p>
                    Net_SFTP requires, minimally, PHP 4.3.0 and Net/SSH2.php, Math/BigInteger.php, Crypt/*.php, and PHP/Compat/Function/*.php.
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="net_sftp_example"></a>5.2.3. Net_SFTP Example</h3></div></div></div><pre class="programlisting">&lt;?php
include('Net/SFTP.php');

$sftp = new Net_SFTP('www.domain.tld');
if (!$sftp-&gt;login('username', 'password')) {
    exit('Login Failed');
}

echo $sftp-&gt;pwd() . "\r\n";
$sftp-&gt;put('filename.ext', 'hello, world!');
print_r($sftp-&gt;nlist());
?&gt;</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="net_sftp_put"></a>5.2.4. put($remote_file, $data [, $mode])</h3></div></div></div><p>
                    By default, put() does not read from the local filesystem.  $data is dumped directly into $remote_file.
                    So, for example, if you set $data to 'filename.ext' and then do get(), you will get a file, twelve bytes
                    long, containing 'filename.ext' as its contents.
                </p><p>
                    Setting $mode to NET_SFTP_LOCAL_FILE will change the above behavior.  With NET_SFTP_LOCAL_FILE, $remote_file will 
                    contain as many bytes as filename.ext does on your local filesystem.  If your filename.ext is 1MB then that is how
                    large $remote_file will be, as well.
                </p><p>
                    Currently, only binary mode is supported.  As such, if the line endings need to be adjusted, you will need to take
                    care of that, yourself.
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="net_sftp_get"></a>5.2.5. get($remote_file [, $local_file])</h3></div></div></div><p>
                    Returns a string containing the contents of $remote_file if $local_file is left undefined or a boolean false if
                    the operation was unsuccessful.  If $local_file is defined, returns true or false depending on the success of the
                    operation
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="net_sftp_pwd"></a>5.2.6. pwd(), chdir(), mkdir() and rmdir()</h3></div></div></div><p>
                    pwd() returns the current directory, chdir() changes directories, mkdir() creates direcotires, and rmdir() removes directories.
                    In the event of failure, they all return false.  chdir(), mkdir(), and rmdir() return true on successful completion of the operation.
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="net_sftp_chmod"></a>5.2.7. chmod() and size()</h3></div></div></div><p>
                    chmod() sets the permissions on a file and returns the new file permissions on success or false on error.  Permissions are expected to be in octal so to set a file to 777 do <code class="code">$sftp-&gt;chmod(0777, $filename)</code>
                </p><p>
                    size() returns the size, in bytes, of an arbitrary file.
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="net_sftp_nlist"></a>5.2.8. nlist() and rawlist()</h3></div></div></div><p>
                    nlist($dir = '.') returns the contents of the current directory as a numerically indexed array and rawlist() returns an associate array where the filenames are the array keys and the array values are, themselves, arrays containing the file attributes.  The directory can be changed with the first parameter.
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="net_sftp_stat"></a>5.2.9. stat() and lstat()</h3></div></div></div><p>
                    stat() returns information about a specific file whereas list() returns information about a file or symbolic link.
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="net_sftp_delete"></a>5.2.10. delete() and rename()</h3></div></div></div><p>
                    The purpose of both functions should be easy enough to glean - delete() deletes files or directories and rename() renames them.  Both return true on success and false on failure.
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="net_sftp_debug"></a>5.2.11. Debugging SFTP</h3></div></div></div><p>
                    To log output, the NET_SFTP_LOGGING constant will need to be defined.  If you want full logs, you'll need to do <code class="code">define('NET_SFTP_LOGGING', NET_SFTP_LOG_COMPLEX)</code>.  <code class="code">$ssh-&gt;getSFTPLog()</code> will then return a string containing the unencrypted packets in hex and ASCII.  If you want to just record the packet types that are being sent to and fro, you'll need to do <code class="code">define('NET_SFTP_LOGGING', NET_SFTP_LOG_SIMPLE)</code>.  <code class="code">$ssh-&gt;getLog()</code> will then return an array.  Both log types include the amount of time it took to send the packet in question.  The former is useful for general diagnostics and the latter is more useful for profiling.  An example follows:
                </p><pre class="programlisting">&lt;?php
include('Net/SFTP.php');
define('NET_SFTP_LOGGING', NET_SFTP_LOG_COMPLEX); // or NET_SFTP_LOG_SIMPLE

$sftp = new Net_SFTP('www.domain.tld');
if (!$sftp-&gt;login('username', 'password')) {
    exit('Login Failed');
}

print_r($sftp-&gt;nlist());
echo $ssh-&gt;getSFTPLog();
?&gt;</pre><p>
                    Depending on the problem, it may be more effective to just look at the output of <code class="code">$ssh-&gt;getLastSFTPError()</code> (which returns a string) and <code class="code">$ssh-&gt;getSFTPErrors()</code> (which returns an array) than to sift through the logs.
                </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="misc_crypt.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top">Chapter 4. Miscellaneous Cryptography </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>

vroom360

initial commit