From e36c7da56c74368881b02a4bbf1f740714083c65 Mon Sep 17 00:00:00 2001 From: Dirk Gadsden Date: Sun, 6 Mar 2016 19:13:29 -0800 Subject: [PATCH 1/3] Clarify documentation of `hash::SipHasher` The docs were making assertions/recommendations they shouldn't have. This clarifies them and adds some helpful links. Fixes #32043. --- src/libcore/hash/sip.rs | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/src/libcore/hash/sip.rs b/src/libcore/hash/sip.rs index 722d77a8a11ef..b1aab4c693de5 100644 --- a/src/libcore/hash/sip.rs +++ b/src/libcore/hash/sip.rs @@ -19,15 +19,18 @@ use super::Hasher; /// /// See: http://131002.net/siphash/ /// -/// Consider this as a main "general-purpose" hash for all hashtables: it -/// runs at good speed (competitive with spooky and city) and permits -/// strong _keyed_ hashing. Key your hashtables from a strong RNG, -/// such as `rand::Rng`. +/// This is the default hashing function used by standard library (eg. +/// `collections::HashMap` uses it by default). +/// +/// SipHash is a general-purpose hashing function: it runs at a good +/// speed (competitive with Spooky and City) and permits strong _keyed_ +/// hashing. This lets you key your hashtables from a strong RNG, such +/// as [`rand::Rng`](https://doc.rust-lang.org/rand/rand/trait.Rng.html). /// /// Although the SipHash algorithm is considered to be cryptographically /// strong, this implementation has not been reviewed for such purposes. -/// As such, all cryptographic uses of this implementation are strongly -/// discouraged. +/// As such, all cryptographic uses of this implementation are _strongly +/// discouraged_. #[stable(feature = "rust1", since = "1.0.0")] pub struct SipHasher { k0: u64, From 054196d1d9b5e932e5a2dd69b77d9210e26b95b5 Mon Sep 17 00:00:00 2001 From: Dirk Gadsden Date: Sun, 6 Mar 2016 19:32:19 -0800 Subject: [PATCH 2/3] Amend `hash::SipHasher` docs to more strongly discourage cryptographic uses --- src/libcore/hash/sip.rs | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/libcore/hash/sip.rs b/src/libcore/hash/sip.rs index b1aab4c693de5..3a6686770f6e6 100644 --- a/src/libcore/hash/sip.rs +++ b/src/libcore/hash/sip.rs @@ -27,10 +27,9 @@ use super::Hasher; /// hashing. This lets you key your hashtables from a strong RNG, such /// as [`rand::Rng`](https://doc.rust-lang.org/rand/rand/trait.Rng.html). /// -/// Although the SipHash algorithm is considered to be cryptographically -/// strong, this implementation has not been reviewed for such purposes. -/// As such, all cryptographic uses of this implementation are _strongly -/// discouraged_. +/// Although the SipHash algorithm is considered to be generally strong, +/// it is not intended for cryptographic purposes. As such, all +/// cryptographic uses of this implementation are _strongly discouraged_. #[stable(feature = "rust1", since = "1.0.0")] pub struct SipHasher { k0: u64, From 46dc35e4772e892bf1be04fa01767e0ec00ffe2f Mon Sep 17 00:00:00 2001 From: Dirk Gadsden Date: Tue, 8 Mar 2016 21:52:44 -0800 Subject: [PATCH 3/3] Link to actual CSPRNG in `hash::SipHasher` documentation --- src/libcore/hash/sip.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/libcore/hash/sip.rs b/src/libcore/hash/sip.rs index 3a6686770f6e6..342071f1b51b7 100644 --- a/src/libcore/hash/sip.rs +++ b/src/libcore/hash/sip.rs @@ -19,13 +19,13 @@ use super::Hasher; /// /// See: http://131002.net/siphash/ /// -/// This is the default hashing function used by standard library (eg. -/// `collections::HashMap` uses it by default). +/// This is currently the default hashing function used by standard library +/// (eg. `collections::HashMap` uses it by default). /// /// SipHash is a general-purpose hashing function: it runs at a good /// speed (competitive with Spooky and City) and permits strong _keyed_ -/// hashing. This lets you key your hashtables from a strong RNG, such -/// as [`rand::Rng`](https://doc.rust-lang.org/rand/rand/trait.Rng.html). +/// hashing. This lets you key your hashtables from a strong RNG, such as +/// [`rand::os::OsRng`](https://doc.rust-lang.org/rand/rand/os/struct.OsRng.html). /// /// Although the SipHash algorithm is considered to be generally strong, /// it is not intended for cryptographic purposes. As such, all