#### mirage-crypto-pk

Simple public-key cryptography for the modern age
IN THIS PACKAGE
Module .

## 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 ] ) 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 `group`s.