1package wasi:[email protected];
2
3/// The insecure-seed interface for seeding hash-map DoS resistance.
4///
5/// It is intended to be portable at least between Unix-family platforms and
6/// Windows.
7@since(version = 0.2.0)
8interface insecure-seed {
9  /// Return a 128-bit value that may contain a pseudo-random value.
10  ///
11  /// The returned value is not required to be computed from a CSPRNG, and may
12  /// even be entirely deterministic. Host implementations are encouraged to
13  /// provide pseudo-random values to any program exposed to
14  /// attacker-controlled content, to enable DoS protection built into many
15  /// languages' hash-map implementations.
16  ///
17  /// This function is intended to only be called once, by a source language
18  /// to initialize Denial Of Service (DoS) protection in its hash-map
19  /// implementation.
20  ///
21  /// # Expected future evolution
22  ///
23  /// This will likely be changed to a value import, to prevent it from being
24  /// called multiple times and potentially used for purposes other than DoS
25  /// protection.
26  @since(version = 0.2.0)
27  insecure-seed: func() -> tuple<u64, u64>;
28}
29
30/// The insecure interface for insecure pseudo-random numbers.
31///
32/// It is intended to be portable at least between Unix-family platforms and
33/// Windows.
34@since(version = 0.2.0)
35interface insecure {
36  /// Return `len` insecure pseudo-random bytes.
37  ///
38  /// This function is not cryptographically secure. Do not use it for
39  /// anything related to security.
40  ///
41  /// There are no requirements on the values of the returned bytes, however
42  /// implementations are encouraged to return evenly distributed values with
43  /// a long period.
44  @since(version = 0.2.0)
45  get-insecure-random-bytes: func(len: u64) -> list<u8>;
46
47  /// Return an insecure pseudo-random `u64` value.
48  ///
49  /// This function returns the same type of pseudo-random data as
50  /// `get-insecure-random-bytes`, represented as a `u64`.
51  @since(version = 0.2.0)
52  get-insecure-random-u64: func() -> u64;
53}
54
55/// WASI Random is a random data API.
56///
57/// It is intended to be portable at least between Unix-family platforms and
58/// Windows.
59@since(version = 0.2.0)
60interface random {
61  /// Return `len` cryptographically-secure random or pseudo-random bytes.
62  ///
63  /// This function must produce data at least as cryptographically secure and
64  /// fast as an adequately seeded cryptographically-secure pseudo-random
65  /// number generator (CSPRNG). It must not block, from the perspective of
66  /// the calling program, under any circumstances, including on the first
67  /// request and on requests for numbers of bytes. The returned data must
68  /// always be unpredictable.
69  ///
70  /// This function must always return fresh data. Deterministic environments
71  /// must omit this function, rather than implementing it with deterministic
72  /// data.
73  @since(version = 0.2.0)
74  get-random-bytes: func(len: u64) -> list<u8>;
75
76  /// Return a cryptographically-secure random or pseudo-random `u64` value.
77  ///
78  /// This function returns the same type of data as `get-random-bytes`,
79  /// represented as a `u64`.
80  @since(version = 0.2.0)
81  get-random-u64: func() -> u64;
82}
83
84@since(version = 0.2.0)
85world imports {
86  @since(version = 0.2.0)
87  import random;
88  @since(version = 0.2.0)
89  import insecure;
90  @since(version = 0.2.0)
91  import insecure-seed;
92}
93