Skip to content

feat(security): sign in with SCRAM-SHA-256 on the wire protocol - #112

Merged
venkat1701 merged 9 commits into
mainfrom
feature/scram-authentication
Oct 27, 2026
Merged

venkat1701 merged 9 commits into
mainfrom
feature/scram-authentication

Conversation

@venkat1701

@venkat1701 venkat1701 commented Oct 25, 2026 •

Copy link
Copy Markdown
Collaborator

Stacked on #109 (merge order: #111, #108, #109, then this). The diff against #109 is the SCRAM work only.

The wire protocol used to take AUTHENTICATE user PASSWORD '…', so without TLS the password crossed the network in clear text. It now signs in with SCRAM-SHA-256 (RFC 5802, RFC 7677), the mechanism PostgreSQL uses:

  • The password never crosses the connection; the client proves it knows it, and the server proves it holds the user's verifier, so a client also detects a fake server.
  • Over TLS the client uses SCRAM-SHA-256-PLUS with tls-server-end-point channel binding, so an exchange relayed through a man in the middle fails. The server rejects a client that announces binding support without using it on a TLS connection.
  • Users are stored as verifiers in the PostgreSQL format (SCRAM-SHA-256$iterations:salt$StoredKey:ServerKey). The old PBKDF2 hashes were exactly SCRAM's SaltedPassword, so the first open converts them in place without the passwords; nobody has to reset anything. A version before this one cannot read converted records.
  • Unknown users get a salt derived from the name and a per-database secret and fail only at the last step, like a wrong password.
  • Old clients: AUTHENTICATE … PASSWORD over the wire is refused, without checking the password, with this server no longer accepts passwords in clear text; upgrade your HStore client to version 0.2.0 or later, which signs in with SCRAM-SHA-256. The project version is now 0.2.0 for that reason. AUTHENTICATE keeps working in embedded sessions and in Studio's console; hstore connect turns one typed at its prompt into a SCRAM exchange.
  • CREATE USER / ALTER USER accept a verifier in place of a password, and the new hstore verifier prints one, so a password need not reach the server even without TLS.
  • The sign-in throttle (from 7ca0014) is split into reserve and complete so a two-step exchange holds its slot; abandoned exchanges count as failures.
  • Docs: wire protocol (protocol, replies, a real transcript, a Python client using only the standard library), security, HQL, CLI, logging.

Tests

  • ScramTest: the RFC 7677 example vector exactly (client-first, server-first, proof, server signature); wrong passwords and unknown users rejected alike, with a stable salt for unknown users; channel binding accepted with the right certificate hash and rejected with another; downgrade (y over TLS, -PLUS without TLS) rejected; 13 malformed messages; replays; verifier parse/encode; legacy hash conversion; our PBKDF2 matches a hand-written PBKDF2 over UTF-8 for a non-ASCII password.
  • SecurityTest: stored verifiers, legacy records upgraded on reopen (and a second reopen writes nothing), verifier passwords in CREATE USER, weak verifiers rejected, SCRAM through Session with throttling.
  • ServerTest: clear-text AUTHENTICATE gets the upgrade message, unsupported mechanism and bad base64 are refused, SCRAM over TLS with channel binding, and every existing client test now signs in with SCRAM.
  • Interoperability: the Python client from the docs (an independent implementation using hashlib/hmac) signs in against a running server over plain TCP (method=SCRAM-SHA-256) and over TLS with channel binding (method=SCRAM-SHA-256-PLUS), and is refused with a wrong password.
  • ChangeLogReplayTest now counts the one commit a new database makes when first opened (the SCRAM secret).
  • Full build of this branch (with everything below it): engine 257, database 116, server 37, all passing.

The wire protocol now signs in with SCRAM-SHA-256 (RFC 5802, RFC 7677),
with tls-server-end-point channel binding (SCRAM-SHA-256-PLUS) over TLS.
The password never crosses the connection, the client checks that the
server knows the user's verifier, and a relayed exchange fails.

- Users are stored as SCRAM verifiers in the PostgreSQL format. The
  first open converts the PBKDF2 hashes of older versions in place,
  without the passwords.
- Unknown users get a salt derived from the name and a per-database
  secret and fail only at the last step, like a wrong password.
- AUTHENTICATE ... PASSWORD over the wire protocol is refused with a
  message to upgrade the client; it still works in embedded sessions and
  in Studio. hstore connect turns a typed AUTHENTICATE into SCRAM.
- CREATE USER and ALTER USER accept a verifier in place of a password,
  and hstore verifier prints one.
- The sign-in throttle is split into reserve and complete so a two-step
  exchange holds its slot.
- Version 0.2.0, because 0.1.0 clients cannot sign in any more.
… hashes

The client now refuses a server that does not ask for the password,
answers the first SASL message with anything but a challenge, names
another user, or skips or fails its proof, and disconnects. A stored
0.1 hash equals SCRAM's SaltedPassword, so it is no longer turned into
a verifier: such users are refused over SCRAM and get a fresh salt on
their next clear-text sign-in through Studio or the embedded API.

AUTHENTICATE wrapped in AT GENERATION or AS OF is refused, verifiers
must use 4096 to 10000000 iterations, and passwords go through SASLprep
on both sides.
…ins to the record

- The shell refuses any script that mentions AUTHENTICATE unless it is
  a single statement it can turn into a SCRAM exchange, and answers
  'disconnected' after it dropped a connection whose proof failed.
- A SCRAM exchange only succeeds while the user's record is the one its
  verifier came from, and clear-text sign-ins keep the exact record
  they checked, so a password change or a drop and re-create during a
  sign-in is caught.
- The Python client in the docs normalizes like the server; both agree
  on every code point.
- Parse errors of scripts with AUTHENTICATE are not logged verbatim, and
  the old-password warning is logged once per user per 10 minutes.
@venkat1701
venkat1701 changed the base branch from feature/rank-statement to main October 27, 2026 12:27
@venkat1701
venkat1701 merged commit d9cfebc into main Oct 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant