README: rand is not a crypto library

[dhardy]

Closes #1358 by documenting what Rand is not.

Edit: the aims of this PR are to:

1. Clarify that rand is a community project without any legally-binding guarantees
2. Better document potential suitability of rand components where security/unpredictability are important

---

Edit no. 2 because more people are now seeing this.

rand contains no high-level cryptographic functionality, e.g. no encryption or signing support. It doesn't even contain a dedicated password generator (though you can pretty easily generate random strings with Alphanumeric).

For example, we've had people assume that ThreadRng had full fork protection (it previously offered a very limited form of fork protection which the docs were clear about to anyone who actually read them), then complain that it didn't function as expected. So now we've "resolved" this by removing all fork protection but adding some instructions to people who need it.

Further, various people expect cryptographic primitives to zero their contents on drop (zeroize). ThreadRng does not do this, and at this point it's unclear if it ever will (StdRng may do so in the future, but we can't guarantee that ThreadRng will, in part because of Rust's lack of guarantees about what happens on thread destruction). ThreadRng has always been a compromise between being an unpredictable generator and being fast (it also uses considerably more memory than something like SmallRng, though also far less than it did in the distant past).

I would prefer the project under-promise than over-promise when it comes to security. In particular, this means that anyone using rand's functionality in a security-sensitive context needs to do their homework: what are their requirements and is getrandom / OsRng / ThreadRng aka rand::rng() appropriate for the job?

[newpavlov]

I think it's worth to explicitly state that ThreadRng is suitable for generation of cryptographic material (keys, nonces, salts, seeds, etc.), but users should account for the listed security caveats and use OsRng when in doubt. It's also worth to add that ThreadRng does not provide forward secrecy guarantees in time between re-seedings.

[dhardy]

Updated.

Ultimately, I'm not comfortable with saying definitively that it is is suitable for XYZ. I attempted to document things such that users get the right message and can decide for themselves.

@tarcieri and @dcmiddle may have comments?

[dcmiddle]

Just curious.. is that because it's onerous to implement or causes a performance hit or something else?

[dhardy]

zeroize? It's just not been done (so far). It has been implemented by the chacha20 crate, so we gain this feature when we switch (with a little adjustment to ThreadRng).

[dcmiddle]

These are useful clarifications that address the substance of #1358. Thanks for working through these.

[dhardy]

Thanks for the review!

[vks]

Maybe we can recommend using getrandom directly if you need guarantees? Most crypto applications don't need a userspace CSPRNG, and I think this is what crypto libraries like ring do.

[dhardy]

Updated

[newpavlov]

The current text is broken:

Rand cannot provide any guarantees of security. which retrieves random data from (operating) system sources without a local memory buffer.

Also you already stated that "Rand is not a cryptographic library and cannot provide guarantees of security" in the first sentence of this paragraph, so here you have a needless duplication.

[benjamin-lieser]

In any case we should not forget to also update or remove the Security.md

[newpavlov]

The wording is a bit too conservative for my taste, but I guess it's fine.

Maybe we could move ThreadRng into a separate crate and use slightly less scary wording in it? This also could help cryptographic crates that would like to use ThreadRng, but do not want to pull the whole rand for it.

[newpavlov]

The current text is broken:

Rand cannot provide any guarantees of security. which retrieves random data from (operating) system sources without a local memory buffer.

Also you already stated that "Rand is not a cryptographic library and cannot provide guarantees of security" in the first sentence of this paragraph, so here you have a needless duplication.

[dhardy]

Are there specific cases where the wording is too conservative (besides the "cannot provide guarantees of security" disclaimer)?

We discussed moving ThreadRng to a different crate in the past and decided against it. Besides which, cryptographic libraries may benefit from things like low-bias range sampling.

[newpavlov]

besides the "cannot provide guarantees of security" disclaimer

It's a big disclaimer. Users may (rightfully) interpret it as "rand should not be used in cryptographic code".

Besides which, cryptographic libraries may benefit from things like low-bias range sampling.

I don't think so, at very least, I can not name a cryptographic library that depends on rand for this. In cryptographic code RNGs are primarily used to generate "raw bytes". Even when we need to generate random numbers (e.g. when working with elliptic curves), cryptographic libraries usually implement their own specialized sampling (e.g. see crypto_bigint::Random).

[dhardy]

Moving ThreadRng to its own crate is #716. Do you want to re-open it? At a glance, this new crate would need ReseedingRng and to depend on rand_core and whichever crate provides ChaCha, which is all reasonable enough. I'm still not convinced it's a very useful separation though.

Yes, it is a big disclaimer. Updated.

[vks]

In cryptographic code RNGs are primarily used to generate "raw bytes".

To my understanding, APIs like getrandom are used for this. Does anyone prefer a userspace CSPRNG for this use case? I guess I don't really see why Rand would be used in this context.

[tarcieri]

@vks though I generally prefer getrandom-style APIs, there are sometimes cases where the performance is inadequate

[newpavlov]

@vks
Cost of syscall may be noticeable in some cases, e.g. while frequently generating less critical cryptographic material such as nonces or salts. It's also more convenient to work with infallible "stateless" RNGs.

[dhardy]

So we're okay with this as-is? I updated again after @newpavlov's last comment on the disclaimer.

[dhardy]

Note to all who commented here: I've added another note to the opening post due to comments regarding the rand v0.9 release. See also reddit comments here.