The authentication exchange, as a fold over the messages the server sends.

minato_protocol decodes an Authentication* message; this module decides what to answer with. It does no I/O and starts no process, so the whole cycle, including the ones that need several round trips, can be driven in a test without a socket.

State = minato_auth:init(#{user => ~"minato", password => ~"pencil"}),
{send, Reply, Next} = minato_auth:step(Message, State),
%% write minato_protocol:encode(Reply), read the next message, step again

step/2 answers one of three things:

• {send, Reply, State} to write Reply and wait for the next message
• {continue, State} when the server's message needed no answer, which is what AuthenticationSASLFinal is
• authenticated on AuthenticationOk, after which the caller reads ParameterStatus, BackendKeyData and ReadyForQuery as usual

An ErrorResponse from the server is not handled here. It is an ordinary decoded message and the caller branches on it: a wrong password arrives that way, not as an exception.

A started SASL exchange has to finish

AuthenticationOk is refused while a SCRAM exchange is outstanding, and that refusal is load bearing rather than tidiness. The check that authenticates the server to the client lives in AuthenticationSASLFinal, so a server that cannot produce a valid ServerSignature has an obvious move available: send AuthenticationOk instead and never send the final message at all. A client that accepted it would have proved itself to an impostor and gone on to send it queries, which is exactly the outcome verifying the signature is meant to prevent. Only an exchange that reached verified, or one that never started because the server asked for no password, ends in authenticated.

Changing method part way through is refused for the same reason. A server that opened with AuthenticationSASL and then asks for a cleartext password, or for MD5, is asking the client to hand over something weaker than the exchange it already began, which is what a man in the middle who cannot finish SCRAM would do next.

That guard is worth having but it is not a policy. A server that asks for cleartext in its very first message is answered, because that is what supporting cleartext means, and minato has no way yet to be told which methods are acceptable. A require_auth style option belongs with the connection layer, along with TLS, since both are decisions about the transport rather than about the exchange.

Methods

SCRAM-SHA-256 is the one that matters: it is what password_encryption has defaulted to since PostgreSQL 14, and CloudNativePG issues nothing else. The other two are here because a PostgreSQL is not always a recent PostgreSQL, and they cost a handful of lines each.

MD5 is broken as a hash and PostgreSQL has deprecated it, so a server asking for it is one to reconfigure rather than one to trust. minato answers anyway, because refusing would only mean a connection that cannot be made at all, whereas the server has already decided what it will accept.

GSSAPI, SSPI and the rest of the Authentication codes never reach this module: minato_protocol models the four above and raises on any other code as it decodes, because there is no useful reply to build and a message silently passed on would look to a caller like a hung connection. A message that is not an authentication message at all raises here, for the same reason.

Channel binding

SCRAM-SHA-256-PLUS is chosen when the server offers it and the caller supplied channel_binding_data, which is the hash of the server's certificate and comes from the connection layer, since only it has the TLS session.

channel_binding => require refuses to authenticate at all without it. prefer takes it when both sides have it, and falls back to plain SCRAM with a y,, header, which tells a server that does support binding that its mechanism list was stripped on the way. disable never binds. See minato_scram for what each header means.