>From 212af2998f87734e4d057d26db3c5221e0f7432f Mon Sep 17 00:00:00 2001 From: Heikki Linnakangas Date: Mon, 10 Apr 2017 15:49:04 +0300 Subject: [PATCH 1/1] Add docs for SASL authentication in protocol. --- doc/src/sgml/protocol.sgml | 260 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 258 insertions(+), 2 deletions(-) diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 4e8bb32d33..3bc62a4b82 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1326,6 +1326,119 @@ + +SASL Authentication + + +SASL is a framework for authentication in connection-oriented protocols. +At the moment, PostgreSQL implements only one SASL authentication mechanism, +SCRAM-SHA-256, but more might be added in the future. The below steps +illustrate how SASL authentication is performed in general, while the next +subsection gives more details on SCRAM-SHA-256. + + + +SASL Authentication Message Flow + + + To begin an SASL authentication exchange, the server sends the client an + AuthenticationSASL message. It includes a list of SASL authentication + mechanisms that the server can accept, in the server's preferred order. + + + + The client selects one of the supported mechanisms from the list, and sends + a SASLInitialResponse message to the server. The message includes the name + of the selected mechanism, and possibly an Initial Client Response, if the + selected mechanism supports that. + + + + + One or more server-challenge and client-response message will follow. Each + server-challenge is sent in an AuthenticationSASLContinue message, followed + by a response from client in an SASLResponse message. The particulars of + the messages are mechanism specific. + + + + + Finally, when the authentication exchange is completed successfully, the + server sends an AuthenticationOK message. The AuthenticationOK message can + include an "additional data" field, whose content is particular to the + selected authentication mechanism. + + + + SCRAM-SHA-256 authentication + + + SCRAM-SHA-256 is the only implemented SASL mechanism, at the moment. It is + described in detail in [RFC7677] and [RFC5741]. (called just SCRAM from now on) + + + +When SCRAM-SHA-256 is used in PostgreSQL, the server will ignore the username +that the client sends in the client-first-message. The username that was +already sent in the startup message is used instead. PostgreSQL supports +multiple character encodings, while SCRAM dictates UTF-8 to be used for the +username, so it might be impossible to represent the PostgreSQL username in +UTF-8. To avoid confusion, the client should use an empty string as the +username in the client-first-message. + + + +The SCRAM specification dictates that the password is also in UTF-8, and is +processed with the SASLprep algorithm. PostgreSQL, however, does not require +UTF-8 to be used for the password. When a user's password is set, it is +processed with SASLprep as if it was in UTF-8, regardless of the actual +encoding used. However, if it is not a legal UTF-8 byte sequence, or it +contains UTF-8 byte sequences that are prohibited by the SASLprep algorithm, +the raw password will be used without SASLprep processing, instead of +throwing an error. This allows the password to be normalized when it is in +UTF-8, but still allows a non-UTF-8 password to be used, and doesn't require +the system to know which encoding the password is in. + + + +Channel binding has not been implemented yet. + + + +Example: + + + + + The server sends an AuthenticationSASL message. It includes of a + list of SASL authentication mechanisms that the server can accept. + + + + The client responds by sending a SASLInitialResponse message, which + indicates the chosen mechanism, SCRAM-SHA-256. In the Initial + Client response field, the message containts a SCRAM + client-first-message, as specified by [RFC5802] and [RFC7677]. + + + + Server sends an AuthenticationSASLContinue message, with a SCRAM + server-first message as the content. + + + + Client sends a SASLResponse messsage, with SCRAM + client-final-message as the content. + + + + Server sends an AuthenticationOK message, with the SCRAM + server-final-message in the "additional data" field. + + + + + Streaming Replication Protocol @@ -2501,7 +2614,7 @@ AuthenticationOk (B) - Int32(8) + Int32 @@ -2519,6 +2632,29 @@ AuthenticationOk (B) + + + Int32 + + + + Length of authentication method specific "additional + data" that follows. If this message contains no additional + data, this field is omitted. + + + + + + Byten + + + + Authentication method specific "additional data". If this + message contains no additional data, this field is omitted. + + + @@ -2894,13 +3030,19 @@ AuthenticationSASL (B) + +The message body is a list of SASL authentication mechanisms, in the +server's order of preference. A zero byte is required as terminator after +the last authentication mechanism name. For each mechanism, there is the +following: + String - Name of a SASL authentication mechanism. + Name of SASL authentication mechanism. @@ -4761,6 +4903,120 @@ PasswordMessage (F) +SASLInitialresponse (F) + + + + + + + + Byte1('p') + + + + Identifies the message as an initial SASL response. Note that + this is also used for GSSAPI, SSPI and password response messages. + The message type is deduced from the context. + + + + + + Int32 + + + + Length of message contents in bytes, including self. + + + + + + String + + + + Name of the SASL authentication mechanism that the client + selected. + + + + + + Int32 + + + + Length of SASL mechanism specific "Initial Response" that + follows, or -1 if there is no Initial Response. + + + + + + Byten + + + + SASL mechanism specific "Initial Response". + + + + + + + + + + + +SASLResponse (F) + + + + + + + + Byte1('p') + + + + Identifies the message as a SASL response. Note that + this is also used for GSSAPI, SSPI and password response messages. + The message type can be deduced from the context. + + + + + + Int32 + + + + Length of message contents in bytes, including self. + + + + + + Byten + + + + SASL mechanism specific message data. + + + + + + + + + + + PortalSuspended (B) -- 2.11.0