gazagnaire.org
upstream: https://github.com/mirage/mirage-crypto
1(** Diffie-Hellman key exchange over multiplicative groups of integers mod p. *)
2
3exception Invalid_key
4(** Raised on invalid DH parameters. *)
5
6type group = private { p : Z.t; gg : Z.t; q : Z.t option }
7(** A DH group with prime [p], generator [gg], and optional subgroup order [q].
8*)
9
10val group :
11 p:Z.t -> gg:Z.t -> ?q:Z.t -> unit -> (group, [> `Msg of string ]) result
12(** [group ~p ~gg ?q ()] constructs a DH group. *)
13
14type secret = private { group : group; x : Z.t }
15(** A DH secret key. *)
16
17val modulus_size : group -> int
18(** [modulus_size g] is the bit size of [g]'s prime modulus. *)
19
20val key_of_secret : group -> s:string -> secret * string
21(** [key_of_secret g ~s] derives a key pair from secret [s]. Returns the secret
22 and the public value. *)
23
24val gen_key : ?g:Crypto_rng.g -> ?bits:int -> group -> secret * string
25(** [gen_key ~g ~bits group] generates a fresh key pair. Returns the secret and
26 the public value. *)
27
28val shared : secret -> string -> string option
29(** [shared secret public] computes the shared secret. Returns [None] if the
30 public value is invalid. *)
31
32val gen_group : ?g:Crypto_rng.g -> bits:int -> unit -> group
33(** [gen_group ~g ~bits ()] generates a fresh DH group with a [bits]-bit prime.
34*)
35
36(** Standard DH groups. *)
37module Group : sig
38 val oakley_1 : group
39 (** Oakley group 1 (RFC 2409, 768-bit). *)
40
41 val oakley_2 : group
42 (** Oakley group 2 (RFC 2409, 1024-bit). *)
43
44 val oakley_5 : group
45 (** Oakley group 5 (RFC 3526, 1536-bit). *)
46
47 val oakley_14 : group
48 (** Oakley group 14 (RFC 3526, 2048-bit). *)
49
50 val oakley_15 : group
51 (** Oakley group 15 (RFC 3526, 3072-bit). *)
52
53 val oakley_16 : group
54 (** Oakley group 16 (RFC 3526, 4096-bit). *)
55
56 val oakley_17 : group
57 (** Oakley group 17 (RFC 3526, 6144-bit). *)
58
59 val oakley_18 : group
60 (** Oakley group 18 (RFC 3526, 8192-bit). *)
61
62 val rfc_5114_1 : group
63 (** RFC 5114 group 1 (1024-bit with 160-bit subgroup). *)
64
65 val rfc_5114_2 : group
66 (** RFC 5114 group 2 (2048-bit with 224-bit subgroup). *)
67
68 val rfc_5114_3 : group
69 (** RFC 5114 group 3 (2048-bit with 256-bit subgroup). *)
70
71 val ffdhe2048 : group
72 (** FFDHE 2048-bit group (RFC 7919). *)
73
74 val ffdhe3072 : group
75 (** FFDHE 3072-bit group (RFC 7919). *)
76
77 val ffdhe4096 : group
78 (** FFDHE 4096-bit group (RFC 7919). *)
79
80 val ffdhe6144 : group
81 (** FFDHE 6144-bit group (RFC 7919). *)
82
83 val ffdhe8192 : group
84 (** FFDHE 8192-bit group (RFC 7919). *)
85end