/// Argon2id password hashing (RFC 9106), from the reference C /// implementation linked as a native dependency (ADR 0005). /// /// import argon2 /// /// let stored = argon2.hash_password("hunter2", argon2.default_params()) /// argon2.verify("hunter2", stored) // Ok(True) /// /// Hashing and verifying run on the `cpu` blocking pool: the calling actor /// waits, others keep running. At most `LOUISE_BLOCKING_CPU_THREADS` hashes /// run at once (each holding `m_cost_kib` of memory), and /// `runtime.blocking_stats()` tells how many wait. import std/random.{type random} import std/string import std/test.{assert} /// Cost parameters: passes over memory, memory in KiB, lanes. pub type Params { Params(t_cost: Int, m_cost_kib: Int, parallelism: Int) } /// RFC 9106's second recommended option: 3 passes over 64 MiB. pub fn default_params :: -> Params { Params(t_cost: 3, m_cost_kib: 65536, parallelism: 1) } /// Hash `password` with a fresh random 16-byte salt (from the `random` /// effect); the result is the PHC string /// (`$argon2id$v=19$m=...,t=...,p=...$salt$hash`) to store. pub fn hash_password :: password: String params: Params -> Result / { hash password (random.token 16) params } /// Hash `password` with `salt` (at least 8 bytes). pub fn hash :: password: String salt: String params: Params -> Result / { hash_raw password salt params.t_cost params.m_cost_kib params.parallelism } @test fn each_parameter_reaches_the_c_library :: -> () / { // Three different values, so that two swapped arguments would show. match hash "pw" "saltsalt" Params(t_cost: 2, m_cost_kib: 96, parallelism: 3) { Ok(stored) -> assert (string.starts_with stored "$argon2id$v=19$m=96,t=2,p=3$") stored , Error(e) -> panic e } } /// `Ok(True)` if `password` matches `encoded`, a string made by `hash`, /// `Ok(False)` if it does not, or an `Error` if `encoded` is not an /// Argon2id hash this package can check (for example, a corrupted one). pub fn verify :: password: String encoded: String -> Result / { verify_raw encoded password } /// Hash `password` keyed with `secret` (RFC 9106's secret value `K`, a /// pepper kept out of the database) and a fresh random 16-byte salt. The /// PHC string does not record the secret: verify it with `verify_keyed` /// and the same secret, never with `verify`. pub fn hash_password_keyed :: password: String secret: String params: Params -> Result / { hash_keyed password secret (random.token 16) params } /// Hash `password` keyed with `secret`, with `salt` (at least 8 bytes). /// The secret's bytes are the key. pub fn hash_keyed :: password: String secret: String salt: String params: Params -> Result / { hash_keyed_raw password secret "" salt params.t_cost params.m_cost_kib params.parallelism } /// [`verify`] for a hash made by `hash_keyed`: `Ok(True)` only with the /// same password and secret. An unkeyed hash verifies with an empty secret. pub fn verify_keyed :: password: String secret: String encoded: String -> Result / { verify_keyed_raw encoded password secret } // RFC 9106 ยง5.3, Argon2id: the secret and the associated data both count. @test fn keyed_hashing_matches_rfc_9106 :: -> () / { match hash_keyed_raw (string.repeat "\u{1}" 32) (string.repeat "\u{3}" 8) (string.repeat "\u{4}" 12) (string.repeat "\u{2}" 16) 3 32 4 { Ok(stored) -> assert ( stored == "$argon2id$v=19$m=32,t=3,p=4$AgICAgICAgICAgICAgICAg$DWQN9Y14dmwIwDejSotTydAe8EUtdbZetSUg6WsB5lk" ) stored , Error(e) -> panic e } } @extern c "louise_argon2_hash" (blocking cpu) fn hash_raw :: password: String salt: String t_cost: Int m_cost: Int parallelism: Int -> Result / @extern c "louise_argon2_verify" (blocking cpu) fn verify_raw :: encoded: String password: String -> Result / @extern c "louise_argon2_hash_keyed" (blocking cpu) fn hash_keyed_raw :: password: String secret: String ad: String salt: String t_cost: Int m_cost: Int parallelism: Int -> Result / @extern c "louise_argon2_verify_keyed" (blocking cpu) fn verify_keyed_raw :: encoded: String password: String secret: String -> Result /