random.wit

package wasi:[email protected];

/// The insecure-seed interface for seeding hash-map DoS resistance.
///
/// It is intended to be portable at least between Unix-family platforms and
/// Windows.
@since(version = 0.2.0)
interface insecure-seed {
  /// Return a 128-bit value that may contain a pseudo-random value.
  ///
  /// The returned value is not required to be computed from a CSPRNG, and may
  /// even be entirely deterministic. Host implementations are encouraged to
  /// provide pseudo-random values to any program exposed to
  /// attacker-controlled content, to enable DoS protection built into many
  /// languages' hash-map implementations.
  ///
  /// This function is intended to only be called once, by a source language
  /// to initialize Denial Of Service (DoS) protection in its hash-map
  /// implementation.
  ///
  /// # Expected future evolution
  ///
  /// This will likely be changed to a value import, to prevent it from being
  /// called multiple times and potentially used for purposes other than DoS
  /// protection.
  @since(version = 0.2.0)
  insecure-seed: func() -> tuple<u64, u64>;
}

/// The insecure interface for insecure pseudo-random numbers.
///
/// It is intended to be portable at least between Unix-family platforms and
/// Windows.
@since(version = 0.2.0)
interface insecure {
  /// Return `len` insecure pseudo-random bytes.
  ///
  /// This function is not cryptographically secure. Do not use it for
  /// anything related to security.
  ///
  /// There are no requirements on the values of the returned bytes, however
  /// implementations are encouraged to return evenly distributed values with
  /// a long period.
  @since(version = 0.2.0)
  get-insecure-random-bytes: func(len: u64) -> list<u8>;

  /// Return an insecure pseudo-random `u64` value.
  ///
  /// This function returns the same type of pseudo-random data as
  /// `get-insecure-random-bytes`, represented as a `u64`.
  @since(version = 0.2.0)
  get-insecure-random-u64: func() -> u64;
}

/// WASI Random is a random data API.
///
/// It is intended to be portable at least between Unix-family platforms and
/// Windows.
@since(version = 0.2.0)
interface random {
  /// Return `len` cryptographically-secure random or pseudo-random bytes.
  ///
  /// This function must produce data at least as cryptographically secure and
  /// fast as an adequately seeded cryptographically-secure pseudo-random
  /// number generator (CSPRNG). It must not block, from the perspective of
  /// the calling program, under any circumstances, including on the first
  /// request and on requests for numbers of bytes. The returned data must
  /// always be unpredictable.
  ///
  /// This function must always return fresh data. Deterministic environments
  /// must omit this function, rather than implementing it with deterministic
  /// data.
  @since(version = 0.2.0)
  get-random-bytes: func(len: u64) -> list<u8>;

  /// Return a cryptographically-secure random or pseudo-random `u64` value.
  ///
  /// This function returns the same type of data as `get-random-bytes`,
  /// represented as a `u64`.
  @since(version = 0.2.0)
  get-random-u64: func() -> u64;
}

@since(version = 0.2.0)
world imports {
  @since(version = 0.2.0)
  import random;
  @since(version = 0.2.0)
  import insecure;
  @since(version = 0.2.0)
  import insecure-seed;
}