<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="Start" href="index.html">
<link rel="previous" href="Cryptokit.Padding.html">
<link rel="next" href="Cryptokit.Hash.html">
<link rel="Up" href="Cryptokit.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of class methods" rel=Appendix href="index_methods.html">
<link title="Index of classes" rel=Appendix href="index_classes.html">
<link title="Index of class types" rel=Appendix href="index_class_types.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Cryptokit" rel="Chapter" href="Cryptokit.html"><title>Cryptokit.Cipher</title>
</head>
<body>
<div class="navbar"><a href="Cryptokit.Padding.html">Previous</a>
<a href="Cryptokit.html">Up</a>
<a href="Cryptokit.Hash.html">Next</a>
</div>
<center><h1>Module <a href="type_Cryptokit.Cipher.html">Cryptokit.Cipher</a></h1></center>
<br>
<pre><span class="keyword">module</span> Cipher: <code class="code">sig</code> <a href="Cryptokit.Cipher.html">..</a> <code class="code">end</code></pre>The <code class="code">Cipher</code> module implements the AES, DES, Triple-DES and ARCfour
symmetric ciphers. Symmetric ciphers are presented as transforms
parameterized by a secret key and a ``direction'' indicating
whether encryption or decryption is to be performed.
The same secret key is used for encryption and for decryption.<br>
<hr width="100%">
<br><code><span class="keyword">type</span> <a name="TYPEdirection"></a><code class="type"></code>direction = </code><table class="typetable">
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">Encrypt</span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">Decrypt</span></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" ><code>Indicate whether the cipher should perform encryption
(transforming plaintext to ciphertext) or decryption
(transforming ciphertext to plaintext).</code></td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr></table>
<br><code><span class="keyword">type</span> <a name="TYPEchaining_mode"></a><code class="type"></code>chaining_mode = </code><table class="typetable">
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">ECB</span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">CBC</span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">CFB</span> <span class="keyword">of</span> <code class="type">int</code></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">OFB</span> <span class="keyword">of</span> <code class="type">int</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" ><code>Block ciphers such as AES or DES map a fixed-sized block of
input data to a block of output data of the same size.
A chaining mode indicates how to extend them to multiple blocks
of data. The four chaining modes supported in this library are:<ul>
<li><code class="code">ECB</code>: Electronic Code Book mode.</li>
<li><code class="code">CBC</code>: Cipher Block Chaining mode.</li>
<li><code class="code">CFB n</code>: Cipher Feedback Block with <code class="code">n</code> bytes.</li>
<li><code class="code">OFB n</code>: Output Feedback Block with <code class="code">n</code> bytes.</li>
</ul>
A detailed description of these modes is beyond the scope of
this documentation; refer to a good cryptography book.
<code class="code">CBC</code> is a recommended default. For <code class="code">CFB n</code> and <code class="code">OFB n</code>,
note that the blocksize is reduced to <code class="code">n</code>, but encryption
speed drops by a factor of <code class="code">blocksize / n</code>, where <code class="code">blocksize</code>
is the block size of the underlying cipher; moreover, <code class="code">n</code>
must be between <code class="code">1</code> and <code class="code">blocksize</code> included.</code></td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr></table>
<pre><span class="keyword">val</span> <a name="VALaes"></a>aes : <code class="type">?mode:<a href="Cryptokit.Cipher.html#TYPEchaining_mode">chaining_mode</a> -><br> ?pad:<a href="Cryptokit.Padding.scheme.html">Cryptokit.Padding.scheme</a> -><br> ?iv:string -> string -> <a href="Cryptokit.Cipher.html#TYPEdirection">direction</a> -> <a href="Cryptokit.transform.html">Cryptokit.transform</a></code></pre><div class="info">
AES is the Advanced Encryption Standard, also known as Rijndael.
This is a modern block cipher, recently standardized.
It processes data by blocks of 128 bits (16 bytes),
and supports keys of 128, 192 or 256 bits.
The string argument is the key; it must have length 16, 24 or 32.
The direction argument specifies whether encryption or decryption
is to be performed.
<p>
The optional <code class="code">mode</code> argument specifies a
chaining mode, as described above; <code class="code">CBC</code> is used by default.
<p>
The optional <code class="code">pad</code> argument specifies a padding scheme to
pad cleartext to an integral number of blocks. If no <code class="code">pad</code>
argument is given, no padding is performed and the length
of the cleartext must be an integral number of blocks.
<p>
The optional <code class="code">iv</code> argument is the initialization vector used
in modes CBC, CFB and OFB. It is ignored in ECB mode.
If provided, it must be a string of the same size as the block size
(16 bytes). If omitted, the null initialization vector
(16 zero bytes) is used.
<p>
The <code class="code">aes</code> function returns a transform that performs encryption
or decryption, depending on the direction argument.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALdes"></a>des : <code class="type">?mode:<a href="Cryptokit.Cipher.html#TYPEchaining_mode">chaining_mode</a> -><br> ?pad:<a href="Cryptokit.Padding.scheme.html">Cryptokit.Padding.scheme</a> -><br> ?iv:string -> string -> <a href="Cryptokit.Cipher.html#TYPEdirection">direction</a> -> <a href="Cryptokit.transform.html">Cryptokit.transform</a></code></pre><div class="info">
DES is the Data Encryption Standard. Probably still the
most widely used cipher today, although it can be broken
relatively easily by brute force, due to its small key size (56 bits).
It should therefore be considered as weak encryption.
Its block size is 64 bits (8 bytes).
The arguments to the <code class="code">des</code> function have the same meaning as
for the <a href="Cryptokit.Cipher.html#VALaes"><code class="code">Cryptokit.Cipher.aes</code></a> function. The key argument is
a string of length 8 (64 bits); the least significant bit of
each key byte is ignored.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALtriple_des"></a>triple_des : <code class="type">?mode:<a href="Cryptokit.Cipher.html#TYPEchaining_mode">chaining_mode</a> -><br> ?pad:<a href="Cryptokit.Padding.scheme.html">Cryptokit.Padding.scheme</a> -><br> ?iv:string -> string -> <a href="Cryptokit.Cipher.html#TYPEdirection">direction</a> -> <a href="Cryptokit.transform.html">Cryptokit.transform</a></code></pre><div class="info">
Triple DES with two or three DES keys.
This is a popular variant of DES
where each block is encrypted with a 56-bit key <code class="code">k1</code>,
decrypted with another 56-bit key <code class="code">k2</code>, then re-encrypted with
either <code class="code">k1</code> or a third 56-bit key <code class="code">k3</code>.
This results in a 112-bit or 168-bit key length that resists
brute-force attacks. However, the three encryptions required
on each block make this cipher quite slow (4 times slower than
AES). The arguments to the <code class="code">triple_des</code> function have the
same meaning as for the <a href="Cryptokit.Cipher.html#VALaes"><code class="code">Cryptokit.Cipher.aes</code></a> function. The
key argument is a string of length 16 or 24, representing the
concatenation of the key parts <code class="code">k1</code>, <code class="code">k2</code>, and optionally
<code class="code">k3</code>. The least significant bit of each key byte is
ignored.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALarcfour"></a>arcfour : <code class="type">string -> <a href="Cryptokit.Cipher.html#TYPEdirection">direction</a> -> <a href="Cryptokit.transform.html">Cryptokit.transform</a></code></pre><div class="info">
ARCfour (``alleged RC4'') is a fast stream cipher
that appears to produce equivalent results with the commercial
RC4 cipher from RSA Data Security Inc. This company holds the
RC4 trademark, and sells the real RC4 cipher. So, it is prudent
not to use ARCfour in a commercial product.
<p>
ARCfour is popular for its speed: approximately 2 times faster
than AES. It accepts any key length up to 2048 bits.
<p>
The ARCfour cipher is a stream cipher, not a block cipher.
Hence, its natural block size is 1, and no padding is
required. Chaining modes do not apply. A feature of stream
ciphers is that the xor of two ciphertexts obtained with the
same key is the xor of the corresponding plaintexts, which
allows various attacks. Hence, the same key must never be
reused.
<p>
The string argument is the key; its length must be between
1 and 256 inclusive. The direction argument is present for
consistency with the other ciphers only, and is actually
ignored: for all stream ciphers, decryption is the same
function as encryption.<br>
</div>
</body></html>
