Added: incubator/vcl/trunk/web/.ht-inc/phpseclib/net.html URL: http://svn.apache.org/viewvc/incubator/vcl/trunk/web/.ht-inc/phpseclib/net.html?rev=1136647&view=auto ============================================================================== --- incubator/vcl/trunk/web/.ht-inc/phpseclib/net.html (added) +++ incubator/vcl/trunk/web/.ht-inc/phpseclib/net.html Thu Jun 16 20:18:36 2011 @@ -0,0 +1,153 @@ +<?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="s ection"><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"><?php +include('Net/SSH2.php'); + +$ssh = new Net_SSH2('www.domain.tld'); +if (!$ssh->login('username', 'password')) { + exit('Login Failed'); +} + +echo $ssh->exec('pwd'); +echo $ssh->exec('ls -la'); +?></pre><pre class="programlisting"><?php +include('Net/SSH2.php'); + +$key = new Crypt_RSA(); +//$key->setPassword('whatever'); +$key->loadKey(file_get_contents('privatekey')); + +$ssh = new Net_SSH2('www.domain.tld'); +if (!$ssh->login('username', $key)) { + exit('Login Failed'); +} + +echo $ssh->read('username@username:~$'); +$ssh->write("ls -la\n"); +echo $ssh->read('username@username:~$'); +?></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->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"><?php +include('Net/SSH2.php'); + +$sftp = new Net_SSH2('www.domain.tld'); +$sftp->login('username', 'password'); + +echo $sftp->read('username@username:~$'); +$sftp->write("sudo ls -la\n"); +$output = $sftp->read('#Password:|username@username:~\$#', NET_SSH2_READ_REGEX); +echo $output; +if (preg_match('#Password:#', $lines)) { + $ssh->write("password\n"); + echo $sftp->read('username@username:~$'); +} +></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"><?php +include('Net/SSH2.php'); + +$ssh = new Net_SSH2('www.domain.tld'); +if (!$ssh->login('username', 'password')) { + exit('Login Failed'); +} + +echo $ssh->exec('pwd'); +echo $ssh->exec('cd /'); +echo $ssh->exec('pwd'); +?></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->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->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"><?php +include('Net/SSH2.php'); +define('NET_SSH2_LOGGING', NET_SSH2_LOG_COMPLEX); + +$ssh = new Net_SSH2('www.domain.tld'); +if (!$ssh->login('username', 'password')) { + exit('Login Failed'); +} + +echo $ssh->exec('pwd'); +echo $ssh->getLog(); +?></pre><p> + Depending on the problem, it may be more effective to just look at the output of <code class="code">$ssh->getLastError()</code> (which returns a string) and <code class="code">$ssh->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"><?php +include('Net/SFTP.php'); + +$sftp = new Net_SFTP('www.domain.tld'); +if (!$sftp->login('username', 'password')) { + exit('Login Failed'); +} + +echo $sftp->pwd() . "\r\n"; +$sftp->put('filename.ext', 'hello, world!'); +print_r($sftp->nlist()); +?></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->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->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->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"><?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->login('username', 'password')) { + exit('Login Failed'); +} + +print_r($sftp->nlist()); +echo $ssh->getSFTPLog(); +?></pre><p> + Depending on the problem, it may be more effective to just look at the output of <code class="code">$ssh->getLastSFTPError()</code> (which returns a string) and <code class="code">$ssh->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>
Added: incubator/vcl/trunk/web/.ht-inc/phpseclib/sym_crypt.html URL: http://svn.apache.org/viewvc/incubator/vcl/trunk/web/.ht-inc/phpseclib/sym_crypt.html?rev=1136647&view=auto ============================================================================== --- incubator/vcl/trunk/web/.ht-inc/phpseclib/sym_crypt.html (added) +++ incubator/vcl/trunk/web/.ht-inc/phpseclib/sym_crypt.html Thu Jun 16 20:18:36 2011 @@ -0,0 +1,118 @@ +<?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 3. Symmetric-key Cryptography</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="math.html" title="Chapter 2. Math" /><link rel="next" 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 3. Symmetric-key Cryptography</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="math.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="misc_crypt.html" >Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" >xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a >id="sym_crypt"></a>Chapter 3. Symmetric-key >Cryptography</h2></div></div></div><div class="toc"><p><b>Table of >Contents</b></p><dl><dt><span class="section"><a >href="sym_crypt.html#sym_crypt_intro">3.1. >Introduction</a></span></dt><dd><dl><dt><span class="section"><a >href="sym_crypt.html#sym_crypt_dependencies">3.1.1. >Dependencies</a></span></dt><dt><span class="section"><a >href="sym_crypt.html#sym_crypt_set">3.1.2. setKey() and >setIV()</a></span></dt><dt><span class="section"><a >href="sym_crypt.html#sym_crypt_encrypt">3.1.3. encrypt() and >decrypt()</a></span></dt><dt><span class="section"><a >href="sym_crypt.html#sym_crypt_continuousbuffer">3.1.4. >enableContinuousBuffer() and >disableContinuousBuffer()</a></span></dt><dt><span class="section"><a >href="sym_crypt.html#sym_crypt_padding">3.1.5. enablePadding() and >disablePadding()</a></s pan></dt><dt><span class="section"><a href="sym_crypt.html#sym_crypt_caution">3.1.6. A word of caution about stream ciphers (and CTR / CFB / OFB)</a></span></dt></dl></dd><dt><span class="section"><a href="sym_crypt.html#sym_crypt_des">3.2. Crypt_DES</a></span></dt><dd><dl><dt><span class="section"><a href="sym_crypt.html#sym_crypt_des_constructor">3.2.1. The constructor</a></span></dt></dl></dd><dt><span class="section"><a href="sym_crypt.html#sym_crypt_tripledes">3.3. Crypt_TripleDES</a></span></dt><dd><dl><dt><span class="section"><a href="sym_crypt.html#sym_crypt_tripledes_constructor">3.3.1. The constructor</a></span></dt></dl></dd><dt><span class="section"><a href="sym_crypt.html#sym_crypt_rc4">3.4. Crypt_RC4</a></span></dt><dd><dl><dt><span class="section"><a href="sym_crypt.html#sym_crypt_rc4_constructor">3.4.1. The constructor</a></span></dt></dl></dd><dt><span class="section"><a href="sym_crypt.html#sym_crypt_aes">3.5. Crypt_Rijndael & Crypt_AES</a></span></dt> <dd><dl><dt><span class="section"><a href="sym_crypt.html#sym_crypt_aes_constructor">3.5.1. The constructor</a></span></dt><dt><span class="section"><a href="sym_crypt.html#sym_crypt_aes_vs_rijndael">3.5.2. AES vs. Rijndael</a></span></dt><dt><span class="section"><a href="sym_crypt.html#sym_crypt_aes_setkeylength">3.5.3. setKeyLength()</a></span></dt><dt><span class="section"><a href="sym_crypt.html#sym_crypt_aes_setblocklength">3.5.4. setBlockLength()</a></span></dt><dt><span class="section"><a href="sym_crypt.html#sym_crypt_aes_benchmarks">3.5.5. Speed Comparisons</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="sym_crypt_intro"></a>3.1. Introduction</h2></div></div></div><p> + All of the cryptographic libraries included in phpseclib use mcrypt, if available, and an internal implementation + if it's not. The libraries all use a common interface although some functions, for some algorithms, carry with + with them certain caveats. Those that do not have caveats attached (or have relatively few attached) are + described below. If you don't know which one to use, try <code class="code">Crypt_TripleDES</code>. + </p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sym_crypt_dependencies"></a>3.1.1. Dependencies</h3></div></div></div><p> + The Crypt_* functions require, minimally, PHP 4.0.0. Crypt_TripleDES additionally requires Crypt/DES.php and Crypt_AES additionally requires Crypt/Rijndael.php. + </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sym_crypt_set"></a>3.1.2. setKey() and setIV()</h3></div></div></div><p> + Sets the key and the initialization vector, respectively. If neither are set, each assumed to be equal to + some amount of null bytes. The initialization vector is only used in block ciphers and even then only + in CBC mode. If the key or the initialization vector are larger then the block size, they're truncated. + If they're smaller, they're padded with null bytes. + </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sym_crypt_encrypt"></a>3.1.3. encrypt() and decrypt()</h3></div></div></div><p> + Self-explanatory. Encrypts or decrypts messages. See the examples in the subsequent sections. + </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sym_crypt_continuousbuffer"></a>3.1.4. enableContinuousBuffer() and disableContinuousBuffer()</h3></div></div></div><p> + If the continuous buffer is enabled and you're using a stream cipher or a block cipher mode other than ECB then encrypting the same string twice will yield different ciphertexts. + The reason being that the IV doesn't reset after each encryption / decryption round when the continuous buffer is used. + This provides better security but it may also make for less intuitive behavior. + For this reason, the continuous buffer is disabled by default. + </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sym_crypt_padding"></a>3.1.5. enablePadding() and disablePadding()</h3></div></div></div><p> + Enables / disables PKCS padding on block ciphers. Stream ciphers (<code class="code">Crypt_RC4</code> is the only stream + cipher currently included) ignore this. + </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sym_crypt_caution"></a>3.1.6. A word of caution about stream ciphers (and CTR / CFB / OFB)</h3></div></div></div><p> + Most stream ciphers (and block ciphers operating in a mode - like CTR, CFB and OFB - that turns them into stream ciphers) work by generating a stream of pseudorandom characters called a <a class="ulink" href="http://en.wikipedia.org/wiki/Keystream"; target="_top">keystream</a> and then XOR'ing that with the plaintext. + This *effectively* makes them <a class="ulink" href="http://en.wikipedia.org/wiki/One-time_pad"; target="_top">one-time pads</a> which, in theory, can provide perfect secrecy. The problem with one-time pads is that they're not as versatile as one might desire. + Among other things, a keystream must never be reset, lest it be possible for an attacker to recover the keystream via a <a class="ulink" href="http://en.wikipedia.org/wiki/Known-plaintext_attack"; target="_top">known-plaintext attack</a>. ie. <code class="code">$ciphertext ^ $plaintext = $key</code>. If <code class="code">$key</code> is constant (because the keystream's being reset or something) than an attacker can recover any <code class="code">$plaintext</code>, but if not - if it's dynamic - then the only key that an attacker could recover is their own. + </p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sym_crypt_des"></a>3.2. Crypt_DES</h2></div></div></div><p> + Implements DES (a block cipher). Here's an example of how to use it: + </p><pre class="programlisting"><?php +include('Crypt/DES.php'); + +$des = new Crypt_DES(); + +$des->setKey('abcdefgh'); + +$size = 10 * 1024; +$plaintext = ''; +for ($i = 0; $i < $size; $i++) { + $plaintext.= 'a'; +} + +echo $des->decrypt($des->encrypt($plaintext)); +?></pre><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sym_crypt_des_constructor"></a>3.2.1. The constructor</h3></div></div></div><p> + The constructor takes one optional parameter - $mode. Valid values for $mode are as follows: + </p><div class="itemizedlist"><ul type="disc"><li><code class="code">CRYPT_DES_MODE_ECB</code></li><li><code class="code">CRYPT_DES_MODE_CBC</code>: The default value.</li><li><code class="code">CRYPT_DES_MODE_CTR</code></li><li><code class="code">CRYPT_DES_MODE_CFB</code></li><li><code class="code">CRYPT_DES_MODE_OFB</code></li></ul></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sym_crypt_tripledes"></a>3.3. Crypt_TripleDES</h2></div></div></div><p> + Implements TripleDES (a block cipher). Here's an example of how to use it: + </p><pre class="programlisting"><?php +include('Crypt/TripleDES.php'); + +$des = new Crypt_TripleDES(); + +$des->setKey('abcdefghijklmnopqrstuvwx'); + +$size = 10 * 1024; +$plaintext = ''; +for ($i = 0; $i < $size; $i++) { + $plaintext.= 'a'; +} + +echo $des->decrypt($des->encrypt($plaintext)); +?></pre><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sym_crypt_tripledes_constructor"></a>3.3.1. The constructor</h3></div></div></div><p> + The constructor takes one optional parameter - $mode. Valid values for $mode are as follows: + </p><div class="itemizedlist"><ul type="disc"><li><code class="code">CRYPT_DES_MODE_ECB</code></li><li><code class="code">CRYPT_DES_MODE_CBC3</code>: Employs outer chaining to propogate the initialization vector. Used by SSH-2 and generally considered more secure than inner chaining.</li><li><code class="code">CRYPT_DES_MODE_3CBC</code>: Employs inner chaining to propogate the initialization vector. Used by SSH-1.</li><li><code class="code">CRYPT_DES_MODE_CBC</code>: The default value. An alias for <code class="code">CRYPT_DES_MODE_CBC3</code>.</li><li><code class="code">CRYPT_DES_MODE_CTR</code></li><li><code class="code">CRYPT_DES_MODE_CFB</code></li><li><code class="code">CRYPT_DES_MODE_OFB</code></li></ul></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sym_crypt_rc4"></a>3.4. Crypt_RC4</h2></div></div></div><p> + Implements RC4 (a stream cipher). Here's an example of how to use it: + </p><pre class="programlisting"><?php +include('Crypt/RC4.php'); + +$rc4 = new Crypt_RC4(); + +$rc4->setKey('abcdefghijklmnopqrstuvwx'); + +$size = 10 * 1024; +$plaintext = ''; +for ($i = 0; $i < $size; $i++) { + $plaintext.= 'a'; +} + +echo $rc4->decrypt($rc4->encrypt($plaintext)); +?></pre><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sym_crypt_rc4_constructor"></a>3.4.1. The constructor</h3></div></div></div><p> + Not much to say about this constructor. Since it's a stream cipher, you don't need to worry about which + mode of operation to use. + </p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sym_crypt_aes"></a>3.5. Crypt_Rijndael & Crypt_AES</h2></div></div></div><p> + Implements Rijndael / AES. Here's an example of how to use Crypt_AES: + </p><pre class="programlisting"><?php +include('Crypt/AES.php'); + +$aes = new Crypt_AES(); + +$aes->setKey('abcdefghijklmnop'); + +$size = 10 * 1024; +$plaintext = ''; +for ($i = 0; $i < $size; $i++) { + $plaintext.= 'a'; +} + +echo $aes->decrypt($aes->encrypt($plaintext)); +?></pre><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sym_crypt_aes_constructor"></a>3.5.1. The constructor</h3></div></div></div><p> + <code class="code">Crypt_AES</code>'s constructor's optional parameter can take the following values: + </p><div class="itemizedlist"><ul type="disc"><li><code class="code">CRYPT_AES_MODE_ECB</code></li><li><code class="code">CRYPT_AES_MODE_CBC</code>: The default value.</li><li><code class="code">CRYPT_AES_MODE_CTR</code></li><li><code class="code">CRYPT_AES_MODE_CFB</code></li><li><code class="code">CRYPT_AES_MODE_OFB</code></li></ul></div><p> + <code class="code">Crypt_Rijndael</code> takes the following: + </p><div class="itemizedlist"><ul type="disc"><li><code class="code">CRYPT_RIJNDAEL_MODE_ECB</code></li><li><code class="code">CRYPT_RIJNDAEL_MODE_CBC</code>: The default value.</li><li><code class="code">CRYPT_RIJNDAEL_MODE_CTR</code></li><li><code class="code">CRYPT_RIJNDAEL_MODE_CFB</code></li><li><code class="code">CRYPT_RIJNDAEL_MODE_OFB</code></li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sym_crypt_aes_vs_rijndael"></a>3.5.2. AES vs. Rijndael</h3></div></div></div><p> + AES is a subset of Rijndael. Both have variable key sizes, however, AES's block size is fixed at 128 bits, whereas Rijndael's is variable. Also, Rijndael supports, by means of an extension to the specification, two key sizes that AES does not - 160 bits and 224 bits. + </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sym_crypt_aes_setkeylength"></a>3.5.3. setKeyLength()</h3></div></div></div><p> + Valid key lengths for AES are 128 bits, 192 bits, and 256 bits. If the key that is assigned is invalid and less than 256 bits, they key length is rounded up to the next closest valid size and the key will be null padded to that amount. If the key length is greater than 256 bits, it will be truncated to 256 bits. + </p><p> + As an example, if the key is 136 bits, it will be null padded to 192 bits (or 160 bits if Rijndael is being used). + </p><p> + If <code class="code">setKeyLength()</code> has been called, this behavior changes somewhat. Say you've set the key length, via this function, to 256 bits. Then, instead of an invalid key being null padded to 192 or 160 bits, it will be null padded to 256 bits. + </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sym_crypt_aes_setblocklength"></a>3.5.4. setBlockLength()</h3></div></div></div><p> + <code class="code">setBlockLength()</code> operates in a manner similar to <code class="code">setKeyLength()</code>, with one exception. <code class="code">setBlockLength()</code> only works on Rijndael. Although <code class="code">Crypt_AES</code> inherits <code class="code">setBlockLength()</code> as a function, the function doesn't do anything in AES. + </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sym_crypt_aes_benchmarks"></a>3.5.5. Speed Comparisons</h3></div></div></div><p> + The following table compares the speed of five different pure-PHP implementations of AES (one of which is Crypt_Rijndael and one of which is Crypt_AES) when ran on 150KB of text on a 1.8GHz Pentium 4-M. The numbers listed are averaged from five different trials and are measured in seconds. phpseclib's two implementations are highlighted. All implementations can be viewed by clicking on their names. + </p><div class="table"><a id="sym_crypt_aes_benchmarks_table"></a><p class="title"><b>Table 3.1. AES Speed Comparisons</b></p><div class="table-contents"><table summary="AES Speed Comparisons" border="1"><colgroup><col /><col /><col /><col /><col /></colgroup><thead><tr><th align="right"><a class="ulink" href="http://phpseclib.sourceforge.net/movable-type.phps"; target="_top">movable-type.phps</a></th><th align="right"><a class="ulink" href="http://phpseclib.sourceforge.net/phpaes.phps"; target="_top">phpaes.phps</a></th><th align="right"><a class="ulink" href="http://phpseclib.sourceforge.net/phpclasses1.phps"; target="_top">phpclasses1.phps</a></th><th align="right"><a class="ulink" href="http://phpseclib.sourceforge.net/phpclasses2.phps"; target="_top">phpclasses2.phps</a></th><th align="right"><a class="ulink" href="http://phpseclib.sourceforge.net/phpseclib-aes.phps"; target="_top">phpseclib-aes.phps</a></th><th align="right"><a class="ulink" href="http ://phpseclib.sourceforge.net/phpseclib-rijndael.phps" target="_top">phpseclib-rijndael.phps</a></th></tr></thead><tbody><tr><td align="right">15.6844158172</td><td align="right">39.9537248135</td><td align="right">15.0100150108</td><td align="right">62.591713190079</td><td class="highlight" align="right">2.03581542968752</td><td class="highlight" align="right">2.62501101493836</td></tr></tbody></table></div></div><br class="table-break" /><p> + As can be seen, phpseclib's implementations are the fastest. phpseclib-aes.phps is faster than phpseclib-rijndael.phps because phpseclib-rijndael.phps has to contend with multiple block sizes whereas phpseclib-aes.phps does not. Note that if mcrypt weren't explicitily disabled phpseclib would have been even faster. + </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="math.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="misc_crypt.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. Math </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 4. Miscellaneous Cryptography</td></tr></table></div></body></html>
