anil.recoil.org
forked from
gazagnaire.org/ocaml-crypto
upstream: https://github.com/mirage/mirage-crypto
Merge pull request #254 from hannesm/deprecate-rng-initialize
Mark the initialize functions as deprecated.
authored by
Hannes Mehnert
and committed by
GitHub
63dab445
dae47651
+6
-4
bench/speed.ml
+6
-4
bench/speed.ml
···
480
throughput_into name (fun dst cs -> DES.ECB.unsafe_encrypt_into ~key cs ~src_off:0 dst ~dst_off:0 (String.length cs))) ;
481
482
bm "fortuna" (fun name ->
483
-
Mirage_crypto_rng_unix.initialize (module Mirage_crypto_rng.Fortuna);
484
-
throughput name (fun buf ->
485
-
let buf = Bytes.unsafe_of_string buf in
486
-
Mirage_crypto_rng.generate_into buf ~off:0 (Bytes.length buf))) ;
487
488
bm "getentropy" (fun name ->
489
Mirage_crypto_rng_unix.use_getentropy ();
···
480
throughput_into name (fun dst cs -> DES.ECB.unsafe_encrypt_into ~key cs ~src_off:0 dst ~dst_off:0 (String.length cs))) ;
481
482
bm "fortuna" (fun name ->
483
+
begin[@alert "-deprecated"]
484
+
Mirage_crypto_rng_unix.initialize (module Mirage_crypto_rng.Fortuna);
485
+
throughput name (fun buf ->
486
+
let buf = Bytes.unsafe_of_string buf in
487
+
Mirage_crypto_rng.generate_into buf ~off:0 (Bytes.length buf))
488
+
end);
489
490
bm "getentropy" (fun name ->
491
Mirage_crypto_rng_unix.use_getentropy ();
+1
rng/async/mirage_crypto_rng_async.mli
+1
rng/async/mirage_crypto_rng_async.mli
+1
rng/eio/mirage_crypto_rng_eio.mli
+1
rng/eio/mirage_crypto_rng_eio.mli
+1
rng/lwt/mirage_crypto_rng_lwt.mli
+1
rng/lwt/mirage_crypto_rng_lwt.mli
+7
-14
rng/mirage_crypto_rng.mli
+7
-14
rng/mirage_crypto_rng.mli
···
23
Please ensure to call [Mirage_crypto_rng_unix.use_default], or
24
[Mirage_crypto_rng_unix.use_dev_urandom] (if you only want to use
25
/dev/urandom), or [Mirage_crypto_rng_unix.use_getentropy] (if you only want
26
-
to use getentropy).
27
28
For fine-grained control (doing entropy harvesting, etc.), please continue
29
-
reading the documentation below. {b Please be aware that the feeding of Fortuna
30
-
and producing random numbers is not thread-safe} (it is on Miou_unix via Pfortuna).
31
-
32
-
The RNGs here are merely the deterministic part of a full random number
33
-
generation suite. For proper operation, they need to be seeded with a
34
-
high-quality entropy source.
35
36
Suitable entropy feeding of generators are provided by other libraries
37
-
{{!Mirage_crypto_rng_lwt}mirage-crypto-rng-lwt} (for Lwt),
38
-
{{!Mirage_crypto_rng_async}mirage-crypto-rng-async} (for Async),
39
{{!Mirage_crypto_rng_mirage}mirage-crypto-rng-mirage} (for MirageOS),
40
-
{{!Mirage_crypto_rng_unix}mirage-crypto-rng.unix},
41
-
{{!Mirage_crypto_rng_eio}mirage-crypto-rng-eio} (for Eio),
42
and {{!Mirage_crypto_rng_miou_unix}mirage-crypto-miou-unix} (for Miou_unix).
43
44
The intention is that "initialize" in the respective sub-library is called
···
49
generator should be used in most setting, and that should be fed a constant
50
stream of entropy.
51
52
-
[mirage-crypto-rng-eio] package differs slightly from other rng packages.
53
-
Instead of the [initialize] function a [run] function is provided with
54
-
similar behaviour, i.e. RNG setup, entropy collection and periodic reseeding.
55
56
Although this module exposes a more fine-grained interface, e.g. allowing
57
manual seeding of generators, this is intended either for implementing
···
23
Please ensure to call [Mirage_crypto_rng_unix.use_default], or
24
[Mirage_crypto_rng_unix.use_dev_urandom] (if you only want to use
25
/dev/urandom), or [Mirage_crypto_rng_unix.use_getentropy] (if you only want
26
+
to use getrandom/getentropy/BCryptGenRandom).
27
28
For fine-grained control (doing entropy harvesting, etc.), please continue
29
+
reading the documentation below. {b Please be aware that the feeding of
30
+
Fortuna and producing random numbers is not thread-safe} (it is on Miou_unix
31
+
via Pfortuna).
32
33
Suitable entropy feeding of generators are provided by other libraries
34
{{!Mirage_crypto_rng_mirage}mirage-crypto-rng-mirage} (for MirageOS),
35
and {{!Mirage_crypto_rng_miou_unix}mirage-crypto-miou-unix} (for Miou_unix).
36
37
The intention is that "initialize" in the respective sub-library is called
···
42
generator should be used in most setting, and that should be fed a constant
43
stream of entropy.
44
45
+
The RNGs here are merely the deterministic part of a full random number
46
+
generation suite. For proper operation, they need to be seeded with a
47
+
high-quality entropy source.
48
49
Although this module exposes a more fine-grained interface, e.g. allowing
50
manual seeding of generators, this is intended either for implementing
+3
-13
rng/rng.ml
+3
-13
rng/rng.ml
···
16
\n If you are using MirageOS, use the random device in config.ml: \
17
`let main = Mirage.main \"Unikernel.Main\" (random @-> job)`, \
18
and `let () = register \"my_unikernel\" [main $ default_random]`. \
19
-
\n If you are using Lwt, execute \
20
-
`Mirage_crypto_rng_lwt.initialize (module Mirage_crypto_rng.Fortuna)` \
21
-
at startup. \
22
-
\n If you are using Async, execute \
23
-
`Mirage_crypto_rng_async.initialize (module Mirage_crypto_rng.Fortuna)` \
24
-
at startup. \
25
-
\n If you are using Eio, execute in one of the fibers \
26
-
`Mirage_crypto_rng_eio.run (module Fortuna) env` (`env` from `Eio_main.run`).
27
-
\n Otherwise, there is no periodic reseeding. For an initial seed from \
28
-
getrandom(), execute \
29
-
`Mirage_crypto_rng_unix.initialize (module Mirage_crypto_rng.Fortuna)`. \
30
-
You can use `Mirage_crypto_rng.accumulate` and `Mirage_crypto_rng.reseed` \
31
-
to reseed the RNG manually."
32
33
let () = Printexc.register_printer (function
34
| Unseeded_generator ->
···
16
\n If you are using MirageOS, use the random device in config.ml: \
17
`let main = Mirage.main \"Unikernel.Main\" (random @-> job)`, \
18
and `let () = register \"my_unikernel\" [main $ default_random]`. \
19
+
\n If you are using miou, execute \
20
+
`Mirage_crypto_rng_miou_unix.initialize (module Mirage_crypto_rng.Fortuna)` \
21
+
at startup."
22
23
let () = Printexc.register_printer (function
24
| Unseeded_generator ->
+1
rng/unix/mirage_crypto_rng_unix.mli
+1
rng/unix/mirage_crypto_rng_unix.mli
···
8
9
(** [initialize ~g rng] will bring the RNG into a working state. *)
10
val initialize : ?g:'a -> 'a Mirage_crypto_rng.generator -> unit
11
+
[@@deprecated "Use 'Mirage_crypto_rng_unix.use_default ()' instead."]
12
13
(** [getrandom size] returns a buffer of [size] filled with random bytes. *)
14
val getrandom : int -> string
+15
-13
tests/test_eio_entropy_collection.ml
+15
-13
tests/test_eio_entropy_collection.ml
···
20
21
let () =
22
Eio_main.run @@ fun env ->
23
-
Mirage_crypto_rng_eio.run (module Printing_rng) env @@ fun () ->
24
-
Eio.Fiber.both
25
-
begin fun () ->
26
-
let sleep = Duration.(of_sec 2 |> to_f) in
27
-
Eio.Time.sleep env#clock sleep
28
-
end
29
-
begin fun () ->
30
-
Format.printf "entropy sources: %a@,%!"
31
-
(fun ppf -> List.iter (fun x ->
32
-
Mirage_crypto_rng.Entropy.pp_source ppf x;
33
-
Format.pp_print_space ppf ()))
34
-
(Mirage_crypto_rng.Entropy.sources ())
35
-
end
36
···
20
21
let () =
22
Eio_main.run @@ fun env ->
23
+
begin[@alert "-deprecated"]
24
+
Mirage_crypto_rng_eio.run (module Printing_rng) env @@ fun () ->
25
+
Eio.Fiber.both
26
+
begin fun () ->
27
+
let sleep = Duration.(of_sec 2 |> to_f) in
28
+
Eio.Time.sleep env#clock sleep
29
+
end
30
+
begin fun () ->
31
+
Format.printf "entropy sources: %a@,%!"
32
+
(fun ppf -> List.iter (fun x ->
33
+
Mirage_crypto_rng.Entropy.pp_source ppf x;
34
+
Format.pp_print_space ppf ()))
35
+
(Mirage_crypto_rng.Entropy.sources ())
36
+
end
37
+
end
38
+9
-7
tests/test_eio_rng.ml
+9
-7
tests/test_eio_rng.ml
···
2
3
let () =
4
Eio_main.run @@ fun env ->
5
-
Mirage_crypto_rng_eio.run (module Fortuna) env @@ fun () ->
6
-
let random_num = Mirage_crypto_rng.generate 32 in
7
-
assert (String.length random_num = 32);
8
-
Printf.printf "32 bit random number: %S\n%!" random_num;
9
-
let random_num = Mirage_crypto_rng.generate 16 in
10
-
assert (String.length random_num = 16);
11
-
Printf.printf "16 bit random number: %S\n%!" random_num;
···
2
3
let () =
4
Eio_main.run @@ fun env ->
5
+
begin[@alert "-deprecated"]
6
+
Mirage_crypto_rng_eio.run (module Fortuna) env @@ fun () ->
7
+
let random_num = Mirage_crypto_rng.generate 32 in
8
+
assert (String.length random_num = 32);
9
+
Printf.printf "32 bit random number: %S\n%!" random_num;
10
+
let random_num = Mirage_crypto_rng.generate 16 in
11
+
assert (String.length random_num = 16);
12
+
Printf.printf "16 bit random number: %S\n%!" random_num;
13
+
end
+3
-1
tests/test_entropy_collection_async.ml
+3
-1
tests/test_entropy_collection_async.ml