phpsec/misc_crypt.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <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>
   4                     Crypt_Hash requires, minimally, PHP 4.3.0 (due to its use of
   5                     <a class="ulink" href="http://php.net/function.sha1" target="_top">sha1()</a>).  If sha384 or sha512 are being used and
   6                     you're not running PHP 5.1.2 or greater then Math/BigInteger.php is also required.
   7                 </p><p>
   8                     Crypt_Hash uses the hash extension if it's available (&gt; 5.1.2), mhash if it's not, and it's own
   9                     internal implementation if not even mhash is available.
  10                 </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
  11 include('Crypt/Hash.php');
  12
  13 $hash = new Crypt_Hash('sha1');
  14 //$hash-&gt;setKey('abcdefg');
  15 echo bin2hex($hash-&gt;hash('abcdefg'));
  16 ?&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>
  17                     If you're running PHP 5, Crypt_RSA requires Math/BigInteger.php and Crypt/Hash.php.  If you're running
  18                     PHP 4, Crypt_RSA also requires PHP/Compat/Function/array_fill.php, PHP/Compat/Function/bcpowmod.php, and
  19                     PHP/Compat/Function/str_split.php
  20             </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
  21 include('Crypt/RSA.php');
  22
  23 $rsa = new Crypt_RSA();
  24 extract($rsa-&gt;createKey());
  25
  26 $plaintext = 'terrafrost';
  27
  28 $rsa-&gt;loadKey($privatekey);
  29 $ciphertext = $rsa-&gt;encrypt($plaintext);
  30
  31 $rsa-&gt;loadKey($publickey);
  32 echo $rsa-&gt;decrypt($ciphertext);
  33 ?&gt;</pre><p>Here's an example of how to create / verify a signature with Crypt_RSA:</p><pre class="programlisting">&lt;?php
  34 include('Crypt/RSA.php');
  35
  36 $rsa = new Crypt_RSA();
  37 extract($rsa-&gt;createKey());
  38
  39 $plaintext = 'terrafrost';
  40
  41 $rsa-&gt;loadKey($privatekey);
  42 $signature = $rsa-&gt;sign($plaintext);
  43
  44 $rsa-&gt;loadKey($publickey);
  45 echo $rsa-&gt;verify($plaintext, $signature) ? 'verified' : 'unverified';
  46 &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>
  47                     <code class="code">createKey()</code> takes three parameters - <code class="code">$bits</code>, <code class="code">$timeout</code>,
  48                     and <code class="code">$primes</code>.  <code class="code">$timeout</code> is present since creating a key has the potential to be
  49                     fairly time consuming and will guarantee that <code class="code">createKey()</code> does not run for more than
  50                     <code class="code">$timeout</code> seconds.  <code class="code">$primes</code> lets provide pre-computed prime numbers to speed
  51                     things up.
  52                 </p><p>
  53                     <code class="code">extract($rsa-&gt;createKey())</code> creates three variables - <code class="code">$publickey</code>,
  54                     <code class="code">$privatekey</code>, and <code class="code">$partialkey</code>.  If <code class="code">createKey</code> hit the timeout then
  55                     it'll return all the primes that it had managed to compute so that you might pass them back to
  56                     <code class="code">createKey()</code> on a subsequent call.
  57                 </p><p>
  58                     The exponent can be set by defining <code class="code">CRYPT_RSA_EXPONENT</code> and multi-prime RSA can be utilized
  59                     by adjusting <code class="code">CRYPT_RSA_SMALLEST_PRIME</code>.  Note that these must be done before a Crypt_RSA()
  60                     object is initialized.
  61                 </p><p>
  62                     Smaller values for <code class="code">CRYPT_RSA_SMALLEST_PRIME</code> result in increased speed at the cost of security.
  63                 </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-----
  64 MIICWgIBAAKBgHx5XHa3LjiugtNq2xkd0oFf2SdsJ04hQYLoeRR3bqAei3Gc+PSy
  65 AvynCIh/03JCvBsUHaCe8BwjwaTYrpq5QunGo/wvIzvx2d3G9dlrpOIFLiatZYOf
  66 h07+CkSfaRXhBUKkul/gU87WPhKEcbnPDJS10uD1HqLsHfSKLNitGOf7AgElAoGA
  67 ENIhQHmedlzFkjEI2eFveURNxw6dhxlANEjtxH7XmRjiaUyQWGsVKQ+nNQpa2Bbb
  68 JkD9FbSc/OI8wz/gPmwP9eJN29CriebhaV3ebM1L1gbb5r7Vf/D/6rxB0BG/h2lA
  69 jyZWEZrV/Gi9ZCaw/J+IUu1pAskKid84yHphvszywCUCQQDigrtr+cVkwkUsxOGd
  70 B378yQCroXmybAD7FQHwVslafuFfTHkaMQSU/ZZLVY1ioMs1VVzzq/vOu0RstZOY
  71 AfHFAkEAjK3mIWdG4JOM44/SrDkACNatsMtXKOi4K3SlXu9ie6ikXPD+GSZ+bWCX
  72 GstFaXr9cHRvZPF3qYtK+j2N9UXOvwJBALeoRO/DmSFDkgifoixLRF5CHDgiD6Vs
  73 U9J/vGIBLaNSHoSe3rtKVr3+CyhTNF3Oe0AABi1bA4UGioGn+yFNr0UCQBbQF3sJ
  74 1CRq9ECT3PlVWfOYbzFtFQ2NhaYul1uAw9yzkEZsROF73SZ+XbFRZTOzFFds08su
  75 E2eaDCiUXDWcnhECQQCRUQn2huHlssj8kt35NAVwiHCNfaeSQ5tiDcwfOywA4YXl
  76 Q+kpuWq5U3V8j/9/n7pE/DL0nXEG/3QpKHJEYV5T
  77 -----END RSA PRIVATE KEY-----</pre><p>CRYPT_RSA_PRIVATE_FORMAT_PKCS1 (with password):</p><pre class="programlisting">-----BEGIN RSA PRIVATE KEY-----
  78 Proc-Type: 4,ENCRYPTED
  79 DEK-Info: DES-EDE3-CBC,0AE1DB47E71463BE
  80
  81 pI2Kk5ceURbMYNo1xQqqA5rm2/QP4hgj/HuvrACtPSz/aesbG+h4lYXGpQ9os6Ha
  82 AyFW+iX2UWS6BRwJj1ztO20sKT6ckg7eINSfiSSAeOOiG5aHLxOYayO9aQ5UrrJX
  83 r0QmwRJRiHTW/82PLBNzfFHYskslNI9EWA5L/Gg4NAXDWwDooGvGkDq3ex7WkWLr
  84 k7DN2JoZuWsUZxwpgTDouRQMsygrsdSjwRDSgbnTn6luEBrL9fc5/oAWf0xoTk5h
  85 XMiOOHPBNPiZ1883ayq91HL/6895g8U9oIR1wQmdl0USViYYp5jI19ueowCyblzP
  86 xD3Bfpb6RPaZ/yqECOysPk6PDz257SGDMNk/QrQJ/eZkeniNXHJ8d+nJGuajZeBu
  87 6A/bglvKGNNNWe8UJMb5P2OAliD7y7F9wXrkV5FnQ/Q49tGxdBl7WXNuGp4x2d9s
  88 ZEnv3mOtrr1lM+2QE0Zg8mjqSem5b6Dp0LxOj5j45j5IbBrrd3MKu87jJVzp8yHy
  89 sBC6NMYYtO03qxV/j1kJR+MmAcCF1+4GGRWdFcoc0sXGVqmEOmK4QfYx3T0Vb6Hk
  90 oLdlh6ofZogezzJ8A1BvV382sTsJ90eqbgz3E+fDl8iR86+EV9bUujFE4IaBgZJP
  91 gxikVItdTcq1frNKTCSH/RPeRwk+oKWTpCYGgNA+bl641onW1DCLYcd14N6TDKmY
  92 77cOTf2ZDGOYNPycAF/FnNJJyLO3IYpU63aKBshB4dYeVrfH0FvG6g5Xt0geIkiD
  93 5W9El4ks7/3r97x443SagDRt6Mceo5TtzzFfAo7cZeA=
  94 -----END RSA PRIVATE KEY-----</pre><p>CRYPT_RSA_PUBLIC_FORMAT_PKCS1:</p><pre class="programlisting">-----BEGIN PUBLIC KEY-----
  95 MIGGAoGAfHlcdrcuOK6C02rbGR3SgV/ZJ2wnTiFBguh5FHduoB6LcZz49LIC/KcIiH/TckK8GxQd
  96 oJ7wHCPBpNiumrlC6caj/C8jO/HZ3cb12Wuk4gUuJq1lg5+HTv4KRJ9pFeEFQqS6X+BTztY+EoRx
  97 uc8MlLXS4PUeouwd9Ios2K0Y5/sCASU=
  98 -----END PUBLIC KEY-----</pre><p>CRYPT_RSA_PUBLIC_FORMAT_OPENSSH:</p><pre class="programlisting">ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIB8eVx2ty44roLTatsZHdKBX9knbCdOIUGC6HkUd26gHotx
  99 nPj0sgL8pwiIf9NyQrwbFB2gnvAcI8Gk2K6auULpxqP8LyM78dndxvXZa6TiBS4mrWWDn4dO/gpEn2kV
 100 4QVCpLpf4FPO1j4ShHG5zwyUtdLg9R6i7B30iizYrRjn+w== phpseclib-generated-key</pre><p>
 101                     Passwords can be set via <code class="code">setPassword()</code> and are only supported on private keys.
 102                     CRYPT_RSA_PUBLIC_FORMAT_OPENSSH generates keys that are intended to go in $HOME/.ssh/authorized_keys
 103                     for use with OpenSSH.  Another format - CRYPT_RSA_PUBLIC_FORMAT_RAW - is stored as an array with two
 104                     indexes - one for the modulus and one for the exponent.  Indexes accepted by <code class="code">loadkey()</code>
 105                     are as follows:
 106                 </p><p>
 107                     e, exponent, publicExponent, modulus, modulo, n
 108                 </p><p>
 109                     <code class="code">loadKey()</code> has two parameters - <code class="code">$key</code> and the optional <code class="code">$type</code>.
 110                     The default type, if <code class="code">$type</code> is not explicitely set, is CRYPT_RSA_PRIVATE_FORMAT_PKCS1.
 111                     It should, at this point, be noted that Crypt_RSA treats public and private keys largelly identically.
 112                     A key can be formatted as a CRYPT_RSA_PUBLIC_FORMAT_PKCS1 and still conform to the
 113                     CRYPT_RSA_PRIVATE_FORMAT_PKCS1 format and vice versa.  The only real difference between private keys and
 114                     public keys is that private keys *can* contain their public key counterparts whereas public keys cannot.
 115                     That said, this distinction is, for the most part, irrelevant and academic.  For a more thorough
 116                     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>.
 117                 </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>
 118                     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>,
 119                     Crypt_RSA treats public and private keys largely identically.  The only real difference is that some
 120                     private key formats contain the public key within them whereas no public key format does.  The reason
 121                     you'd want to do this is for indexing purposes.  For example, in SSH-2, RSA authentication works by
 122                     sending your public key along with a signature created by your private key.  The SSH-2 server then looks
 123                     the public key up in an index of public keys to see if it's an allowed key and then verifies the signature.
 124                     To that end, <code class="code">setPublicKey()</code> defines the public key if it hasn't already been defined and
 125                     <code class="code">getPublicKey()</code> returns it.  <code class="code">getPublicKey()</code> has an optional parameter - $type -
 126                     that sets the format.
 127                 </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>
 128                     Crypt_RSA supports two encryption modes - <code class="code">CRYPT_RSA_ENCRYPTION_OAEP</code> and
 129                     <code class="code">CRYPT_RSA_ENCRYPTION_PKCS1</code>.  <code class="code">CRYPT_RSA_ENCRYPTION_OAEP</code> uses
 130                     <a class="ulink" href="http://en.wikipedia.org/wiki/Optimal_Asymmetric_Encryption_Padding" target="_top">Optimal Asymmetric Encryption Padding</a>
 131                     and provides more security than <code class="code">CRYPT_RSA_ENCRYPTION_PKCS1</code>.
 132                 </p><p>
 133                     Both <code class="code">CRYPT_RSA_ENCRYPTION_OAEP</code> and <code class="code">CRYPT_RSA_ENCRYPTION_PKCS1</code> impose limits
 134                     on how large the plaintext can be.  If the plaintext exceeds these limits the plaintext will be split
 135                     up such that each block falls within those limits.
 136                 </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>
 137                     Crypt_RSA supports two signature modes - <code class="code">CRYPT_RSA_SIGNATURE_PSS</code> and
 138                     <code class="code">CRYPT_RSA_SIGNATURE_PKCS1</code>.  The former is assumed to provide more security than the latter.
 139                     See <a class="link" href="misc_crypt.html#misc_crypt_rsa_examples" title="4.2.2. Examples">Examples</a> for examples.
 140                 </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>
 141                    In all likelihood, calling these functions will be unnecessary as the default values should be sufficient.
 142                    None-the-less a discussion of them follows.
 143                 </p><p>
 144                     <code class="code">setHash()</code> is used with signature production / verification and (if the encryption mode is
 145                     CRYPT_RSA_ENCRYPTION_OAEP) encryption and decryption.  If the specified hash isn't supported sha1 will
 146                     be used.
 147                 </p><p>
 148                     <code class="code">setMGFHash()</code> determines which hashing function should be used for the mask generation
 149                     function as utilized in CRYPT_RSA_ENCRYPTION_OAEP and CRYPT_RSA_SIGNATURE_PSS.  PKCS#1 recommends
 150                     but does not require that the MGFHash and the Hash be set to the same thing.
 151                 </p><p>
 152                     <code class="code">setSaltLength()</code> is only utilized with CRYPT_RSA_SIGNATURE_PSS.  PKCS#1 recommends this
 153                     value either be 0 (which is what it is by default) or the length of the output of the hash function as
 154                     set via <code class="code">setHash()</code>
 155                 </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>