std::hash
Cryptographic hashes and message authentication codes over bytes. Each
digest function returns the digest’s bytes, and its _hex form the
lowercase hexadecimal digits that sha256sum and its kin print, the form
a digest is usually written down in. Hash text as its UTF-8 bytes:
digest = hash.sha256_hex(String.to_bytes("abc"))
Which one to use:
- To tell whether data changed, or to name it by its content:
sha256(32 bytes), orsha512(64 bytes) when a format asks for it. Both are SHA-2 (FIPS 180-4). - To sign a message or a token so that only a holder of the key can make
or check it:
hmac_sha256orhmac_sha512(RFC 2104). Check a MAC someone sent withequal_in_constant_time, never==, which returns as soon as a byte differs and so tells an attacker how much of a forgery was right. - To stretch a password or passphrase into a key:
pbkdf2_sha256(RFC 8018). To store a password for logging in, use std::passwords, which salts it and records how it was hashed. - To match a format that names an older hash:
md5(ETags, legacy checksums) andsha1(Git object names). Both are broken for security, since inputs with the same digest can be made, so never use them to check data someone else could have chosen.
None of these is for storing passwords. They are fast by design, which lets an attacker who has the digests guess billions of passwords a second. Store a password with std::passwords, which is slow on purpose.
Every function here is pure, so a typed literal’s handler may call them,
except pbkdf2_sha256, whose cost is its iteration count.
Import with import std::hash.
hash.sha256
Section titled “hash.sha256”fn sha256(data: Bytes) -> Bytes
The SHA-256 digest of data: 32 bytes.
import std::hash
assert Bytes.length(hash.sha256(String.to_bytes(""))) == 32
hash.sha256_hex
Section titled “hash.sha256_hex”fn sha256_hex(data: Bytes) -> String
The SHA-256 digest of data as 64 lowercase hexadecimal digits.
import std::hash
assert hash.sha256_hex(String.to_bytes(""))
== "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
assert hash.sha256_hex(String.to_bytes("abc"))
== "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
hash.sha512
Section titled “hash.sha512”fn sha512(data: Bytes) -> Bytes
The SHA-512 digest of data: 64 bytes.
import std::hash
assert Bytes.length(hash.sha512(String.to_bytes(""))) == 64
hash.sha512_hex
Section titled “hash.sha512_hex”fn sha512_hex(data: Bytes) -> String
The SHA-512 digest of data as 128 lowercase hexadecimal digits.
import std::hash
assert hash.sha512_hex(
String.to_bytes("")
) == "cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e"
assert hash.sha512_hex(
String.to_bytes("abc")
) == "ddaf35a193617abacc417349ae20413112e6fa4e89a97ea20a9eeee64b55d39a2192992a274fc1a836ba3c23a3feebbd454d4423643ce80e2a9ac94fa54ca49f"
hash.md5
Section titled “hash.md5”fn md5(data: Bytes) -> Bytes
The MD5 digest of data: 16 bytes (RFC 1321). MD5 is here for formats
that still name it, such as ETags, legacy checksums and Gravatar’s
original URLs. It is broken for security, since anyone can make two
inputs with the same digest; to tell whether data was changed, use
sha256, and to sign it, hmac_sha256.
import std::hash
assert Bytes.length(hash.md5(String.to_bytes(""))) == 16
hash.md5_hex
Section titled “hash.md5_hex”fn md5_hex(data: Bytes) -> String
The MD5 digest of data as 32 lowercase hexadecimal digits, the form
md5sum prints. Not for security; see md5.
import std::hash
// RFC 1321, appendix A.5.
assert hash.md5_hex(String.to_bytes("")) == "d41d8cd98f00b204e9800998ecf8427e"
assert hash.md5_hex(String.to_bytes("abc")) == "900150983cd24fb0d6963f7d28e17f72"
assert hash.md5_hex(String.to_bytes("message digest")) == "f96b697d7cb7938d525a2f31aaf161d0"
import std::hash
// A Gravatar URL can name the MD5 of the trimmed, lowercased email.
email = " Ada@Example.com "
key = email |> String.trim() |> String.lowercase() |> String.to_bytes() |> hash.md5_hex()
assert key == "3e3417d7ef77d5932a6734b916515ed5"
hash.sha1
Section titled “hash.sha1”fn sha1(data: Bytes) -> Bytes
The SHA-1 digest of data: 20 bytes (FIPS 180-4). SHA-1 is here for
formats that still name it, such as Git object names and older
checksums. It is broken for security, since two inputs with the same
digest have been made; to tell whether data was changed, use sha256.
import std::hash
assert Bytes.length(hash.sha1(String.to_bytes(""))) == 20
hash.sha1_hex
Section titled “hash.sha1_hex”fn sha1_hex(data: Bytes) -> String
The SHA-1 digest of data as 40 lowercase hexadecimal digits, the form
sha1sum prints. Not for security; see sha1.
import std::hash
// FIPS 180 examples.
assert hash.sha1_hex(String.to_bytes("")) == "da39a3ee5e6b4b0d3255bfef95601890afd80709"
assert hash.sha1_hex(String.to_bytes("abc")) == "a9993e364706816aba3e25717850c26c9cd0d89d"
assert hash.sha1_hex(String.to_bytes("abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq"))
== "84983e441c3bd26ebaae4aa1f95129e5e54670f1"
hash.hmac_sha256
Section titled “hash.hmac_sha256”fn hmac_sha256(key: Bytes, data: Bytes) -> Bytes
The HMAC-SHA256 of data under key (RFC 2104): 32 bytes. The same
key and data always give the same MAC, and a different key a different
one.
import std::hash
message = String.to_bytes("order 42")
mac = hash.hmac_sha256(String.to_bytes("key"), message)
assert Bytes.length(mac) == 32
assert mac == hash.hmac_sha256(String.to_bytes("key"), message)
assert mac != hash.hmac_sha256(String.to_bytes("other key"), message)
import std::hash
import std::hex
// RFC 4231, test cases 1 and 2.
key = hex.decode("0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b")!
assert hex.encode(hash.hmac_sha256(key, String.to_bytes("Hi There")))
== "b0344c61d8db38535ca8afceaf0bf12b881dc200c9833da726e9376c2e32cff7"
jefe = String.to_bytes("Jefe")
question = String.to_bytes("what do ya want for nothing?")
assert hex.encode(hash.hmac_sha256(jefe, question))
== "5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843"
hash.hmac_sha512
Section titled “hash.hmac_sha512”fn hmac_sha512(key: Bytes, data: Bytes) -> Bytes
The HMAC-SHA512 of data under key (RFC 2104): 64 bytes.
import std::hash
mac = hash.hmac_sha512(String.to_bytes("key"), String.to_bytes("order 42"))
assert Bytes.length(mac) == 64
import std::hash
import std::hex
// RFC 4231, test cases 1 and 2.
key = hex.decode("0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b")!
assert hex.encode(
hash.hmac_sha512(key, String.to_bytes("Hi There"))
) == "87aa7cdea5ef619d4ff0b4241a1d6cb02379f4e2ce4ec2787ad0b30545e17cdedaa833b7d6b8a702038b274eaea3f4e4be9d914eeb61f1702e696c203a126854"
jefe = String.to_bytes("Jefe")
question = String.to_bytes("what do ya want for nothing?")
assert hex.encode(
hash.hmac_sha512(jefe, question)
) == "164b7a7bfcf819e2e395fbe73b56e0a387bd64222e831fd610270cd7ea2505549758bf75c05a994a6d034f65f8f0e6fdcaeab1a34d4a6b4b636e070a38bce737"
hash.equal_in_constant_time
Section titled “hash.equal_in_constant_time”fn equal_in_constant_time(a: Bytes, b: Bytes) -> Bool
Whether a and b hold the same bytes, in a time that depends only on
their lengths. Compare a MAC or a token with this, not ==: == stops at
the first byte that differs, and its timing tells an attacker how many
leading bytes of a guess were right.
import std::hash
key = String.to_bytes("key")
sent = hash.hmac_sha256(key, String.to_bytes("order 42"))
assert hash.equal_in_constant_time(sent, hash.hmac_sha256(key, String.to_bytes("order 42")))
refute hash.equal_in_constant_time(sent, hash.hmac_sha256(key, String.to_bytes("order 43")))
refute hash.equal_in_constant_time(sent, Bytes.slice(sent, 0, 16))
hash.pbkdf2_sha256
Section titled “hash.pbkdf2_sha256”fn pbkdf2_sha256(password: Bytes, salt: Bytes, iterations: PositiveInt, length: PositiveInt) -> Bytes
PBKDF2 with HMAC-SHA256 (RFC 8018): a key length bytes long derived
from password and salt by iterations rounds of HMAC-SHA256. Each
round costs the same, so the count sets how long a guess takes. Both
counts are PositiveInts, and every 32 bytes of length past the first
32 cost iterations more rounds. To store a password, use
std::passwords, which picks the salt and the count and records both.
import std::hash
import std::hex
// RFC 7914, section 11.
key = hash.pbkdf2_sha256(String.to_bytes("passwd"), String.to_bytes("salt"), 1, 64)
assert hex.encode(
key
) == "55ac046e56e3089fec1691c22544b605f94185216dde0465e68b9d57c20dacbc49ca9cccf179b645991664b39d77ef317c71b845b1e30bd509112041d3a19783"
slow = hash.pbkdf2_sha256(String.to_bytes("Password"), String.to_bytes("NaCl"), 80_000, 64)
assert hex.encode(
slow
) == "4ddcd8f60b98be21830cee5ef22701f9641a4418d04c0414aeff08876b34ab56a1d425a1225833549adb841b51c9b3176a272bdebba1d078478f62b397f33c8d"