Module Mirage_crypto_pk.Dh

Diffie-Hellman, MODP version.

Diffie-Hellman key exchange

exception Invalid_key

Raised if the private key material is degenerate. The following invariants are checked: Secret key: 1 < secret < p Public key: 1 < public < p-1 && public <> gg

type group = private {
p : Z.t;

modulus

gg : Z.t;

generator

q : Z.t option;

subgroup order; potentially unknown

}

A DH group.

Sexplib convertible.

val group : p:Z.t -> gg:Z.t -> ?⁠q:Z.t -> unit -> (group, [> `Msg of string ]) Stdlib.result

group ~p ~gg ~q () constructs a group if p is odd, a prime number, and greater than zero. gg must be in the range 1 < gg < p.

type secret = private {
group : group;
x : Z.t;
}

A private key.

Sexplib convertible.

val modulus_size : group -> bits

Bit size of the modulus.

val key_of_secret : group -> s:Cstruct.t -> secret * Cstruct.t

key_of_secret group s is the secret and the corresponding public key which use s as the secret exponent.

raises Invalid_key

if s is degenerate.

val gen_key : ?⁠g:Mirage_crypto_rng.g -> ?⁠bits:bits -> group -> secret * Cstruct.t

Generate a random secret and the corresponding public key. bits is the exact bit-size of secret and defaults to a value dependent on the group's p.

Note The process might diverge when bits is extremely small.

val shared : secret -> Cstruct.t -> Cstruct.t option

shared secret public is Some shared_key given a a previously generated secret (which specifies the group) and the other party's public key. shared_key is the unpadded big-endian representation of the shared key. It is None if these invariants do not hold for public: 1 < public < p-1 && public <> gg.

val gen_group : ?⁠g:Mirage_crypto_rng.g -> bits:bits -> unit -> group

gen_group ~g ~bits () generates a random group with modulus size bits. Uses a safe prime p = 2q + 1 (with q prime) for the modulus and 2 for the generator, such that 2^q = 1 mod p. Runtime is on the order of a minute for 1024 bits. Note that no time masking is done for the modular exponentiation.

Note The process might diverge if there are no suitable groups. This happens with extremely small bits values.

module Group : sig ... end

A small catalog of standardized groups.