AHash is the fastest, DOS resistant hash currently available in Rust. AHash is intended exclusively for use in in-memory hashmaps.
AHash's output is of high quality but aHash is not a cryptographically secure hash.
Because AHash is a keyed hash, each map will produce completely different hashes, which cannot be predicted without knowing the keys. This prevents DOS attacks where an attacker sends a large number of items whose hashes collide that get used as keys in a hashmap.
This also avoids accidentally quadratic behavior by reading from one map and writing to another.
AHash does not have a fixed standard for its output. This allows it to improve over time. For example, if any faster algorithm is found, aHash will be updated to incorporate the technique. Similarly, should any flaw in aHash's DOS resistance be found, aHash will be changed to correct the flaw.
Because it does not have a fixed standard, different computers or computers on different versions of the code will observe different hash values.
As such, aHash is not recommended for use other than in-memory maps. Specifically, aHash is not intended for network use or in applications which persist hashed values.
(In these cases HighwayHash
would be a better choice)
Additionally, aHash is not intended to be cryptographically secure and should not be used as a MAC, or anywhere which requires a cryptographically secure hash.
(In these cases SHA-3
would be a better choice)
AHash is a drop in replacement for the default implementation of the Hasher
trait. To construct a HashMap
using aHash
as its hasher do the following:
use ahash::{AHasher, RandomState};
use std::collections::HashMap;
let mut map: HashMap<i32, i32, RandomState> = HashMap::default();
map.insert(12, 34);
For convenience, wrappers called AHashMap
and AHashSet
are also provided.
These do the same thing with slightly less typing.
use ahash::AHashMap;
let mut map: AHashMap<i32, i32> = AHashMap::new();
map.insert(12, 34);
map.insert(56, 78);
The aHash package has the following flags:
std
: This enables features which require the standard library. (On by default) This includes providing the utility classesAHashMap
andAHashSet
.serde
: Enablesserde
support for the utility classesAHashMap
andAHashSet
.runtime-rng
: To obtain a seed for Hashers will obtain randomness from the operating system. (On by default) This is done using the getrandom crate.compile-time-rng
: For OS targets without access to a random number generator,compile-time-rng
provides an alternative. Ifgetrandom
is unavailable andcompile-time-rng
is enabled, aHash will generate random numbers at compile time and embed them in the binary. This allows for DOS resistance even if there is no random number generator available at runtime (assuming the compiled binary is not public). This makes the binary non-deterministic. (If non-determinism is a problem see constrandom's documentation)
If both runtime-rng
and compile-time-rng
are enabled the runtime-rng
will take precedence and compile-time-rng
will do nothing.
NOTE: If both runtime-rng
and compile-time-rng
a source of randomness may be provided by the application on startup
using the ahash::random_state::set_random_source method.
If neither flag is set and this is not done, aHash will fall back on using the numeric value of memory addresses as a source of randomness.
This is somewhat strong if ALSR is turned on (it is by default) but for embedded platforms this will result in weak keys.
As a result, it is recommended to use compile-time-rng
anytime random numbers will not be available at runtime.
A full comparison with other hashing algorithms can be found here
For a more representative performance comparison which includes the overhead of using a HashMap, see HashBrown's benchmarks as HashBrown now uses aHash as its hasher by default.
AHash passes the full SMHasher test suite.
The code to reproduce the result, and the full output are checked into the repo.
A separate FAQ document is maintained here. If you have questions not covered there, open an issue here.
Licensed under either of:
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.