From d5b374d0a466c4bf642d806168d973d4aad638e8 Mon Sep 17 00:00:00 2001
From: "Robbie Harwood (frozencemetery)" <rharwood@redhat.com>
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
     <productname>GSSAPI</productname> with <productname>Kerberos</productname>
     authentication according to RFC 1964. <productname>GSSAPI</productname>
     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
-    <acronym>SSL</acronym> is used.
+    that support it. The authentication itself is secure, and GSSAPI can be
+    used for connection encryption as well (see the
+    <literal>require_encrypt</literal> parameter below); <acronym>SSL</acronym>
+    can also be used for connection security.
    </para>
 
    <para>
@@ -1046,6 +1047,18 @@ omicron         bryanh                  guest1
        </para>
       </listitem>
      </varlistentry>
+
+     <varlistentry>
+      <term><literal>require_encrypt</literal></term>
+      <listitem>
+       <para>
+        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.
+       </para>
+      </listitem>
+     </varlistentry>
     </variablelist>
    </para>
   </sect2>
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
       </listitem>
      </varlistentry>
 
+     <varlistentry id="libpq-connect-gss-enc-require" xreflabel="gss-enc-require">
+      <term><literal>gss_enc_require</literal></term>
+      <listitem>
+       <para>
+        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.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry id="libpq-connect-service" xreflabel="service">
       <term><literal>service</literal></term>
       <listitem>
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.
    </para>
   </sect2>
+
+  <sect2>
+   <title><acronym>GSSAPI</acronym> Session Encryption</title>
+
+   <para>
+    If <productname>PostgreSQL</> was built with
+    <acronym>GSSAPI</acronym> and <acronym>GSSAPI</acronym> support, traffic
+    can also be encrypted using <acronym>GSSAPI</acronym>. To force encryption
+    using <acronym>GSSAPI</acronym>, set require_encrypt in
+    <filename>pg_hba.conf</filename>.
+   </para>
+
+   <para>
+    In order to probe for <acronym>GSSAPI</acronym> support, the client will
+    include in their StartupMessage the parameter gss_encrypt. If the server
+    does not support <acronym>GSSAPI</acronym> or <acronym>GSSAPI</acronym>
+    encryption, the server will error the connection; otherwise, it continues
+    as normal. The client may retry the connection
+    without <acronym>GSSAPI</acronym> encryption support depending on its
+    settings. If the client does not probe support, depending on settings
+    in <filename>pg_hba.conf</filename>, the server may drop
+    <acronym>GSSAPI</acronym>-authenticated connections without encryption.
+   </para>
+
+   <para>
+    If the client has probed <acronym>GSSAPI</acronym> encryption support and
+    the connection is <acronym>GSSAPI</acronym>-authenticated, then after the
+    server sends AuthenticationOk, all traffic between the client and server
+    will be <acronym>GSSAPI</acronym>-encrypted. Because
+    <acronym>GSSAPI</acronym> does not provide framing,
+    <acronym>GSSAPI</acronym>-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.
+   </para>
+
+   <para>
+     It is valid to use <acronym>GSSAPI</acronym> encryption over
+     <acronym>SSL</acronym>-encrypted connections.
+   </para>
+  </sect2>
  </sect1>
 
 <sect1 id="protocol-replication">
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
   </para>
 
   <para>
-   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 <literal>hostssl</> connections (<xref
@@ -1843,6 +1843,15 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
    <literal>verify-full</> and have the appropriate root certificate
    file installed (<xref linkend="libq-ssl-certificates">).
   </para>
+
+  <para>
+   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 <literal>require_encrypt</> in <filename>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.
+  </para>
  </sect1>
 
  <sect1 id="encryption-options">
@@ -1958,6 +1967,15 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
       connect to servers only via SSL. <application>Stunnel</> or
       <application>SSH</> can also be used to encrypt transmissions.
      </para>
+
+     <para>
+      GSSAPI connections can also encrypt all data sent across the
+      network. In the <filename>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.
+     </para>
     </listitem>
   </varlistentry>
 
-- 
2.1.4

