package cryptokit

  1. Overview
  2. Docs

The DH 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).

The protocol executes as follows:

  • Both parties must agree beforehand on a set of public parameters (type Cryptokit.DH.parameters). Suitable parameters can be generated by calling Cryptokit.DH.new_parameters, or fixed parameters taken from the literature can be used.
  • Each party computes a random private secret using the function Cryptokit.DH.private_secret.
  • From its private secrets and the public parameters, each party computes a message (a string) with the function Cryptokit.DH.message, and sends it to the other party.
  • Each party recovers the shared secret by applying the function Cryptokit.DH.shared_secret to its private secret and to the message received from the other party.
  • Fixed-size keys can then be derived from the shared secret using the function Cryptokit.DH.derive_key.
type parameters = {
  1. p : string;
    (*

    Large prime number

    *)
  2. g : string;
    (*

    Generator of Z/pZ

    *)
  3. privlen : int;
    (*

    Length of private secrets in bits

    *)
}

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.

val new_parameters : ?rng:Random.rng -> ?privlen:int -> int -> parameters

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.

Generate a new set of Diffie-Hellman parameters. The non-optional argument is the size in bits of the p parameter. It must be large enough that the discrete logarithm problem modulo p is computationally unsolvable. 1024 is a reasonable value. The optional rng argument specifies a random number generator to use for generating the parameters; it defaults to Cryptokit.Random.secure_rng. The optional privlen argument is the size in bits of the private secrets that are generated during the key agreement protocol; the default is 160.

type private_secret

Generate a new set of Diffie-Hellman parameters. The non-optional argument is the size in bits of the p parameter. It must be large enough that the discrete logarithm problem modulo p is computationally unsolvable. 1024 is a reasonable value. The optional rng argument specifies a random number generator to use for generating the parameters; it defaults to Cryptokit.Random.secure_rng. The optional privlen argument is the size in bits of the private secrets that are generated during the key agreement protocol; the default is 160.

The abstract type of private secrets generated during key agreement.

val private_secret : ?rng:Random.rng -> parameters -> private_secret

The abstract type of private secrets generated during key agreement.

Generate a random private secret. The optional rng argument specifies a random number generator to use; it defaults to Cryptokit.Random.secure_rng.

val message : parameters -> private_secret -> string

Generate a random private secret. The optional rng argument specifies a random number generator to use; it defaults to Cryptokit.Random.secure_rng.

Compute the message to be sent to the other party.

val shared_secret : parameters -> private_secret -> string -> string

Compute the message to be sent to the other party.

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 p parameter. The private secret is destroyed and can no longer be used afterwards.

val derive_key : ?diversification:string -> string -> int -> string

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 p parameter. The private secret is destroyed and can no longer be used afterwards.

derive_key shared_secret numbytes derives a secret string (typically, a key for symmetric encryption) from the given shared secret. numbytes is the desired length for the returned string. The optional diversification 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 diversification 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 numbytes bytes have been obtained.