gazagnaire.org
upstream: https://github.com/mirage/mirage-crypto
1(** Block cipher modes of operation.
2
3 Provides module types for block cipher modes (ECB, CBC, CTR, GCM, CCM) and
4 functors to construct them from a {{!Block.Core} core cipher}
5 implementation. Includes AES and Triple-DES instantiations. *)
6
7(** {1 Block cipher signatures} *)
8
9(** Core block cipher primitive. *)
10module Block : sig
11 (** Low-level encrypt/decrypt with explicit block counts. *)
12 module type Core = sig
13 type ekey
14 (** Encryption key schedule. *)
15
16 type dkey
17 (** Decryption key schedule. *)
18
19 val of_secret : string -> ekey * dkey
20 (** [of_secret s] derives both key schedules from [s]. *)
21
22 val e_of_secret : string -> ekey
23 (** [e_of_secret s] derives the encryption key schedule. *)
24
25 val d_of_secret : string -> dkey
26 (** [d_of_secret s] derives the decryption key schedule. *)
27
28 val key : int array
29 (** Supported key sizes in bytes. *)
30
31 val block : int
32 (** Block size in bytes. *)
33
34 val encrypt :
35 key:ekey -> blocks:int -> string -> int -> bytes -> int -> unit
36 (** [encrypt ~key ~blocks src src_off dst dst_off] encrypts [blocks] blocks
37 from [src] into [dst]. *)
38
39 val decrypt :
40 key:dkey -> blocks:int -> string -> int -> bytes -> int -> unit
41 (** [decrypt ~key ~blocks src src_off dst dst_off] decrypts [blocks] blocks
42 from [src] into [dst]. *)
43 end
44
45 (** Electronic Codebook mode. *)
46 module type ECB = sig
47 type key
48 (** Cipher key. *)
49
50 val of_secret : string -> key
51 (** [of_secret s] constructs a key from [s]. *)
52
53 val key_sizes : int array
54 (** Supported key sizes in bytes. *)
55
56 val block_size : int
57 (** Block size in bytes. *)
58
59 val encrypt : key:key -> string -> string
60 (** [encrypt ~key data] encrypts [data]. *)
61
62 val decrypt : key:key -> string -> string
63 (** [decrypt ~key data] decrypts [data]. *)
64
65 val encrypt_into :
66 key:key -> string -> src_off:int -> bytes -> dst_off:int -> int -> unit
67 (** [encrypt_into ~key src ~src_off dst ~dst_off len] encrypts [len] bytes
68 from [src] into [dst]. *)
69
70 val decrypt_into :
71 key:key -> string -> src_off:int -> bytes -> dst_off:int -> int -> unit
72 (** [decrypt_into ~key src ~src_off dst ~dst_off len] decrypts [len] bytes
73 from [src] into [dst]. *)
74
75 val unsafe_encrypt_into :
76 key:key -> string -> src_off:int -> bytes -> dst_off:int -> int -> unit
77 (** Like {!encrypt_into} without bounds checking. *)
78
79 val unsafe_decrypt_into :
80 key:key -> string -> src_off:int -> bytes -> dst_off:int -> int -> unit
81 (** Like {!decrypt_into} without bounds checking. *)
82 end
83
84 (** Cipher Block Chaining mode. *)
85 module type CBC = sig
86 type key
87 (** Cipher key. *)
88
89 val of_secret : string -> key
90 (** [of_secret s] constructs a key from [s]. *)
91
92 val key_sizes : int array
93 (** Supported key sizes in bytes. *)
94
95 val block_size : int
96 (** Block size in bytes. *)
97
98 val encrypt : key:key -> iv:string -> string -> string
99 (** [encrypt ~key ~iv data] encrypts [data] with initialisation vector [iv].
100 *)
101
102 val decrypt : key:key -> iv:string -> string -> string
103 (** [decrypt ~key ~iv data] decrypts [data]. *)
104
105 val next_iv : ?off:int -> string -> iv:string -> string
106 (** [next_iv ~off ct ~iv] computes the IV for the next message from the last
107 block of ciphertext [ct]. *)
108
109 val encrypt_into :
110 key:key ->
111 iv:string ->
112 string ->
113 src_off:int ->
114 bytes ->
115 dst_off:int ->
116 int ->
117 unit
118 (** [encrypt_into ~key ~iv src ~src_off dst ~dst_off len] encrypts [len]
119 bytes from [src] into [dst]. *)
120
121 val decrypt_into :
122 key:key ->
123 iv:string ->
124 string ->
125 src_off:int ->
126 bytes ->
127 dst_off:int ->
128 int ->
129 unit
130 (** [decrypt_into ~key ~iv src ~src_off dst ~dst_off len] decrypts [len]
131 bytes from [src] into [dst]. *)
132
133 val unsafe_encrypt_into :
134 key:key ->
135 iv:string ->
136 string ->
137 src_off:int ->
138 bytes ->
139 dst_off:int ->
140 int ->
141 unit
142 (** Like {!encrypt_into} without bounds checking. *)
143
144 val unsafe_decrypt_into :
145 key:key ->
146 iv:string ->
147 string ->
148 src_off:int ->
149 bytes ->
150 dst_off:int ->
151 int ->
152 unit
153 (** Like {!decrypt_into} without bounds checking. *)
154
155 val unsafe_encrypt_into_inplace :
156 key:key -> iv:string -> bytes -> dst_off:int -> int -> unit
157 (** Like {!unsafe_encrypt_into} but encrypts the buffer in place. *)
158 end
159
160 (** Counter mode. *)
161 module type CTR = sig
162 type key
163 (** Cipher key. *)
164
165 val of_secret : string -> key
166 (** [of_secret s] constructs a key from [s]. *)
167
168 val key_sizes : int array
169 (** Supported key sizes in bytes. *)
170
171 val block_size : int
172 (** Block size in bytes. *)
173
174 type ctr
175 (** Counter value. *)
176
177 val add_ctr : ctr -> int64 -> ctr
178 (** [add_ctr ctr n] increments [ctr] by [n]. *)
179
180 val next_ctr : ?off:int -> string -> ctr:ctr -> ctr
181 (** [next_ctr ~off msg ~ctr] advances [ctr] past [msg]. *)
182
183 val ctr_of_octets : string -> ctr
184 (** [ctr_of_octets s] decodes a counter from [s]. *)
185
186 val stream : key:key -> ctr:ctr -> int -> string
187 (** [stream ~key ~ctr n] generates [n] bytes of key stream. *)
188
189 val encrypt : key:key -> ctr:ctr -> string -> string
190 (** [encrypt ~key ~ctr data] encrypts [data]. *)
191
192 val decrypt : key:key -> ctr:ctr -> string -> string
193 (** [decrypt ~key ~ctr data] decrypts [data]. *)
194
195 val stream_into : key:key -> ctr:ctr -> bytes -> off:int -> int -> unit
196 (** [stream_into ~key ~ctr buf ~off len] writes [len] bytes of key stream
197 into [buf]. *)
198
199 val encrypt_into :
200 key:key ->
201 ctr:ctr ->
202 string ->
203 src_off:int ->
204 bytes ->
205 dst_off:int ->
206 int ->
207 unit
208 (** [encrypt_into ~key ~ctr src ~src_off dst ~dst_off len] encrypts [len]
209 bytes from [src] into [dst]. *)
210
211 val decrypt_into :
212 key:key ->
213 ctr:ctr ->
214 string ->
215 src_off:int ->
216 bytes ->
217 dst_off:int ->
218 int ->
219 unit
220 (** [decrypt_into ~key ~ctr src ~src_off dst ~dst_off len] decrypts [len]
221 bytes from [src] into [dst]. *)
222
223 val unsafe_stream_into :
224 key:key -> ctr:ctr -> bytes -> off:int -> int -> unit
225 (** Like {!stream_into} without bounds checking. *)
226
227 val unsafe_encrypt_into :
228 key:key ->
229 ctr:ctr ->
230 string ->
231 src_off:int ->
232 bytes ->
233 dst_off:int ->
234 int ->
235 unit
236 (** Like {!encrypt_into} without bounds checking. *)
237
238 val unsafe_decrypt_into :
239 key:key ->
240 ctr:ctr ->
241 string ->
242 src_off:int ->
243 bytes ->
244 dst_off:int ->
245 int ->
246 unit
247 (** Like {!decrypt_into} without bounds checking. *)
248 end
249
250 (** Galois/Counter Mode. *)
251 module type GCM = sig
252 include Aead.AEAD
253
254 val key_sizes : int array
255 (** Supported key sizes in bytes. *)
256
257 val block_size : int
258 (** Block size in bytes. *)
259 end
260
261 (** Counter with CBC-MAC (16-byte tag). *)
262 module type CCM16 = sig
263 include Aead.AEAD
264
265 val key_sizes : int array
266 (** Supported key sizes in bytes. *)
267
268 val block_size : int
269 (** Block size in bytes. *)
270 end
271end
272
273(** {1 Counter representations} *)
274
275(** Counter arithmetic for CTR mode. *)
276module Counters : sig
277 (** Counter operations. *)
278 module type S = sig
279 type ctr
280 (** Counter value. *)
281
282 val size : int
283 (** Counter size in bytes. *)
284
285 val add : ctr -> int64 -> ctr
286 (** [add ctr n] increments [ctr] by [n]. *)
287
288 val of_octets : string -> ctr
289 (** [of_octets s] decodes a counter from [s]. *)
290
291 val unsafe_count_into : ctr -> bytes -> off:int -> blocks:int -> unit
292 (** [unsafe_count_into ctr buf ~off ~blocks] writes [blocks] consecutive
293 counter values into [buf]. *)
294 end
295
296 module C64be : S with type ctr = int64
297 (** Big-endian 64-bit counter. *)
298
299 module C128be : S with type ctr = int64 * int64
300 (** Big-endian 128-bit counter. *)
301
302 module C128be32 : S with type ctr = int64 * int64
303 (** Big-endian 128-bit counter, incrementing only the lower 32 bits. *)
304end
305
306(** {1 Mode functors} *)
307
308(** Constructors for block cipher modes from a core primitive. *)
309module Modes : sig
310 module ECB_of (Core : Block.Core) : Block.ECB
311 module CBC_of (Core : Block.Core) : Block.CBC
312
313 module CTR_of (Core : Block.Core) (Ctr : Counters.S) :
314 Block.CTR with type key = Core.ekey and type ctr = Ctr.ctr
315
316 module GCM_of (Core : Block.Core) : Block.GCM
317 module CCM16_of (Core : Block.Core) : Block.CCM16
318end
319
320(** {1 Cipher instantiations} *)
321
322(** AES (128, 192, and 256-bit keys). *)
323module AES : sig
324 module Core : Block.Core
325 module ECB : Block.ECB
326 module CBC : Block.CBC
327 module CTR : Block.CTR with type ctr = int64 * int64
328 module GCM : Block.GCM
329 module CCM16 : Block.CCM16
330end
331
332(** Triple DES (168-bit key as 3 x 56-bit). *)
333module DES : sig
334 module Core : Block.Core
335 module ECB : Block.ECB
336 module CBC : Block.CBC
337 module CTR : Block.CTR with type ctr = int64
338end
339
340val accelerated : [ `XOR | `AES | `GHASH ] list
341(** [accelerated] is the list of hardware-accelerated operations detected at
342 startup. *)