crypto
SHA and MD5 digests, HMAC signatures, secure random numbers and password hashing.
import crypto
This package has the basic cryptography tools, written in Salam: the SHA-1, SHA-2 and MD5 digests, HMAC, PBKDF2 password hashing, a constant time comparison and secure random bytes from the operating system. It covers hashing, signing and secrets; it does not encrypt. For encryption (AES-GCM, ChaCha20-Poly1305, key exchange) use tls, and for signed tokens that carry claims jwt.
Most functions come in three shapes: ...Hex takes a str and returns hex text, the simplest; ...Bytes and ...Raw write the raw digest into memory you allocate; and Sha256New, Sha256Update, Sha256Final hash data that arrives in pieces.
Things to get right:
HashPassworduses only 1000 PBKDF2 rounds. That is far below current advice (OWASP asks for 600,000 with SHA-256). For new systems build the same string with more rounds, as the second section shows;VerifyPasswordreads the rounds from the stored string, so both kinds keep working.- Compare secrets with
SecretEquals, never with==. - A
strstops at the first zero byte. For binary data or a binary key, use the...Bytesand...Rawforms with a pointer and a length;Sha256Hexof a buffer that contains a zero hashes only the part before it. HashStr,HashBytesandHashIntare fast hash table hashes, not cryptographic ones; MD5 and SHA-1 are only for old systems that require them.
Storing passwords
A login system keeps one string per user: the output of HashPassword. It has four fields separated by $: the algorithm, the number of PBKDF2 rounds, a random salt and the derived key. Because the salt is new every time, two users with the same password get different strings, and a leaked table cannot be attacked with one precomputed list. At login, VerifyPassword reads the rounds and the salt back out of the stored string, so the stored value is all you need to keep.
import crypto
import str
struct User:
pub name: str = ""
pub hash: str = ""
end
func register(users &: Vector<User>, name: str, password: str):
users.Push(User { name = name, hash = crypto.HashPassword(password) })
end
func login(users: Vector<User>, name: str, password: str): bool:
each u in users:
if u.name == name:
ret crypto.VerifyPassword(password, u.hash)
end
end
ret false
end
func main:
mut users := Vector {} as Vector<User>
register(users, "sara", "correct horse battery")
register(users, "omid", "correct horse battery")
parts := str.Split(users.Get(0).hash, "$")
println "stored fields:", parts.Len(), "algorithm:", parts.Get(0), "rounds:", parts.Get(1)
println "same password, same hash?", users.Get(0).hash == users.Get(1).hash
println "sara right password:", login(users, "sara", "correct horse battery")
println "sara wrong password:", login(users, "sara", "correct horse")
println "unknown user:", login(users, "nobody", "x")
endAnswer "wrong user" and "wrong password" with the same message, so that a visitor cannot use the login form to find out which accounts exist.
More rounds, and upgrading old hashes
The cost of a password hash is the number of rounds: every guess an attacker tries costs the same work as one login. Pbkdf2HmacSha256Hex takes the round count, so a stronger hash is the same four-field string as HashPassword writes, built by hand with 600,000 rounds. Existing users do not have to reset anything. At their next successful login the program sees that the stored hash has fewer rounds than the target and stores a new one, made from the password they just typed.
import crypto
import str
const ROUNDS := 600000
func strong_hash(password: str): str:
salt := crypto.RandomHex(16)
ret "pbkdf2-sha256$" + ROUNDS + "$" + salt + "$" + crypto.Pbkdf2HmacSha256Hex(password, salt, ROUNDS, 32)
end
func rounds_of(stored: str): int:
ret str.Split(stored, "$").Get(1).ToInt()
end
func login(stored &: str, password: str): bool:
if not crypto.VerifyPassword(password, stored): ret false end
if rounds_of(stored) < ROUNDS:
stored = strong_hash(password)
println " upgraded the stored hash to", rounds_of(stored), "rounds"
end
ret true
end
func main:
mut stored := crypto.HashPassword("tea at five")
println "HashPassword uses", rounds_of(stored), "rounds"
println "login:", login(stored, "tea at five")
println "login again:", login(stored, "tea at five")
println "wrong password:", login(stored, "coffee at six")
end600,000 rounds take a noticeable fraction of a second, which is the point, but it also means a login endpoint should be rate limited, or many parallel login attempts can keep the server busy.
Checking a webhook signature
Payment providers, GitHub and most other services sign the requests they send you. They compute an HMAC of the raw body with a secret you both know and put it in a header. To check it, compute the same HMAC over the body exactly as it arrived and compare. Compare with SecretEquals, never with ==: == stops at the first different character, and the time that takes tells an attacker how much of a forged signature was right.
import crypto
func verify(secret: str, body: str, header: str): bool:
expected := "sha256=" + crypto.HmacSha256Hex(secret, body)
ret crypto.SecretEquals(expected, header)
end
func main:
secret := "whsec_4f9a1c"
body := "{\"event\":\"order.paid\",\"id\":1042}"
header := "sha256=" + crypto.HmacSha256Hex(secret, body)
println "signature: " + header
println "genuine request:", verify(secret, body, header)
println "changed body:", verify(secret, "{\"event\":\"order.paid\",\"id\":9999}", header)
println "wrong secret:", verify("guess", body, header)
endSign the bytes you received, not a version you decoded and encoded again: a JSON library may reorder keys or change spaces, and then the signature no longer matches.
Checksums of large data
Sha256Hex needs the whole text at once. For a file or a download that arrives in pieces, keep a running state: Sha256New starts it, Sha256Update feeds each piece and Sha256Final writes the 32 byte digest. The result is the same as hashing everything in one go, as the program shows.
import crypto
import encoding
import mem
func main:
chunks := ["first block of the file, ", "second block, ", "and the last one."]
mut whole := ""
mut h := crypto.Sha256New()
each c in chunks:
crypto.Sha256Update(h, c as void*, c.Len())
whole += c
end
out := mem.Allocate(32 as u64)
crypto.Sha256Final(h, out)
streamed := encoding.Base64EncodeBytes(out, 32)
crypto.Sha256Bytes(whole as void*, whole.Len(), out)
oneshot := encoding.Base64EncodeBytes(out, 32)
mem.Free(out)
println "streamed: " + streamed
println "one shot: " + oneshot
println "match:", streamed == oneshot
println "hex form: " + crypto.Sha256Hex(whole)
endThe ...Bytes and ...Final functions write raw bytes into memory you allocated; turn them into text with Base64EncodeBytes from encoding. The SHA-512 and SHA-384 states work the same way with Sha512New, Sha384New, Sha512Update and Sha512Final.
API keys and tokens
An API key, a password reset link or a session id must be impossible to guess, so make it with RandomToken, which reads the operating system's secure random source. RandomToken(n) returns n random bytes as 2n hex characters. Store only the SHA-256 digest of the key: a stolen database then gives no working keys, and checking a key that comes in with a request is one digest and one SecretEquals. A plain digest is enough here because the key is long and random; a password is short and chosen by a person, which is why it needs HashPassword instead.
import crypto
func main:
key := "sk_" + crypto.RandomToken(24)
println "key length:", key.Len()
stored := crypto.Sha256Hex(key)
println "stored digest length:", stored.Len()
println "valid key accepted:", crypto.SecretEquals(crypto.Sha256Hex(key), stored)
println "forged key accepted:", crypto.SecretEquals(crypto.Sha256Hex("sk_" + crypto.RandomToken(24)), stored)
println "two keys differ:", crypto.RandomToken(24) != crypto.RandomToken(24)
endWhich function for which job
| Job | Use |
|---|---|
| Store and check a user password | HashPassword, VerifyPassword |
| Sign a message or check a signed request | HmacSha256Hex and SecretEquals |
| A file checksum or a content id | Sha256Hex, or Sha256New, Sha256Update, Sha256Final for data in pieces |
| A token, key or nonce | RandomToken, RandomHex, RandomBytes |
| A key derived from a passphrase | Pbkdf2HmacSha256Hex |
| A hash table key, not for security | HashStr, HashBytes, HashInt |
| Talking to an old system that wants MD5 or SHA-1 | Md5Hex, Sha1Hex; do not use them for anything new |
For signed tokens that carry claims, see jwt; for encryption, see tls.
Types
Sha256
struct Sha256| Name | Type | Description |
|---|---|---|
h | u32[] | The internal state. |
blk | u8[] | The partial block. |
blen | int = 0 | The length of the partial block. |
total | u64 = 0 | The total number of bytes. |
import crypto
import encoding
import mem
func main:
println crypto.Sha256Hex("abc")
println crypto.Sha512Hex("abc").Len()
println crypto.Sha1Hex("abc")
println crypto.Sha1Base64("abc")
println crypto.Md5Hex("abc")
text := "abc"
out := mem.Allocate(64 as u64)
crypto.Sha256Bytes(text as void*, 3, out)
println encoding.Base64EncodeBytes(out, 32)
crypto.Sha384Bytes(text as void*, 3, out)
println encoding.Base64EncodeBytes(out, 48)
crypto.Sha512Bytes(text as void*, 3, out)
println encoding.Base64EncodeBytes(out, 16).Len()
crypto.Sha1Bytes(text as void*, 3, out)
println encoding.Base64EncodeBytes(out, 20)
crypto.Md5Bytes(text as void*, 3, out)
println encoding.Base64EncodeBytes(out, 16)
mut h := crypto.Sha256New()
crypto.Sha256Update(h, "a" as void*, 1)
crypto.Sha256Update(h, "bc" as void*, 2)
crypto.Sha256Final(h, out)
println encoding.Base64EncodeBytes(out, 32)
mut b := crypto.Sha512New()
crypto.Sha512Update(b, text as void*, 3)
crypto.Sha512Final(b, out)
println b.outlen
mut s := crypto.Sha384New()
crypto.Sha512Update(s, text as void*, 3)
crypto.Sha512Final(s, out)
println s.outlen, encoding.Base64EncodeBytes(out, 48)
mem.Free(out)
println crypto.HashStr("hello") == crypto.HashStr("hello"), crypto.HashStr("a") != crypto.HashStr("b")
println crypto.HashBytes(text as void*, 3 as u64) == crypto.HashStr("abc")
println crypto.HashInt(42 as u64) != crypto.HashInt(43 as u64)
endSha512
struct Sha512| Name | Type | Description |
|---|---|---|
h | u64[] | The internal state. |
blk | u8[] | The partial block. |
blen | int = 0 | The length of the partial block. |
total | u64 = 0 | The total number of bytes. |
outlen | int = 64 | The digest length: 64 for SHA-512 and 48 for SHA-384. |
The example for this item is shown with the ones above: crypto-Hash.salam
Functions
HashBytes
func HashBytes(p: void*, n: u64): u64The example for this item is shown with the ones above: crypto-Hash.salam
HashStr
func HashStr(s: str): u64The example for this item is shown with the ones above: crypto-Hash.salam
HashInt
func HashInt(x: u64): u64The example for this item is shown with the ones above: crypto-Hash.salam
Md5Bytes
func Md5Bytes(p: void*, n: int, out: void*)The example for this item is shown with the ones above: crypto-Hash.salam
Md5Hex
func Md5Hex(data: str): strThe example for this item is shown with the ones above: crypto-Hash.salam
HmacSha1Raw
func HmacSha1Raw(key: void*, klen: int, msg: void*, mlen: int, out: void*)import crypto
import encoding
import mem
func main:
key := "key"
message := "The quick brown fox jumps over the lazy dog"
println crypto.HmacSha256Hex(key, message)
println crypto.HmacSha1Hex(key, message)
println crypto.HmacSha1Base64(key, message)
println crypto.HmacSha384Hex(key, message).Len(), crypto.HmacSha512Hex(key, message).Len()
out := mem.Allocate(64 as u64)
crypto.HmacSha256Bytes(key, message, out)
a := encoding.Base64EncodeBytes(out, 32)
crypto.HmacSha256Raw(key as void*, 3, message as void*, message.Len(), out)
println a == encoding.Base64EncodeBytes(out, 32)
crypto.HmacSha1Bytes(key, message, out)
b := encoding.Base64EncodeBytes(out, 20)
crypto.HmacSha1Raw(key as void*, 3, message as void*, message.Len(), out)
println b == encoding.Base64EncodeBytes(out, 20), b == crypto.HmacSha1Base64(key, message)
crypto.HmacSha384Bytes(key, message, out)
c := encoding.Base64EncodeBytes(out, 48)
crypto.HmacSha384Raw(key as void*, 3, message as void*, message.Len(), out)
println c == encoding.Base64EncodeBytes(out, 48)
crypto.HmacSha512Bytes(key, message, out)
d := encoding.Base64EncodeBytes(out, 64)
crypto.HmacSha512Raw(key as void*, 3, message as void*, message.Len(), out)
println d == encoding.Base64EncodeBytes(out, 64)
mem.Free(out)
endHmacSha1Bytes
func HmacSha1Bytes(key: str, msg: str, out: void*)The example for this item is shown with the ones above: crypto-Hmac.salam
HmacSha1Hex
func HmacSha1Hex(key: str, msg: str): strThe example for this item is shown with the ones above: crypto-Hmac.salam
HmacSha1Base64
func HmacSha1Base64(key: str, msg: str): strThe example for this item is shown with the ones above: crypto-Hmac.salam
Sha256Hex
func Sha256Hex(data: str): strThe example for this item is shown with the ones above: crypto-Hash.salam
HmacSha256Raw
func HmacSha256Raw(key: void*, klen: int, msg: void*, mlen: int, out: void*)The example for this item is shown with the ones above: crypto-Hmac.salam
HmacSha384Raw
func HmacSha384Raw(key: void*, klen: int, msg: void*, mlen: int, out: void*)The example for this item is shown with the ones above: crypto-Hmac.salam
HmacSha512Raw
func HmacSha512Raw(key: void*, klen: int, msg: void*, mlen: int, out: void*)The example for this item is shown with the ones above: crypto-Hmac.salam
HmacSha256Bytes
func HmacSha256Bytes(key: str, msg: str, out: void*)The example for this item is shown with the ones above: crypto-Hmac.salam
HmacSha384Bytes
func HmacSha384Bytes(key: str, msg: str, out: void*)The example for this item is shown with the ones above: crypto-Hmac.salam
HmacSha512Bytes
func HmacSha512Bytes(key: str, msg: str, out: void*)The example for this item is shown with the ones above: crypto-Hmac.salam
HmacSha384Hex
func HmacSha384Hex(key: str, msg: str): strThe example for this item is shown with the ones above: crypto-Hmac.salam
HmacSha512Hex
func HmacSha512Hex(key: str, msg: str): strThe example for this item is shown with the ones above: crypto-Hmac.salam
HmacSha256Hex
func HmacSha256Hex(key: str, msg: str): strHmacSha256Raw for binary ones.The example for this item is shown with the ones above: crypto-Hmac.salam
BcryptHashWithSalt
func BcryptHashWithSalt(password: str, cost: int, salt: void*): strBcryptHash, with your own 16 byte salt from a pointer instead of a random one, so the same input always gives the same string; for tests and known answers, not for storing real passwords.import crypto
import mem
import str
func main:
stored := crypto.BcryptHash("s3cret-password", 10)
println str.StartsWith(stored, "$2y$10$"), stored.Len()
println crypto.IsBcryptHash(stored), crypto.BcryptCost(stored)
println crypto.BcryptVerify("s3cret-password", stored), crypto.BcryptVerify("wrong", stored)
println stored != crypto.BcryptHash("s3cret-password", 10)
salt := mem.Allocate(16 as u64)
bytes := salt as u8*
repeat 16 in i:
bytes[i] = (i * 7) as u8
end
fixed := crypto.BcryptHashWithSalt("s3cret-password", 4, salt)
println fixed
println fixed == crypto.BcryptHashWithSalt("s3cret-password", 4, salt)
mem.Free(salt)
println crypto.BcryptVerify("U*U", "$2a$05$CCCCCCCCCCCCCCCCCCCCC.E5YPO9kmyuRGyh0XouQYb4YMJKvyOeW")
println crypto.IsBcryptHash("pbkdf2-sha256$1000$aa$bb"), crypto.BcryptCost("not a hash")
endBcryptHash
func BcryptHash(password: str, cost: int): str$2y$cost$salt+hash string that PHP password_hash also writes. The cost is the base 2 log of the rounds: each step up doubles the work; 10 is a common choice, and values are kept between 4 and 31. Only the first 72 bytes of the password count.The example for this item is shown with the ones above: crypto-Bcrypt.salam
IsBcryptHash
func IsBcryptHash(encoded: str): bool$2a$, $2b$ or $2y$. Useful when a database holds both bcrypt and HashPassword strings.The example for this item is shown with the ones above: crypto-Bcrypt.salam
BcryptCost
func BcryptCost(encoded: str): int$2y$10$...; -1 when the string is not a bcrypt hash. Compare it with your target cost to know when to hash a password again.The example for this item is shown with the ones above: crypto-Bcrypt.salam
BcryptVerify
func BcryptVerify(password: str, encoded: str): bool$2a$, $2b$ or $2y$ string, with the cost and salt it holds, in constant time; hashes from PHP and other bcrypt libraries work. False for any other format.The example for this item is shown with the ones above: crypto-Bcrypt.salam
RandomHex
func RandomHex(n: int): strimport crypto
import str
import mem
func main:
stored := crypto.HashPassword("s3cret-password")
println str.StartsWith(stored, "pbkdf2-sha256$")
println crypto.VerifyPassword("s3cret-password", stored), crypto.VerifyPassword("wrong", stored)
println stored != crypto.HashPassword("s3cret-password")
println crypto.Pbkdf2HmacSha256Hex("password", "salt", 1, 32)
println crypto.SecretEquals("abc", "abc"), crypto.SecretEquals("abc", "xyz")
println crypto.RandomHex(16).Len(), crypto.RandomToken(32).Len() > 0
b := mem.Allocate(8 as u64)
crypto.RandomBytes(b, 8)
mem.Free(b)
endRandomToken
func RandomToken(n: int): strRandomHex); for session and password reset tokens.The example for this item is shown with the ones above: crypto-Password.salam
RandomBytes
func RandomBytes(p: void*, n: int)The example for this item is shown with the ones above: crypto-Password.salam
Sha512Hex
func Sha512Hex(data: str): strThe example for this item is shown with the ones above: crypto-Hash.salam
Sha256Bytes
func Sha256Bytes(p: void*, n: int, out: void*)The example for this item is shown with the ones above: crypto-Hash.salam
Sha384Bytes
func Sha384Bytes(p: void*, n: int, out: void*)The example for this item is shown with the ones above: crypto-Hash.salam
Sha512Bytes
func Sha512Bytes(p: void*, n: int, out: void*)The example for this item is shown with the ones above: crypto-Hash.salam
Sha256New
func Sha256New(): Sha256The example for this item is shown with the ones above: crypto-Hash.salam
Sha256Update
func Sha256Update(s &: Sha256, p: void*, n: int)The example for this item is shown with the ones above: crypto-Hash.salam
Sha256Final
func Sha256Final(s: Sha256, out: void*)The example for this item is shown with the ones above: crypto-Hash.salam
Sha384New
func Sha384New(): Sha512The example for this item is shown with the ones above: crypto-Hash.salam
Sha512New
func Sha512New(): Sha512The example for this item is shown with the ones above: crypto-Hash.salam
Sha512Update
func Sha512Update(s &: Sha512, p: void*, n: int)The example for this item is shown with the ones above: crypto-Hash.salam
Sha512Final
func Sha512Final(s: Sha512, out: void*)outlen.The example for this item is shown with the ones above: crypto-Hash.salam
Pbkdf2HmacSha256Hex
func Pbkdf2HmacSha256Hex(password: str, salt: str, iterations: int, keylen: int): strThe example for this item is shown with the ones above: crypto-Password.salam
HashPassword
func HashPassword(password: str): strpbkdf2-sha256$1000$salt$hash to keep in your database. The output is different every time. 1000 rounds is low by today's standards; see the guide for a stronger hash.The example for this item is shown with the ones above: crypto-Password.salam
VerifyPassword
func VerifyPassword(password: str, encoded: str): boolpbkdf2-sha256$rounds$salt$hash string, with the rounds and salt it holds, in constant time. False for any other format.The example for this item is shown with the ones above: crypto-Password.salam
SecretEquals
func SecretEquals(a: str, b: str): boolThe example for this item is shown with the ones above: crypto-Password.salam
Sha1Hex
func Sha1Hex(data: str): strThe example for this item is shown with the ones above: crypto-Hash.salam
Sha1Base64
func Sha1Base64(data: str): strThe example for this item is shown with the ones above: crypto-Hash.salam
Sha1Bytes
func Sha1Bytes(p: void*, n: int, out: void*)The example for this item is shown with the ones above: crypto-Hash.salam