]> git.mxchange.org Git - friendica.git/blob - library/phpsec/misc_crypt.html
Remove some test logging
[friendica.git] / library / 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>