Skip to content

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), or sha512 (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_sha256 or hmac_sha512 (RFC 2104). Check a MAC someone sent with equal_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) and sha1 (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.

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
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"
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
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"
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
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"
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
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"
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"
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"
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))
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"