Osrng doc #333
Osrng doc #333
Conversation
|
Rebased (and fixed spelling) |
| @@ -87,7 +87,6 @@ You may also find the [Update Guide](UPDATING.md) useful. | |||
| - Use widening multiply method for much faster integer range reduction. (#274) | |||
| - `Uniform` distributions for `bool` uses `Range`. (#274) | |||
| - `Uniform` distributions for `bool` uses sign test. (#274) | |||
| - Add `HighPrecision01` distribution. (#320) | |||
There was a problem hiding this comment.
Can we not assume #320 will land before 0.5?
There was a problem hiding this comment.
We can, but there is some open discussion around using a wrapper type, and adding range code. I now feel like it is better to land HighPrecision01 in combination with the range code, as that seems like the more common use. And I don't mind if that takes some longer to get right...
There was a problem hiding this comment.
Okay. I was only thinking that I don't want to make a release which removes functionality without a viable replacement, but there isn't really much removed that HighPrecision01 replaces (I was thinking about the change to gen() for floats, but nothing is actually missing).
src/os.rs
Outdated
| /// Platform sources: | ||
| /// Sometimes there is the misconception that `OsRng` somehow provides 'better' | ||
| /// random numbers than some good user-space cryptographic random number | ||
| /// generator. This is not true, but `OsRng` has a role in initializing such an |
There was a problem hiding this comment.
This is a very incomplete note on the topic; it would be better just to refer to elsewhere (e.g. the doc I wrote, or maybe we should refer to an external article on the topic specific to our Rand lib).
There was a problem hiding this comment.
My goal was mostly to say that CSPRNG's generate values that can be just as good as those from OsRng, but I can see what you mean. There may be other considerations. I did a second try at this paragraph.
If it is not yet really what you have in mind, can you make a suggestion?
| /// Note: many Unix systems provide `/dev/random` as well as `/dev/urandom`. | ||
| /// On all modern systems these two interfaces offer identical quality, with | ||
| /// the difference that on some systems `/dev/random` may block. This is a | ||
| /// dated design, and `/dev/urandom` is preferred by cryptography experts. [1] |
There was a problem hiding this comment.
The urandom man page on my system still mentions:
When read during early boot time, /dev/urandom may return data prior to the entropy pool being initialized.
You noted wanting to fix this in #332; I don't know that we should remove all doc about this vulnerability before then however (although in practice it only affects things like systemd).
There was a problem hiding this comment.
With #338 this is fixed on our side.
src/os.rs
Outdated
| /// the operating system. | ||
| /// A random number generator that retrieves randomness straight from the | ||
| /// operating system. This is the preferred external source of randomness for | ||
| /// most applications. Commonly it is used to initialize a user-space RNG, which |
There was a problem hiding this comment.
I still don't think the guidance about what to use this for / which RNG is 'better' belongs here at all. (I'm thinking of moving the doc about crypto-stuff from lib.rs to the README; we can reference that.)
The note about EntropyRng and details like not blocking and how this interfaces with the OS make sense.
I think we should also add a note that OsRng::new() is guaranteed to be very cheap (after first successful call), and will never consume more than one file handle per process.
There was a problem hiding this comment.
Removed the paragraph and added a bit about OsRng::new().
There was a problem hiding this comment.
Also the bit about this is the preferred source of randomness — I presume you mean entropy source, but it could also be read to mean preferred way to get each new random value.
There was a problem hiding this comment.
😢 And I already don't like writing documentation 😄.
|
Okay, I'm finally happy with this PR! I'll let you merge in the morning if you think it's ready. |
Based on top of #328.
I took a stab at improving the documentation of
OsRng.Somewhere in a long paragraph it mentioned the problem with
/dev/urandomduring early boot. Instead of making things complicated for users, I think this is something we can handle, especially now that we only keep a single handle to/dev/urandomopen. Opened #332 for that and other possible improvements toOsRng.Also updated the changelog with
SecRandomCopyBytes(#322), #321 (comment), and removedHighPrecision01(maybe want to think things through a bit more for that one?).