Skip to content

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.

Types

Interfaces

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.

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

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.

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.

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
    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>.

impl PasswordHasher for Pbkdf2

fn recognizes(Pbkdf2, id: String) -> Bool

impl PasswordHasher.recognizes

impl PasswordHasher for Pbkdf2

fn hash(hasher: Pbkdf2, password: String) -> Result<String, String>

impl PasswordHasher.hash

impl PasswordHasher for Pbkdf2

fn verify(Pbkdf2, password: String, stored: String) -> Result<Bool, String>

impl PasswordHasher.verify

impl PasswordHasher for Pbkdf2

fn needs_rehash(hasher: Pbkdf2, stored: String) -> Bool

impl PasswordHasher.needs_rehash

impl Debug for Pbkdf2

fn inspect(value: Pbkdf2) -> String

impl Debug.inspect

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

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")
fn param(phc: Phc, name: String) -> Maybe<String>

type function on Phc

The value of the parameter name, if phc has it.

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

impl Display for Phc

fn to_string(phc: Phc) -> String

impl Display.to_string

The PHC string: $<id>[$v=<version>][$<params>]$<salt>$<hash>.

impl Debug for Phc

fn inspect(value: Phc) -> String

impl Debug.inspect