Re: [PATCH v2] GSSAPI encryption support

Michael Paquier <michael.paquier@gmail.com> writes:

> On Fri, Jul 3, 2015 at 3:22 AM, Robbie Harwood <rharwood@redhat.com> wrote:
>
>> Hello -hackers,
>>
>> As previously discussed on this list, I have coded up GSSAPI encryption
>> support.  If it is easier for anyone, this code is also available for
>> viewing on my github:
>>
>> https://github.com/postgres/postgres/compare/master...frozencemetery:feature/gssencrypt
>>
>> Fallback support is present in both directions for talking to old client
>> and old servers; GSSAPI encryption is by default auto-upgraded to where
>> available (for compatibility), but both client and server contain
>> settings for requiring it.
>>
>> There are 8 commits in this series; I have tried to err on the side of
>> creating too much separation rather than too little.  A patch for each
>> is attached.  This is v1 of the series.
>
> I just had a quick look at this patch, and here are some comments:
> +   <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>
> Message formats should be described in protocol.sgml in the section for
> message formats.
>
> +      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
> s/authenticaion/authentication
> s/requiested/requested
>
> +        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.
> s/compatability/compatibility

As promised, here's a V2 to address your issues with comments.  I
haven't heard back on the issues you found in testing, so no other
changes are present.

This means that only the last patch has changed.  For convenience, I
will therefore only provide this new patch.  I have also updated the
version available from my github.

Thanks!
From 2e9017a572a3097fecf2f7e53bf5f9aabf6ae36d Mon Sep 17 00:00:00 2001
From: "Robbie Harwood (frozencemetery)" <rharwood@redhat.com>
Date: Mon, 29 Jun 2015 15:29:36 -0400
Subject: [PATCH] Document GSSAPI encryption

---
 doc/src/sgml/client-auth.sgml | 19 ++++++++--
 doc/src/sgml/libpq.sgml       | 12 +++++++
 doc/src/sgml/protocol.sgml    | 82 ++++++++++++++++++++++++++++++++++++++++++-
 doc/src/sgml/runtime.sgml     | 20 ++++++++++-
 4 files changed, 128 insertions(+), 5 deletions(-)

diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index ba04bdf..0863468 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
+        compatibility 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 7940ef2..b80d29d 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..15e0014 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1295,6 +1295,42 @@
     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.  See message formats above.
+   </para>
+
+   <para>
+     It is valid to use <acronym>GSSAPI</acronym> encryption over
+     <acronym>SSL</acronym>-encrypted connections.
+   </para>
+  </sect2>
  </sect1>

 <sect1 id="protocol-replication">
@@ -2191,7 +2227,9 @@ Notice that although each message includes a byte count at the beginning,
 the message format is defined so that the message end can be found without
 reference to the byte count.  This aids validity checking.  (The CopyData
 message is an exception, because it forms part of a data stream; the contents
-of any individual CopyData message cannot be interpretable on their own.)
+of any individual CopyData message cannot be interpretable on their own.  The
+GSSAPI message type is another exception because GSSAPI does not require
+payloads to include length information.)
 </para>

 <variablelist>
@@ -3921,6 +3959,48 @@ FunctionCallResponse (B)
 </listitem>
 </varlistentry>

+<varlistentry>
+<term>
+GSSAPI (F & B)
+</term>
+<listitem>
+<para>
+<variablelist>
+<varlistentry>
+<term>
+        Byte1('g')
+</term>
+<listitem>
+<para>
+                Identifies the message as GSSAPI-encrypted data.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int32
+</term>
+<listitem>
+<para>
+                Length of message contents in bytes, including self.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Byte<replaceable>n</replaceable>
+</term>
+<listitem>
+<para>
+                GSSAPI-encrypted data.  Once decrypted, will be in a valid
+                message format.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</para>
+</listitem>
+</varlistentry>

 <varlistentry>
 <term>
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 6d5b108..0d65fd6 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1868,7 +1868,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
@@ -1878,6 +1878,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">
@@ -1993,6 +2002,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 GSSAPI authentication method has
+      a parameter to require encryption; otherwise, connections will be
+      encrypted if available and requested by the client. On the client side,
+      there is also a parameter to require GSSAPI encryption support from the
+      server.
+     </para>
     </listitem>
   </varlistentry>

--
2.5.1