From d5b374d0a466c4bf642d806168d973d4aad638e8 Mon Sep 17 00:00:00 2001 From: "Robbie Harwood (frozencemetery)" Date: Mon, 29 Jun 2015 15:29:36 -0400 Subject: Document GSSAPI encryption --- doc/src/sgml/client-auth.sgml | 19 ++++++++++++++++--- doc/src/sgml/libpq.sgml | 12 ++++++++++++ doc/src/sgml/protocol.sgml | 40 ++++++++++++++++++++++++++++++++++++++++ doc/src/sgml/runtime.sgml | 20 +++++++++++++++++++- 4 files changed, 87 insertions(+), 4 deletions(-) diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index 5f72beb..3c49612 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -913,9 +913,10 @@ omicron bryanh guest1 GSSAPI with Kerberos authentication according to RFC 1964. GSSAPI provides automatic authentication (single sign-on) for systems - that support it. The authentication itself is secure, but the - data sent over the database connection will be sent unencrypted unless - SSL is used. + that support it. The authentication itself is secure, and GSSAPI can be + used for connection encryption as well (see the + require_encrypt parameter below); SSL + can also be used for connection security. @@ -1046,6 +1047,18 @@ omicron bryanh guest1 + + + require_encrypt + + + Whether to require GSSAPI encryption. Default is off, which causes + GSSAPI encryption to be enabled if available and requested for + compatability with old clients. It is recommended to set this unless + old clients are present. + + + diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index de6b3ad..db2340c 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1356,6 +1356,18 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname + + gss_enc_require + + + If set, whether to require GSSAPI encryption support from the remote + server. Defaults to unset, which will cause the client to fall back to + not using GSSAPI encryption if the server does not support encryption + through GSSAPI. + + + + service diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 42e9497..8355e54 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1295,6 +1295,46 @@ of authentication checking. + + + <acronym>GSSAPI</acronym> Session Encryption + + + If PostgreSQL was built with + GSSAPI and GSSAPI support, traffic + can also be encrypted using GSSAPI. To force encryption + using GSSAPI, set require_encrypt in + pg_hba.conf. + + + + In order to probe for GSSAPI support, the client will + include in their StartupMessage the parameter gss_encrypt. If the server + does not support GSSAPI or GSSAPI + encryption, the server will error the connection; otherwise, it continues + as normal. The client may retry the connection + without GSSAPI encryption support depending on its + settings. If the client does not probe support, depending on settings + in pg_hba.conf, the server may drop + GSSAPI-authenticated connections without encryption. + + + + If the client has probed GSSAPI encryption support and + the connection is GSSAPI-authenticated, then after the + server sends AuthenticationOk, all traffic between the client and server + will be GSSAPI-encrypted. Because + GSSAPI does not provide framing, + GSSAPI-encrypted messages are modeled after protocol-3 + messages: the first byte is the caracter g, then four bytes of length, and + then an encrypted message. + + + + It is valid to use GSSAPI encryption over + SSL-encrypted connections. + + diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index 547567e..0b1b009 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -1833,7 +1833,7 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 - To prevent spoofing on TCP connections, the best solution is to use + To prevent spoofing on TCP connections, one possible solution is to use SSL certificates and make sure that clients check the server's certificate. To do that, the server must be configured to accept only hostssl connections (verify-full and have the appropriate root certificate file installed (). + + + Another way of preventing spoofing on TCP connections is to use GSSAPI + encryption. In order to force all GSSAPI connections to be encrypted, one + should set require_encrypt in pg_hba.conf on GSS + connections. Then, using Kerberos, the client and server will mutually + authenticate, and the connection will be encrypted once the authentication + step is complete. + @@ -1958,6 +1967,15 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 connect to servers only via SSL. Stunnel or SSH can also be used to encrypt transmissions. + + + GSSAPI connections can also encrypt all data sent across the + network. In the pg_hba.conf file, the GSS authenticaion + method has a parameter to require encryption; otherwise, connections + will be encrypted if available and requiested by the client. On the + client side, there is also a parameter to require GSSAPI encryption + support from the server. + -- 2.1.4