mc-rand

Crates.iomc-rand
lib.rsmc-rand
version1.1.0
sourcesrc
created_at2023-03-25 17:33:31.380897
updated_at2023-03-27 17:31:16.833005
descriptionA platform abstraction layer providing a cryptographic RNG, `McRng`
homepage
repositoryhttps://github.com/mobilecoinfoundation/rand
max_upload_size
id820416
size55,602
Eran Rundstein (eranrund)

documentation

README

mc-rand

Project ChatLicenseArchitecture: anyCrates.ioDocs StatusDependency StatusCodeCov StatusGitHub Workflow StatusContributor Covenant

A platform abstraction layer providing a cryptographic RNG, McRng.

Example usage

Example usage:

use mc_rand::{McRng, RngCore}

pub fn my_func() -> (u64, u64) {
    let mut rng = McRng::default();
    let k0 = rng.next_u64();
    let k1 = rng.next_u64();
    (k0, k1)
}

What it does

This project has evolved considerably as cargo has gotten more bug fixes and features.

Today, what it does is:

  • On targets with CPU feature rdrand, McRng resolves to RdRandRng, which uses CPU intrinsics to call RDRAND directly. This implementation was audited by NCC group.
  • When this feature is not present, but the target_arch is wasm_32, McRng resolves to OsRng from rand crate. (This is because ThreadRng is not available in wasm.)
  • When neither of these is the case, McRng resolves to ThreadRng. (ThreadRng is the generically recommendable cryptographic RNG on major rust platforms.)

On targets with rdrand, this crate does not pull in the standard library. On targets without rdrand, the feature rand/std will be enabled.

Motivation

McRng was created initially because MobileCoin builds SGX enclave software in a strict no_std environment. Enclaves are generally supposed to get randomness from the CPU via RDRAND and not from the OS, because the OS is untrusted in the SGX security model.

This creates the following needs:

  • An RNG needs to exist in enclave implementations which resolves to RDRAND.
  • Ideally the same RNG also works in unit-test builds of the enclave-impl crate without further configuration if you are working on x86.
  • Some libraries are meant to be consumed both by enclaves in servers, and in clients, which may not be x86. See e.g. "common" crate, which also provided a hashmap for use in the enclave and out of the enclave, and which requires randomness to avoid HASH-DOS.
  • Four years ago, before the resolver = 2 innovation, cargo would unify features across build-dependencies and target dependencies, so if anything in your build.rs pulled in rand then you would get the standard library, which made common libraries like rand toxic to our enclave builds.

We wanted to have an RNG type that any of these users can consume, that will be secure and do the right thing on each platform without requiring explicit configuration or other toil from developers.

Because none of the existing RNG libraries quite provided this, we made mc-rand.

Future directions

McRng fills a niche that isn't quite filled by OsRng or ThreadRng or other popular crates, and has been audited and battle-tested in production for years.

Feel free to use mc-rand knowing that it will usually do the right thing:

  • When working on x86 on enclave implementations, it's great, because your cargo tests and benchmarks will use the same implementation that your code will use in production.
  • On other targets, it will still use the most generally recommendable crypographic RNG for that platform.

As other targets arise that are of interest, we are happy to improve support for them.

Commit count: 8

cargo fmt