/// SCRAM-SHA-256 client authentication (RFC 5802, RFC 7677; issue gabla108/louise#145): /// the exchange as pure functions — a nonce goes in, the messages come /// out — so the whole handshake is testable against the RFC's recorded /// one, no server needed. /// /// The connection actor drives it: `client_first`, then on /// `AuthenticationSaslContinue` `client_final`, and on /// `AuthenticationSaslFinal` `verify_server`. import std/base64 import std/bytes import std/crypto import std/int import std/list import std/option import std/result import std/string /// The state between the steps. pub type Scram { /// After `client_first`. Started(client_nonce: String, client_first_bare: String) /// After `client_final`: the signature the server must show. , Answered(server_signature: Bytes) } /// The client-first message: `n,,n=,r=`. The `n=` (username) part /// is empty: PostgreSQL reads the user from the startup message. The /// nonce is the caller's (`random.bytes`-backed in production). pub fn client_first :: nonce: String -> (Scram, Bytes) { let bare = "n=,r=" <> nonce (Started(nonce, bare), bytes.from_string ("n,," <> bare)) } /// The client-final message for `password`, answering the server-first /// message (`r=,s=,i=`). The server's nonce must /// extend ours (a downgrade or a replay has it not). pub fn client_final :: state: Scram password: String server_first: String -> Result<(Scram, String), String> { match state { Answered(_) -> Error("scram: the exchange already sent its client-final") , Started(client_nonce, bare) -> { let fields = list.map (string.split server_first ",") field_value use nonce <- result.try ( option.to_result (field fields "r") "scram: the server-first message has no nonce" ) if !string.starts_with nonce client_nonce { Error("scram: the server's nonce does not extend ours") } else { use salt64 <- result.try ( option.to_result (field fields "s") "scram: no salt in the server-first message" ) use its <- result.try ( option.to_result (field fields "i") "scram: no iteration count in the server-first message" ) use iterations <- result.try (string.to_int its |> result.map_error fn e { "scram: {e}" }) use salt <- result.try (base64.decode salt64) let salted = crypto.pbkdf2_hmac_sha256 (bytes.from_string password) salt iterations 32 let client_key = crypto.hmac_sha256 salted (bytes.from_string "Client Key") let stored_key = crypto.sha256 client_key let without_proof = "c=biws,r=" <> nonce let auth_message = bare <> "," <> server_first <> "," <> without_proof let proof = xor client_key (crypto.hmac_sha256 stored_key (bytes.from_string auth_message)) let server_key = crypto.hmac_sha256 salted (bytes.from_string "Server Key") let signature = crypto.hmac_sha256 server_key (bytes.from_string auth_message) Ok((Answered(signature), without_proof <> ",p=" <> base64.encode proof)) } } } } /// Check the server-final message's `v=`: a wrong one means the /// server never knew the password either. pub fn verify_server :: state: Scram server_final: String -> Result<(), String> { match state { Started(..) -> Error("scram: no client-final was sent") , Answered(expected) -> { let fields = list.map (string.split server_final ",") field_value match field fields "v" { None -> Error("scram: the server-final message has no signature") , Some(signature64) -> match base64.decode signature64 { Ok(signature) -> if signature == expected { Ok(()) } else { Error( "scram: the server never knew the password (bad server signature)" ) } , Error(e) -> Error("scram: {e}") } } } } } // ---- helpers ---------------------------------------------------------------- /// `"name=value"` as `(name, value)`; a value may itself contain `=` /// (base64 padding does). fn field_value :: f: String -> (String, String) { match string.split f "=" { [name, ..rest] -> (name, string.join rest "="), [] -> (f, "") } } /// The value of the field `name`, if present. fn field :: fields: List<(String, String)> name: String -> Option { match fields { [] -> None , [(n, v), ..rest] -> if n == name { Some(v) } else { field rest name } } } /// Byte-wise XOR (same length: a key and its signature are both 32 bytes). fn xor :: a: Bytes b: Bytes -> Bytes { bytes.from_list (list.zip_with (bytes.to_list a) (bytes.to_list b) int.xor) }