<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="Start" href="index.html">
<link rel="previous" href="Cryptokit.RSA.html">
<link rel="next" href="Cryptokit.Block.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.DH</title>
</head>
<body>
<div class="navbar"><a href="Cryptokit.RSA.html">Previous</a>
<a href="Cryptokit.html">Up</a>
<a href="Cryptokit.Block.html">Next</a>
</div>
<center><h1>Module <a href="type_Cryptokit.DH.html">Cryptokit.DH</a></h1></center>
<br>
<pre><span class="keyword">module</span> DH: <code class="code">sig</code> <a href="Cryptokit.DH.html">..</a> <code class="code">end</code></pre>The <code class="code">DH</code> module implements Diffie-Hellman key agreement.
Key agreement is a protocol by which two parties can establish
a shared secret (typically a key for a symmetric cipher or MAC)
by exchanging messages, with the guarantee that even if an attacker
eavesdrop on the messages, he cannot recover the shared secret.
Diffie-Hellman is one such key agreement protocol, relying on
the difficulty of computing discrete logarithms. Notice that
the Diffie-Hellman protocol is vulnerable to active attacks
(man-in-the-middle attacks).
<p>
The protocol executes as follows:<ul>
<li>Both parties must agree beforehand on a set of public parameters
(type <a href="Cryptokit.DH.html#TYPEparameters"><code class="code">Cryptokit.DH.parameters</code></a>). Suitable parameters
can be generated by calling <a href="Cryptokit.DH.html#VALnew_parameters"><code class="code">Cryptokit.DH.new_parameters</code></a>,
or fixed parameters taken from the literature can be used.</li>
<li>Each party computes a random private secret using the function
<a href="Cryptokit.DH.html#VALprivate_secret"><code class="code">Cryptokit.DH.private_secret</code></a>.</li>
<li>From its private secrets and the public parameters, each party
computes a message (a string) with the function <a href="Cryptokit.DH.html#VALmessage"><code class="code">Cryptokit.DH.message</code></a>,
and sends it to the other party.</li>
<li>Each party recovers the shared secret by applying the function
<a href="Cryptokit.DH.html#VALshared_secret"><code class="code">Cryptokit.DH.shared_secret</code></a> to its private secret and to the
message received from the other party.</li>
<li>Fixed-size keys can then be derived from the shared secret
using the function <a href="Cryptokit.DH.html#VALderive_key"><code class="code">Cryptokit.DH.derive_key</code></a>.</li>
</ul>
<br>
<hr width="100%">
<br><code><span class="keyword">type</span> <a name="TYPEparameters"></a><code class="type"></code>parameters = {</code><table class="typetable">
<tr>
<td align="left" valign="top" >
<code> </code></td>
<td align="left" valign="top" >
<code>p : <code class="type">string</code>;</code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" ><code>Large prime number</code></td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code> </code></td>
<td align="left" valign="top" >
<code>g : <code class="type">string</code>;</code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" ><code>Generator of <code class="code">Z/pZ</code></code></td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code> </code></td>
<td align="left" valign="top" >
<code>privlen : <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>Length of private secrets in bits</code></td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr></table>
}
<div class="info">
The type of Diffie-Hellman parameters. These parameters
need to be agreed upon by the two parties before the key agreement
protocol is run. The parameters are public and can be reused
for several runs of the protocol.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALnew_parameters"></a>new_parameters : <code class="type">?rng:<a href="Cryptokit.Random.rng.html">Cryptokit.Random.rng</a> -> ?privlen:int -> int -> <a href="Cryptokit.DH.html#TYPEparameters">parameters</a></code></pre><div class="info">
Generate a new set of Diffie-Hellman parameters.
The non-optional argument is the size in bits of the <code class="code">p</code> parameter.
It must be large enough that the discrete logarithm problem modulo
<code class="code">p</code> is computationally unsolvable. 1024 is a reasonable value.
The optional <code class="code">rng</code> argument specifies a random number generator
to use for generating the parameters; it defaults to
<a href="Cryptokit.Random.html#VALsecure_rng"><code class="code">Cryptokit.Random.secure_rng</code></a>. The optional <code class="code">privlen</code> argument
is the size in bits of the private secrets that are generated
during the key agreement protocol; the default is 160.<br>
</div>
<pre><span class="keyword">type</span> <a name="TYPEprivate_secret"></a><code class="type"></code>private_secret </pre>
<div class="info">
The abstract type of private secrets generated during key agreement.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALprivate_secret"></a>private_secret : <code class="type">?rng:<a href="Cryptokit.Random.rng.html">Cryptokit.Random.rng</a> -><br> <a href="Cryptokit.DH.html#TYPEparameters">parameters</a> -> <a href="Cryptokit.DH.html#TYPEprivate_secret">private_secret</a></code></pre><div class="info">
Generate a random private secret.
The optional <code class="code">rng</code> argument specifies a random number generator
to use; it defaults to <a href="Cryptokit.Random.html#VALsecure_rng"><code class="code">Cryptokit.Random.secure_rng</code></a>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALmessage"></a>message : <code class="type"><a href="Cryptokit.DH.html#TYPEparameters">parameters</a> -> <a href="Cryptokit.DH.html#TYPEprivate_secret">private_secret</a> -> string</code></pre><div class="info">
Compute the message to be sent to the other party.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALshared_secret"></a>shared_secret : <code class="type"><a href="Cryptokit.DH.html#TYPEparameters">parameters</a> -> <a href="Cryptokit.DH.html#TYPEprivate_secret">private_secret</a> -> string -> string</code></pre><div class="info">
Recover the shared secret from the private secret of the
present party and the message received from the other party.
The shared secret returned is a string of the same length as
the <code class="code">p</code> parameter. The private secret is destroyed and can no
longer be used afterwards.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALderive_key"></a>derive_key : <code class="type">?diversification:string -> string -> int -> string</code></pre><div class="info">
<code class="code">derive_key shared_secret numbytes</code> derives a secret string
(typically, a key for symmetric encryption) from the given shared
secret. <code class="code">numbytes</code> is the desired length for the returned string.
The optional <code class="code">diversification</code> argument is an arbitrary string
that defaults to the empty string. Different secret strings can
be obtained from the same shared secret by supplying different
<code class="code">diversification</code> argument. The computation of the secret
string is performed by SHA-1 hashing of the diversification
string, followed by the shared secret, followed by an integer
counter. The hashing is repeated with increasing values of the
counter until <code class="code">numbytes</code> bytes have been obtained.<br>
</div>
</body></html>
