std::passwords
Password storage for logins: passwords.hash turns a password into a
string to keep, and passwords.verify checks a password someone typed
against it.
stored = passwords.hash(form.password)? // later, at sign-in: signed_in = passwords.verify(form.password, user.password_hash) == Ok(True)
The stored string is a PHC string: it names the algorithm and records
its parameters, a random salt and the hash, as
$pbkdf2-sha256$i=600000$<salt>$<hash> with the salt and hash in base64
without padding. So a hash keeps verifying after the defaults change,
and passwords.needs_rehash says when to hash a password again, which
an app does at sign-in, the one time it holds the password:
if passwords.needs_rehash(user.password_hash) then save_password_hash(user, passwords.hash(form.password)?) end
The default hasher is Pbkdf2, PBKDF2-HMAC-SHA256 at 600,000
iterations, what OWASP’s Password Storage Cheat Sheet recommends for it,
because Go’s standard library has it. Argon2id, which OWASP prefers, and
bcrypt, for hashes an older system made, are in the first-party
password_hashers module, whose types implement PasswordHasher; hand
verify every hasher whose hashes the app may hold, and it picks the
one that reads the stored string’s algorithm.
A password is hashed as its UTF-8 bytes, as typed: there is no normalization, so a password typed with a different composition of the same accented letter does not verify.
Import with import std::passwords.
Exports
Section titled “Exports”Types
Interfaces
interface PasswordHasher
Section titled “interface PasswordHasher”interface PasswordHasher fn recognizes(hasher: self, id: String) -> Bool fn hash(hasher: self, password: String) -> Result<String, String> fn verify(hasher: self, password: String, stored: String) -> Result<Bool, String> fn needs_rehash(hasher: self, stored: String) -> Bool end
A password hashing algorithm: how it hashes a password, and how it
checks a password against a hash it made before. passwords.hash,
verify and needs_rehash call these; a module that adds an algorithm
implements it.
PasswordHasher.recognizes
Section titled “PasswordHasher.recognizes”fn recognizes(hasher: self, id: String) -> Bool
interface PasswordHasher
Whether this hasher recognizes a stored hash whose algorithm is id:
the text between a stored string’s first two $ (pbkdf2-sha256,
argon2id, 2b).
PasswordHasher.hash
Section titled “PasswordHasher.hash”fn hash(hasher: self, password: String) -> Result<String, String>
interface PasswordHasher
password hashed with a new random salt, as the string to store,
or why this hasher’s parameters, or the password, cannot be hashed.
PasswordHasher.verify
Section titled “PasswordHasher.verify”fn verify(hasher: self, password: String, stored: String) -> Result<Bool, String>
interface PasswordHasher
Whether password is the one stored was made from, by the
parameters stored records, compared in constant time. An Err
says stored is not a well-formed hash of this algorithm.
PasswordHasher.needs_rehash
Section titled “PasswordHasher.needs_rehash”fn needs_rehash(hasher: self, stored: String) -> Bool
interface PasswordHasher
Whether stored, which this hasher reads, was made with parameters
other than this hasher’s.
struct Pbkdf2
Section titled “struct Pbkdf2”struct Pbkdf2 iterations: PositiveInt = 600_000 salt_length: PositiveInt = 16 length: PositiveInt = 32 end
PBKDF2 with HMAC-SHA256 (RFC 8018), the algorithm Go’s standard library
carries. Its stored strings are $pbkdf2-sha256$i=<iterations>$<salt>$<hash>.
Pbkdf2.recognizes
Section titled “Pbkdf2.recognizes”impl PasswordHasher for Pbkdf2
fn recognizes(Pbkdf2, id: String) -> Bool
impl PasswordHasher.recognizes
Pbkdf2.hash
Section titled “Pbkdf2.hash”impl PasswordHasher for Pbkdf2
fn hash(hasher: Pbkdf2, password: String) -> Result<String, String>
impl PasswordHasher.hash
Pbkdf2.verify
Section titled “Pbkdf2.verify”impl PasswordHasher for Pbkdf2
fn verify(Pbkdf2, password: String, stored: String) -> Result<Bool, String>
Pbkdf2.needs_rehash
Section titled “Pbkdf2.needs_rehash”impl PasswordHasher for Pbkdf2
fn needs_rehash(hasher: Pbkdf2, stored: String) -> Bool
impl PasswordHasher.needs_rehash
Pbkdf2.inspect
Section titled “Pbkdf2.inspect”impl Debug for Pbkdf2
fn inspect(value: Pbkdf2) -> String
impl Debug.inspect
passwords.hash
Section titled “passwords.hash”fn hash(password: String, hasher: PasswordHasher = Pbkdf2{}) -> Result<String, String>
password hashed by hasher with a new random salt: the string to
store. Hashing the same password twice gives two strings, each of which
verifies. An Err says the hasher’s parameters, or the password, cannot
be hashed, such as a Pbkdf2 whose salt is too short.
import std::passwords.{self, Pbkdf2}
fast = Pbkdf2{iterations: 1_000}
stored = passwords.hash("correct horse", hasher: fast)!
assert String.starts_with(stored, "$pbkdf2-sha256$i=1000$")
assert passwords.hash("correct horse", hasher: fast)! != stored
assert passwords.verify("correct horse", stored) == Ok(True)
assert passwords.hash("x", hasher: Pbkdf2{salt_length: 4})
== Err("a PBKDF2 salt is 8 to 1024 bytes, got 4")
passwords.verify
Section titled “passwords.verify”fn verify(password: String, stored: String, hashers: List<PasswordHasher> = [Pbkdf2{}]) -> Result<Bool, String>
Whether password is the one stored was made from, checked by the
first of hashers that reads stored’s algorithm, with the parameters
stored records. The comparison takes the same time however much of a
wrong password’s hash matches. An Err says stored is not a password
hash, or that none of hashers reads its algorithm.
import std::passwords
// PBKDF2-HMAC-SHA256 of "password" and "somesaltsomesalt" at 1,000
// iterations, as Go's crypto/pbkdf2 computes it.
stored = "$pbkdf2-sha256$i=1000$c29tZXNhbHRzb21lc2FsdA$s5LQUeAEZUMuFVrnmF3OMNPXs3QWnF8SO/5BXmCj6QQ"
assert passwords.verify("password", stored) == Ok(True)
assert passwords.verify("Password", stored) == Ok(False)
assert passwords.verify("password", "plain text")
== Err("not a password hash: it does not start with `$<algorithm>$`")
assert passwords.verify("password", "$argon2id$v=19$m=19456,t=2,p=1$c2FsdA$aGFzaA")
== Err("no hasher given reads `argon2id` hashes")
passwords.needs_rehash
Section titled “passwords.needs_rehash”fn needs_rehash(stored: String, hasher: PasswordHasher = Pbkdf2{}) -> Bool
Whether stored should be hashed again with hasher: it was made by
another algorithm, with other parameters, or is not a hash hasher
reads at all. Check it after a password verifies, and store the new
hash.
import std::passwords.{self, Pbkdf2}
old = passwords.hash("hunter2", hasher: Pbkdf2{iterations: 1_000})!
assert passwords.needs_rehash(old, hasher: Pbkdf2{iterations: 2_000})
refute passwords.needs_rehash(old, hasher: Pbkdf2{iterations: 1_000})
assert passwords.needs_rehash("$2b$10$abc")
passwords.algorithm
Section titled “passwords.algorithm”fn algorithm(stored: String) -> Maybe<String>
The algorithm a stored hash names, between its first two $, or
None for a string that does not start that way.
import std::passwords
assert passwords.algorithm("$pbkdf2-sha256$i=1000$c2FsdA$aGFzaA") == Some("pbkdf2-sha256")
assert passwords.algorithm("$2b$12$R9h/cIPz0gi.URNNX3kh2O") == Some("2b")
assert passwords.algorithm("hunter2") == None
struct Phc
Section titled “struct Phc”struct Phc id: String version: Maybe<Int> = None params: List<(String, String)> = [] salt: Bytes hash: Bytes end
A PHC string’s parts: $<id>[$v=<version>][$<param>=<value>,...]$<salt>$<hash>,
with the salt and hash in base64’s standard alphabet without padding,
as the Password Hashing Competition’s string format writes them. A
PasswordHasher for a PHC algorithm reads and writes its strings with
this.
Phc.parse
Section titled “Phc.parse”fn parse(text: String) -> Result<Phc, String>
type function on Phc
The parts of a PHC string, or why it is not one. A salt or hash
with = padding, or a version or parameter that is not a name and
a value, is an Err.
import std::passwords.Phc
phc = Phc.parse("$argon2id$v=19$m=19456,t=2,p=1$c29tZXNhbHQ$aGFzaA")!
assert phc.id == "argon2id"
assert phc.version == Some(19)
assert phc.params == [("m", "19456"), ("t", "2"), ("p", "1")]
assert phc.salt == String.to_bytes("somesalt")
assert Display.to_string(phc) == "$argon2id$v=19$m=19456,t=2,p=1$c29tZXNhbHQ$aGFzaA"
assert Phc.parse("$pbkdf2-sha256$i=1000$c2FsdA==$aGFzaA") == Err("a PHC salt has no `=` padding")
Phc.param
Section titled “Phc.param”fn param(phc: Phc, name: String) -> Maybe<String>
type function on Phc
The value of the parameter name, if phc has it.
Phc.int_param
Section titled “Phc.int_param”fn int_param(phc: Phc, name: String) -> Result<Int, String>
type function on Phc
The parameter name as a non-negative decimal Int, or why phc
lacks it.
import std::passwords.Phc
phc = Phc.parse("$pbkdf2-sha256$i=1000$c2FsdA$aGFzaA")!
assert Phc.int_param(phc, "i") == Ok(1000)
assert Phc.int_param(phc, "m") == Err("the PHC string has no `m` parameter")
Phc.to_string
Section titled “Phc.to_string”impl Display for Phc
fn to_string(phc: Phc) -> String
impl Display.to_string
The PHC string: $<id>[$v=<version>][$<params>]$<salt>$<hash>.
Phc.inspect
Section titled “Phc.inspect”impl Debug for Phc
fn inspect(value: Phc) -> String
impl Debug.inspect