README
Tr
Source
- ::equalUnavailable::equal
- ::not_equalUnavailable::not_equal
- ::outputUnavailable::output
- ::to_reprUnavailable::to_repr
- ::to_stringUnavailable::to_string
- ::fillReplay::fill
- ::newReplay::new
- ::remainingReplay::remaining
V
below
V
bytes
V
scalar

moonseed

Secure random bytes and unbiased sampling for MoonBit; never a seeded generator.

random

entropy

csprng

crypto

moonbit

Download zip

Author

moonbitstack

Version

0.1.0

License

Apache-2.0

Repository

github.com/moonbitstack/moonseed

Last updated

18 hours ago

Downloads

308

No dependencies

moonseed

test "draw" {
  let key = @moonseed.bytes(32, @system.source) // 32 uniform bytes
  let n = @moonseed.below(b"\x03\xe8", @system.source) // uniform in [0, 1000)
  let d = @moonseed.scalar(b"\x05", @system.source) // uniform in [1, 4]
  ignore((key, n, d))
}

moon run src/examples/tour shows all of it in one run.

#Packages

Package	What it holds	Depends on
moonseed	Source, Unavailable, bytes, below, scalar, Replay	nothing
moonseed/system	source, the platform's entropy	core env

The root package touches no platform. Linking system links the platform's call, which on wasm is the WASI random_get import; a program for a wasm host without WASI uses the root package with a source of its own.

#Sources

Source	Where the bytes come from
@system.source	crypto.getRandomValues on JavaScript, WASI random_get on wasm and wasm-gc, the runtime on native
Replay::new(bytes)	the bytes given, in order; exhausted after
your own	anything that implements Source

struct Device {}

impl @moonseed.Source for Device with fn fill(_self, _buf) {
  raise Failed("the device is unplugged")
}

No source falls back to a seeded generator. When there are no bytes to be had, the call raises Unavailable: Platform from the platform source, Exhausted from a replay, Failed(reason) from a source of your own. A key drawn from a fallback looks like any other key and is guessable, so the failure is the caller's to see.

#Replaying bytes

Replay hands out the bytes it was built from, in order, and then raises Exhausted. A test pins a draw with it, and a vector written elsewhere replays through it byte for byte.

test "replay" {
  let source = @moonseed.Replay::new(b"\x07\xff\x02")
  assert_eq(@moonseed.below(b"\x0a", source), b"\x07")
  // 0xff is 15 once the high bits are cleared, too big, so the next byte is drawn.
  assert_eq(@moonseed.below(b"\x0a", source), b"\x02")
  assert_eq(source.remaining(), 0)
  let refused = try {
    ignore(@moonseed.below(b"\x0a", source))
    false
  } catch {
    Exhausted => true
    _ => false
  }
  assert_true(refused)
}

#Sampling

below(bound, source) reads bound as a big-endian number and returns one in [0, bound), as wide as bound. It draws as many bytes as bound - 1 needs, clears the unused high bits of the first, and draws again while the value is at or above bound. Every value is equally likely; reducing a wider draw modulo bound would favour the small ones.

scalar(order, source) returns a value in [1, order - 1], as wide as order: a private key or a nonce for a group of that order. It draws as FIPS 186-5 A.2.2 says: the leftmost bits of a draw as long as order, drawn again while the value is zero or not below order. A P-521 scalar is 66 bytes with the top bits clear, which is why this is not "ask for 32 bytes".

#Licence

Apache-2.0.

Source

source

pub(open) trait Source {
  fn fill(Self, FixedArray[Byte]) -> Unit raise Unavailable
}

Where random bytes come from: Rust's RngCore::try_fill_bytes. The platform's source is @system.source; a program implements this for a hardware source, a service, or a fixed sequence in its tests.

Unavailable

source

pub(all) suberror Unavailable {
  Platform
  Exhausted
  Failed(String)
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

No random bytes could be had. There is no fallback to a seeded generator: a caller that needs entropy and gets none stops here.

impl Show for Unavailable

Unavailable::equal

source

fn Unavailable::equal(Unavailable, Unavailable) -> Bool

Unavailable::not_equal

source

fn Unavailable::not_equal(x : Unavailable, y : Unavailable) -> Bool

Unavailable::output

source

fn Unavailable::output(self : Unavailable, logger : &Logger) -> Unit

Unavailable::to_repr

source

fn Unavailable::to_repr(Unavailable) -> @moonbitlang/core/debug.Repr
Repr

Unavailable::to_string

source

fn Unavailable::to_string(self : Unavailable) -> String

Replay

source

pub struct Replay {
  // private fields
}

A source that hands out the bytes it was given, in order, and is exhausted after: the fixed randomness of a test vector, or a test that walks every branch of a rejection loop.

impl Source for Replay

Replay::fill

source

fn Replay::fill(self : Replay, buf : FixedArray[Byte]) -> Unit raise Unavailable

Replay::new

source

fn Replay::new(data : Bytes) -> Replay

Replay::remaining

source

fn Replay::remaining(self : Replay) -> Int

How many bytes are left to give.

below

source

fn[S : Source] below(bound : BytesView, source : S) -> Bytes raise Unavailable

A uniform number in [0, bound), both big-endian and as wide as bound, drawn as Go's crypto/rand.Int draws it and from the same bytes: as many bytes as bound - 1 needs, the unused high bits of the first cleared, drawn again while the value is at or above bound. No value is likelier than another; reducing a wider draw modulo bound would favour the small ones. A bound of 1 reads nothing. Aborts when bound is zero.

bytes

source

fn[S : Source] bytes(n : Int, source : S) -> Bytes raise Unavailable

n uniform random bytes: Go's rand.Read, Python's secrets.token_bytes. Aborts on a negative n.

scalar

source

fn[S : Source] scalar(order : BytesView, source : S) -> Bytes raise Unavailable

A uniform number in [1, order - 1], as wide as order: the private key or nonce of a group of that order, drawn as FIPS 186-5 A.2.2 and Go's ECDSA draw it and from the same bytes: the leftmost bits of a draw as long as order, drawn again while the value is zero or at or above order. Aborts when order is below 2.