README.md
1# Choosing A Hash Function
2
3> Note: this document is still very much a work-in-progress. Currently missing:
4> - recommendations for hashed containers
5> - recommendations for a better persistent hash
6> - recommendations for a secure hash
7
8If a hash function with unchanging output is needed, please select from one of
9the unchanging forever options below.
10
11## Non-cryptographic
12
13name | input | output | unchanging forever | notes
14---------------------------------------------|-----------------------------|------------|--------------------|-------
15[`Hash()`][hash] | overloaded | `uint32_t` | no | This function is currently being updated to return `size_t`.
16[`PersistentHash()`][persistenthash] | overloaded | `uint32_t` | yes | Fairly weak but widely used for persisted hashes.
17[`CityHash64()`][cityhash64] | `base::span<const uint8_t>` | `uint64_t` | yes (note 1) | Version 1.0.3. Has some known weaknesses.
18[`CityHash64WithSeed()`][cityhash64withseed] | `base::span<const uint8_t>` | `uint64_t` | yes (note 1) | Version 1.0.3. Has some known weaknesses.
19
20## Cryptographic
21
22**There are no hashes in `//base` that provide cryptographic security.**
23
24 name | input | output | unchanging forever | notes
25-------------------------------|---------------|---------------|--------------------|-------
26[`MD5String()`][md5string] | `std::string` | `std::string` | yes | **INSECURE**
27[`SHA1HashString`][sha1string] | `std::string` | `std::string` | yes | **INSECURE**
28
29## Deprecated
30
31> Note: CRC32, Murmur2, and Murmur3 will be listed here.
32
33Note 1: While CityHash is not guaranteed unchanging forever, the version used in
34Chrome is pinned to version 1.0.3.
35
36[hash]: https://cs.chromium.org/chromium/src/base/hash/hash.h?l=26
37[persistenthash]: https://cs.chromium.org/chromium/src/base/hash/hash.h?l=36
38[cityhash64]: https://cs.chromium.org/chromium/src/base/hash/city_v103.h?l=19
39[cityhash64withseed]: https://cs.chromium.org/chromium/src/base/hash/city_v103.h?l=20
40[md5string]: https://cs.chromium.org/chromium/src/base/hash/md5.h?l=74
41[sha1string]: https://cs.chromium.org/chromium/src/base/hash/sha1.h?l=22
42