aboutsummaryrefslogblamecommitdiffstats
path: root/library/phpsec/misc_crypt.html
blob: 9751ddac8ac249365e1b23c85c0eeae3aab1ba25 (plain) (tree)

























































































































































                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   
<?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 4. Miscellaneous 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="sym_crypt.html" title="Chapter 3. Symmetric-key Cryptography" /><link rel="next" href="net.html" title="Chapter 5. Networking" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 4. Miscellaneous Cryptography</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="sym_crypt.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="net.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="misc_crypt"></a>Chapter 4. Miscellaneous Cryptography</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="misc_crypt.html#misc_crypt_hash">4.1. Crypt_Hash</a></span></dt><dd><dl><dt><span class="section"><a href="misc_crypt.html#misc_crypt_hash_supported">4.1.1. Supported Algorithms and Dependencies</a></span></dt><dt><span class="section"><a href="misc_crypt.html#misc_crypt_hash_example">4.1.2. Example</a></span></dt></dl></dd><dt><span class="section"><a href="misc_crypt.html#misc_crypt_rsa">4.2. Crypt_RSA</a></span></dt><dd><dl><dt><span class="section"><a href="misc_crypt.html#misc_crypt_rsa_dependencies">4.2.1. Dependencies</a></span></dt><dt><span class="section"><a href="misc_crypt.html#misc_crypt_rsa_examples">4.2.2. Examples</a></span></dt><dt><span class="section"><a href="misc_crypt.html#misc_crypt_rsa_createkey">4.2.3. createKey()</a></span></dt><dt><span class="section"><a href="misc_crypt.html#misc_crypt_rsa_format">4.2.4. setPrivateKeyFormat(), setPublicKeyFormat(), loadKey() and setPassword()</a></span></dt><dt><span class="section"><a href="misc_crypt.html#misc_crypt_rsa_getpublickey">4.2.5. setPublicKey() and getPublicKey()</a></span></dt><dt><span class="section"><a href="misc_crypt.html#misc_crypt_rsa_encrypt">4.2.6. encrypt(), decrypt() and setEncryptionMode()</a></span></dt><dt><span class="section"><a href="misc_crypt.html#misc_crypt_rsa_sign">4.2.7. sign(), verify(), and setSignatureMode()</a></span></dt><dt><span class="section"><a href="misc_crypt.html#misc_crypt_rsa_params">4.2.8. setHash(), setMGFHash() and setSaltLength()</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="misc_crypt_hash"></a>4.1. Crypt_Hash</h2></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="misc_crypt_hash_supported"></a>4.1.1. Supported Algorithms and Dependencies</h3></div></div></div><p>The following algorithms are supported:</p><p>md2, md5, md5-96, sha1, sha1-96, sha256, sha384, and sha512</p><p>
                    Crypt_Hash requires, minimally, PHP 4.3.0 (due to its use of
                    <a class="ulink" href="http://php.net/function.sha1" target="_top">sha1()</a>).  If sha384 or sha512 are being used and
                    you're not running PHP 5.1.2 or greater then Math/BigInteger.php is also required.
                </p><p>
                    Crypt_Hash uses the hash extension if it's available (&gt; 5.1.2), mhash if it's not, and it's own
                    internal implementation if not even mhash is available.
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="misc_crypt_hash_example"></a>4.1.2. Example</h3></div></div></div><pre class="programlisting">&lt;?php
include('Crypt/Hash.php');

$hash = new Crypt_Hash('sha1');
//$hash-&gt;setKey('abcdefg');
echo bin2hex($hash-&gt;hash('abcdefg'));
?&gt;</pre><p>If <code class="code">$hash-&gt;setKey()</code> had been called <code class="code">$hash-&gt;hash()</code> would have returned an HMAC.</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="misc_crypt_rsa"></a>4.2. Crypt_RSA</h2></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="misc_crypt_rsa_dependencies"></a>4.2.1. Dependencies</h3></div></div></div>
                    If you're running PHP 5, Crypt_RSA requires Math/BigInteger.php and Crypt/Hash.php.  If you're running
                    PHP 4, Crypt_RSA also requires PHP/Compat/Function/array_fill.php, PHP/Compat/Function/bcpowmod.php, and
                    PHP/Compat/Function/str_split.php
            </div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="misc_crypt_rsa_examples"></a>4.2.2. Examples</h3></div></div></div><p>Here's an example of how to encrypt / decrypt with Crypt_RSA:</p><pre class="programlisting">&lt;?php
include('Crypt/RSA.php');

$rsa = new Crypt_RSA();
extract($rsa-&gt;createKey());

$plaintext = 'terrafrost';

$rsa-&gt;loadKey($privatekey);
$ciphertext = $rsa-&gt;encrypt($plaintext);

$rsa-&gt;loadKey($publickey);
echo $rsa-&gt;decrypt($ciphertext);
?&gt;</pre><p>Here's an example of how to create / verify a signature with Crypt_RSA:</p><pre class="programlisting">&lt;?php
include('Crypt/RSA.php');

$rsa = new Crypt_RSA();
extract($rsa-&gt;createKey());

$plaintext = 'terrafrost';

$rsa-&gt;loadKey($privatekey);
$signature = $rsa-&gt;sign($plaintext);

$rsa-&gt;loadKey($publickey);
echo $rsa-&gt;verify($plaintext, $signature) ? 'verified' : 'unverified';
&gt;</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="misc_crypt_rsa_createkey"></a>4.2.3. createKey()</h3></div></div></div><p>
                    <code class="code">createKey()</code> takes three parameters - <code class="code">$bits</code>, <code class="code">$timeout</code>,
                    and <code class="code">$primes</code>.  <code class="code">$timeout</code> is present since creating a key has the potential to be
                    fairly time consuming and will guarantee that <code class="code">createKey()</code> does not run for more than
                    <code class="code">$timeout</code> seconds.  <code class="code">$primes</code> lets provide pre-computed prime numbers to speed
                    things up.
                </p><p>
                    <code class="code">extract($rsa-&gt;createKey())</code> creates three variables - <code class="code">$publickey</code>,
                    <code class="code">$privatekey</code>, and <code class="code">$partialkey</code>.  If <code class="code">createKey</code> hit the timeout then
                    it'll return all the primes that it had managed to compute so that you might pass them back to
                    <code class="code">createKey()</code> on a subsequent call.
                </p><p>
                    The exponent can be set by defining <code class="code">CRYPT_RSA_EXPONENT</code> and multi-prime RSA can be utilized
                    by adjusting <code class="code">CRYPT_RSA_SMALLEST_PRIME</code>.  Note that these must be done before a Crypt_RSA()
                    object is initialized.
                </p><p>
                    Smaller values for <code class="code">CRYPT_RSA_SMALLEST_PRIME</code> result in increased speed at the cost of security.
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="misc_crypt_rsa_format"></a>4.2.4. setPrivateKeyFormat(), setPublicKeyFormat(), loadKey() and setPassword()</h3></div></div></div><p>Crypt_RSA supports the following formats:</p><p>CRYPT_RSA_PRIVATE_FORMAT_PKCS1:</p><pre class="programlisting">-----BEGIN RSA PRIVATE KEY-----
MIICWgIBAAKBgHx5XHa3LjiugtNq2xkd0oFf2SdsJ04hQYLoeRR3bqAei3Gc+PSy
AvynCIh/03JCvBsUHaCe8BwjwaTYrpq5QunGo/wvIzvx2d3G9dlrpOIFLiatZYOf
h07+CkSfaRXhBUKkul/gU87WPhKEcbnPDJS10uD1HqLsHfSKLNitGOf7AgElAoGA
ENIhQHmedlzFkjEI2eFveURNxw6dhxlANEjtxH7XmRjiaUyQWGsVKQ+nNQpa2Bbb
JkD9FbSc/OI8wz/gPmwP9eJN29CriebhaV3ebM1L1gbb5r7Vf/D/6rxB0BG/h2lA
jyZWEZrV/Gi9ZCaw/J+IUu1pAskKid84yHphvszywCUCQQDigrtr+cVkwkUsxOGd
B378yQCroXmybAD7FQHwVslafuFfTHkaMQSU/ZZLVY1ioMs1VVzzq/vOu0RstZOY
AfHFAkEAjK3mIWdG4JOM44/SrDkACNatsMtXKOi4K3SlXu9ie6ikXPD+GSZ+bWCX
GstFaXr9cHRvZPF3qYtK+j2N9UXOvwJBALeoRO/DmSFDkgifoixLRF5CHDgiD6Vs
U9J/vGIBLaNSHoSe3rtKVr3+CyhTNF3Oe0AABi1bA4UGioGn+yFNr0UCQBbQF3sJ
1CRq9ECT3PlVWfOYbzFtFQ2NhaYul1uAw9yzkEZsROF73SZ+XbFRZTOzFFds08su
E2eaDCiUXDWcnhECQQCRUQn2huHlssj8kt35NAVwiHCNfaeSQ5tiDcwfOywA4YXl
Q+kpuWq5U3V8j/9/n7pE/DL0nXEG/3QpKHJEYV5T
-----END RSA PRIVATE KEY-----</pre><p>CRYPT_RSA_PRIVATE_FORMAT_PKCS1 (with password):</p><pre class="programlisting">-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,0AE1DB47E71463BE

pI2Kk5ceURbMYNo1xQqqA5rm2/QP4hgj/HuvrACtPSz/aesbG+h4lYXGpQ9os6Ha
AyFW+iX2UWS6BRwJj1ztO20sKT6ckg7eINSfiSSAeOOiG5aHLxOYayO9aQ5UrrJX
r0QmwRJRiHTW/82PLBNzfFHYskslNI9EWA5L/Gg4NAXDWwDooGvGkDq3ex7WkWLr
k7DN2JoZuWsUZxwpgTDouRQMsygrsdSjwRDSgbnTn6luEBrL9fc5/oAWf0xoTk5h
XMiOOHPBNPiZ1883ayq91HL/6895g8U9oIR1wQmdl0USViYYp5jI19ueowCyblzP
xD3Bfpb6RPaZ/yqECOysPk6PDz257SGDMNk/QrQJ/eZkeniNXHJ8d+nJGuajZeBu
6A/bglvKGNNNWe8UJMb5P2OAliD7y7F9wXrkV5FnQ/Q49tGxdBl7WXNuGp4x2d9s
ZEnv3mOtrr1lM+2QE0Zg8mjqSem5b6Dp0LxOj5j45j5IbBrrd3MKu87jJVzp8yHy
sBC6NMYYtO03qxV/j1kJR+MmAcCF1+4GGRWdFcoc0sXGVqmEOmK4QfYx3T0Vb6Hk
oLdlh6ofZogezzJ8A1BvV382sTsJ90eqbgz3E+fDl8iR86+EV9bUujFE4IaBgZJP
gxikVItdTcq1frNKTCSH/RPeRwk+oKWTpCYGgNA+bl641onW1DCLYcd14N6TDKmY
77cOTf2ZDGOYNPycAF/FnNJJyLO3IYpU63aKBshB4dYeVrfH0FvG6g5Xt0geIkiD
5W9El4ks7/3r97x443SagDRt6Mceo5TtzzFfAo7cZeA=
-----END RSA PRIVATE KEY-----</pre><p>CRYPT_RSA_PUBLIC_FORMAT_PKCS1:</p><pre class="programlisting">-----BEGIN PUBLIC KEY-----
MIGGAoGAfHlcdrcuOK6C02rbGR3SgV/ZJ2wnTiFBguh5FHduoB6LcZz49LIC/KcIiH/TckK8GxQd
oJ7wHCPBpNiumrlC6caj/C8jO/HZ3cb12Wuk4gUuJq1lg5+HTv4KRJ9pFeEFQqS6X+BTztY+EoRx
uc8MlLXS4PUeouwd9Ios2K0Y5/sCASU=
-----END PUBLIC KEY-----</pre><p>CRYPT_RSA_PUBLIC_FORMAT_OPENSSH:</p><pre class="programlisting">ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIB8eVx2ty44roLTatsZHdKBX9knbCdOIUGC6HkUd26gHotx
nPj0sgL8pwiIf9NyQrwbFB2gnvAcI8Gk2K6auULpxqP8LyM78dndxvXZa6TiBS4mrWWDn4dO/gpEn2kV
4QVCpLpf4FPO1j4ShHG5zwyUtdLg9R6i7B30iizYrRjn+w== phpseclib-generated-key</pre><p>
                    Passwords can be set via <code class="code">setPassword()</code> and are only supported on private keys.
                    CRYPT_RSA_PUBLIC_FORMAT_OPENSSH generates keys that are intended to go in $HOME/.ssh/authorized_keys
                    for use with OpenSSH.  Another format - CRYPT_RSA_PUBLIC_FORMAT_RAW - is stored as an array with two
                    indexes - one for the modulus and one for the exponent.  Indexes accepted by <code class="code">loadkey()</code>
                    are as follows:
                </p><p>
                    e, exponent, publicExponent, modulus, modulo, n
                </p><p>
                    <code class="code">loadKey()</code> has two parameters - <code class="code">$key</code> and the optional <code class="code">$type</code>.
                    The default type, if <code class="code">$type</code> is not explicitely set, is CRYPT_RSA_PRIVATE_FORMAT_PKCS1.
                    It should, at this point, be noted that Crypt_RSA treats public and private keys largelly identically.
                    A key can be formatted as a CRYPT_RSA_PUBLIC_FORMAT_PKCS1 and still conform to the 
                    CRYPT_RSA_PRIVATE_FORMAT_PKCS1 format and vice versa.  The only real difference between private keys and
                    public keys is that private keys *can* contain their public key counterparts whereas public keys cannot.
                    That said, this distinction is, for the most part, irrelevant and academic.  For a more thorough
                    discussion of this see <a class="link" href="misc_crypt.html#misc_crypt_rsa_getpublickey" title="4.2.5. setPublicKey() and getPublicKey()">setPublicKey() and getPublicKey()</a>.
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="misc_crypt_rsa_getpublickey"></a>4.2.5. setPublicKey() and getPublicKey()</h3></div></div></div><p>
                    As noted in <a class="link" href="misc_crypt.html#misc_crypt_rsa_format" title="4.2.4. setPrivateKeyFormat(), setPublicKeyFormat(), loadKey() and setPassword()">setPrivateKeyFormat(), setPublicKeyFormat(), loadKey() and setPassword()</a>,
                    Crypt_RSA treats public and private keys largely identically.  The only real difference is that some
                    private key formats contain the public key within them whereas no public key format does.  The reason
                    you'd want to do this is for indexing purposes.  For example, in SSH-2, RSA authentication works by
                    sending your public key along with a signature created by your private key.  The SSH-2 server then looks
                    the public key up in an index of public keys to see if it's an allowed key and then verifies the signature.
                    To that end, <code class="code">setPublicKey()</code> defines the public key if it hasn't already been defined and
                    <code class="code">getPublicKey()</code> returns it.  <code class="code">getPublicKey()</code> has an optional parameter - $type -
                    that sets the format.
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="misc_crypt_rsa_encrypt"></a>4.2.6. encrypt(), decrypt() and setEncryptionMode()</h3></div></div></div><p>
                    Crypt_RSA supports two encryption modes - <code class="code">CRYPT_RSA_ENCRYPTION_OAEP</code> and
                    <code class="code">CRYPT_RSA_ENCRYPTION_PKCS1</code>.  <code class="code">CRYPT_RSA_ENCRYPTION_OAEP</code> uses
                    <a class="ulink" href="http://en.wikipedia.org/wiki/Optimal_Asymmetric_Encryption_Padding" target="_top">Optimal Asymmetric Encryption Padding</a>
                    and provides more security than <code class="code">CRYPT_RSA_ENCRYPTION_PKCS1</code>.
                </p><p>
                    Both <code class="code">CRYPT_RSA_ENCRYPTION_OAEP</code> and <code class="code">CRYPT_RSA_ENCRYPTION_PKCS1</code> impose limits
                    on how large the plaintext can be.  If the plaintext exceeds these limits the plaintext will be split
                    up such that each block falls within those limits.
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="misc_crypt_rsa_sign"></a>4.2.7. sign(), verify(), and setSignatureMode()</h3></div></div></div><p>
                    Crypt_RSA supports two signature modes - <code class="code">CRYPT_RSA_SIGNATURE_PSS</code> and
                    <code class="code">CRYPT_RSA_SIGNATURE_PKCS1</code>.  The former is assumed to provide more security than the latter.
                    See <a class="link" href="misc_crypt.html#misc_crypt_rsa_examples" title="4.2.2. Examples">Examples</a> for examples.
                </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="misc_crypt_rsa_params"></a>4.2.8. setHash(), setMGFHash() and setSaltLength()</h3></div></div></div><p>
                   In all likelihood, calling these functions will be unnecessary as the default values should be sufficient.
                   None-the-less a discussion of them follows.
                </p><p>
                    <code class="code">setHash()</code> is used with signature production / verification and (if the encryption mode is
                    CRYPT_RSA_ENCRYPTION_OAEP) encryption and decryption.  If the specified hash isn't supported sha1 will
                    be used.
                </p><p>
                    <code class="code">setMGFHash()</code> determines which hashing function should be used for the mask generation
                    function as utilized in CRYPT_RSA_ENCRYPTION_OAEP and CRYPT_RSA_SIGNATURE_PSS.  PKCS#1 recommends
                    but does not require that the MGFHash and the Hash be set to the same thing.
                </p><p>
                    <code class="code">setSaltLength()</code> is only utilized with CRYPT_RSA_SIGNATURE_PSS.  PKCS#1 recommends this
                    value either be 0 (which is what it is by default) or the length of the output of the hash function as
                    set via <code class="code">setHash()</code>
                </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sym_crypt.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="net.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 3. Symmetric-key Cryptography </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 5. Networking</td></tr></table></div></body></html>