1# aHash    2 3AHash is the [fastest](https://github.com/tkaitchuck/aHash/blob/master/compare/readme.md#Speed), 4[DOS resistant hash](https://github.com/tkaitchuck/aHash/wiki/How-aHash-is-resists-DOS-attacks) currently available in Rust. 5AHash is intended *exclusively* for use in in-memory hashmaps. 6 7AHash's output is of [high quality](https://github.com/tkaitchuck/aHash/blob/master/compare/readme.md#Quality) but aHash is **not** a cryptographically secure hash. 8 9## Design 10 11Because AHash is a keyed hash, each map will produce completely different hashes, which cannot be predicted without knowing the keys. 12[This prevents DOS attacks where an attacker sends a large number of items whose hashes collide that get used as keys in a hashmap.](https://github.com/tkaitchuck/aHash/wiki/How-aHash-is-resists-DOS-attacks) 13 14This also avoids [accidentally quadratic behavior by reading from one map and writing to another.](https://accidentallyquadratic.tumblr.com/post/153545455987/rust-hash-iteration-reinsertion) 15 16## Goals and Non-Goals 17 18AHash does *not* have a fixed standard for its output. This allows it to improve over time. For example, 19if any faster algorithm is found, aHash will be updated to incorporate the technique. 20Similarly, should any flaw in aHash's DOS resistance be found, aHash will be changed to correct the flaw. 21 22Because it does not have a fixed standard, different computers or computers on different versions of the code will observe different hash values. 23As 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. 24(In these cases `HighwayHash` would be a better choice) 25 26Additionally, aHash is not intended to be cryptographically secure and should not be used as a MAC, or anywhere which requires a cryptographically secure hash. 27(In these cases `SHA-3` would be a better choice) 28 29## Usage 30 31AHash is a drop in replacement for the default implementation of the `Hasher` trait. To construct a `HashMap` using aHash 32as its hasher do the following: 33 34```rust 35use ahash::{AHasher, RandomState}; 36use std::collections::HashMap; 37 38let mut map: HashMap<i32, i32, RandomState> = HashMap::default(); 39map.insert(12, 34); 40``` 41For convenience, wrappers called `AHashMap` and `AHashSet` are also provided. 42These do the same thing with slightly less typing. 43```rust 44use ahash::AHashMap; 45 46let mut map: AHashMap<i32, i32> = AHashMap::new(); 47map.insert(12, 34); 48map.insert(56, 78); 49``` 50 51## Flags 52 53The aHash package has the following flags: 54* `std`: This enables features which require the standard library. (On by default) This includes providing the utility classes `AHashMap` and `AHashSet`. 55* `serde`: Enables `serde` support for the utility classes `AHashMap` and `AHashSet`. 56* `compile-time-rng`: Whenever possible aHash will seed hashers with random numbers using the [getrandom](https://github.com/rust-random/getrandom) crate. 57This is possible for OS targets which provide a source of randomness. (see the [full list](https://docs.rs/getrandom/0.2.0/getrandom/#supported-targets).) 58For OS targets without access to a random number generator, `compile-time-rng` provides an alternative. 59If `getrandom` is unavailable and `compile-time-rng` is enabled, aHash will generate random numbers at compile time and embed them in the binary. 60This allows for DOS resistance even if there is no random number generator available at runtime (assuming the compiled binary is not public). 61This makes the binary non-deterministic, unless `getrandom` is available for the target in which case the flag does nothing. 62(If non-determinism is a problem see [constrandom's documentation](https://github.com/tkaitchuck/constrandom#deterministic-builds)) 63 64**NOTE:** If `getrandom` is unavailable and `compile-time-rng` is disabled aHash will fall back on using the numeric 65value of memory addresses as a source of randomness. This is somewhat strong if ALSR is turned on (it is by default) 66but for embedded platforms this will result in weak keys. As a result, it is recommended to use `compile-time-rng` anytime 67random numbers will not be available at runtime. 68 69## Comparison with other hashers 70 71A full comparison with other hashing algorithms can be found [here](https://github.com/tkaitchuck/aHash/blob/master/compare/readme.md) 72 73 74 75For a more representative performance comparison which includes the overhead of using a HashMap, see [HashBrown's benchmarks](https://github.com/rust-lang/hashbrown#performance) 76as HashBrown now uses aHash as its hasher by default. 77 78## Hash quality 79 80AHash passes the full [SMHasher test suite](https://github.com/rurban/smhasher). 81 82The code to reproduce the result, and the full output [are checked into the repo](https://github.com/tkaitchuck/aHash/tree/master/smhasher). 83 84## Additional FAQ 85 86A separate FAQ document is maintained [here](https://github.com/tkaitchuck/aHash/blob/master/FAQ.md). 87If you have questions not covered there, open an issue [here](https://github.com/tkaitchuck/aHash/issues). 88 89## License 90 91Licensed under either of: 92 93 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) 94 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) 95 96at your option. 97 98## Contribution 99 100Unless you explicitly state otherwise, any contribution intentionally submitted 101for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any 102additional terms or conditions. 103 104 105 106 107 108 109 110 111