From eb882a1b717589777e068dc6671830226f3aa7f0 Mon Sep 17 00:00:00 2001 From: Stephen Frost Date: Fri, 19 Apr 2019 21:22:22 -0400 Subject: GSSAPI: Improve documentation and tests The GSSAPI encryption patch neglected to update the protocol documentation to describe how to set up a GSSAPI encrypted connection from a client to the server, so fix that by adding the appropriate documentation to protocol.sgml. The tests added for encryption support were overly long and couldn't be run in parallel due to race conditions; this was largely because each test was setting up its own KDC to perform the tests. Instead, merge the authentication tests and the encryption tests into the original test, where we only create one KDC to run the tests with. Also, have the tests check what the server's opinion is of the connection and if it was GSS authenticated or encrypted using the pg_stat_gssapi view. In passing, fix the libpq label for GSSENC-Mode to be consistent with the "PGGSSENCMODE" environment variable. Missing protocol documentation pointed out by Michael Paquier. Issues with the tests pointed out by Tom Lane and Peter Eisentraut. Refactored tests and added documentation by me. Reviewed by Robbie Harwood (protocol documentation) and Michael Paquier (rework of the tests). --- doc/src/sgml/protocol.sgml | 106 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) (limited to 'doc/src') diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 09893d96b57..4c4bb38ba7f 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1479,6 +1479,75 @@ SELCT 1/0; of authentication checking. + + + <acronym>GSSAPI</acronym> Session Encryption + + + If PostgreSQL was built with + GSSAPI support, frontend/backend communications + can be encrypted using GSSAPI. This provides + communication security in environments where attackers might be + able to capture the session traffic. For more information on + encrypting PostgreSQL sessions with + GSSAPI, see . + + + + To initiate a GSSAPI-encrypted connection, the + frontend initially sends a GSSENCRequest message rather than a + StartupMessage. The server then responds with a single byte + containing G or N, indicating that it + is willing or unwilling to perform GSSAPI encryption, + respectively. The frontend might close the connection at this point + if it is dissatisfied with the response. To continue after + G, using the GSSAPI C bindings as discussed in RFC2744 + or equivilant, perform a GSSAPI initialization by + calling gss_init_sec_context() in a loop and sending + the result to the server, starting with an empty input and then with each + result from the server, until it returns no output. When sending the + results of gss_init_sec_context() to the server, + prepend the length of the message as a four byte integer in network byte + order. If this is successful, then use gss_wrap() to + encrypt the usual StartupMessage and all subsequent data, prepending the + length of the result from gss_wrap() as a four byte + integer in network byte order to the actual encrypted payload. Note that + the server will only accept encrypted packets from the client which are less + than 16KB; gss_wrap_size_limit() should be used by the + client to determine the size of the unencrypted message which will fit + within this limit and larger messages should be broken up into multiple + gss_wrap() calls. Typical segments are 8KB of + unencrypted data, resulting in encrypted packets of slightly larger than 8KB + but well within the 16KB maximum. The server can be expected to not send + encrypted packets of larger than 16KB to the client. To continue after + N, send the usual StartupMessage and proceed without + encryption. + + + + The frontend should also be prepared to handle an ErrorMessage + response to GSSENCRequest from the server. This would only occur if + the server predates the addition of GSSAPI encryption + support to PostgreSQL. In this case the + connection must be closed, but the frontend might choose to open a fresh + connection and proceed without requesting GSSAPI + encryption. Given the length limits specified above, the ErrorMessage can + not be confused with a proper response from the server with an appropriate + length. + + + + An initial GSSENCRequest can also be used in a connection that is being + opened to send a CancelRequest message. + + + + While the protocol itself does not provide a way for the server to + force GSSAPI encryption, the administrator can + configure the server to reject unencrypted sessions as a byproduct + of authentication checking. + + @@ -5714,6 +5783,43 @@ SSLRequest (F) + + +GSSENCRequest (F) + + + + + + + + Int32(8) + + + + Length of message contents in bytes, including self. + + + + + + Int32(80877104) + + + + The GSSAPI Encryption request code. The value is chosen to contain + 1234 in the most significant 16 bits, and 5680 in the + least significant 16 bits. (To avoid confusion, this code + must not be the same as any protocol version number.) + + + + + + + + + -- cgit v1.2.3