GSSAPI documentation

doc/src/sgml/client-auth.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.98 2007/03/24 21:46:23 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.99 2007/07/18 12:00:47 mha Exp $ -->
 
 <chapter id="client-authentication">
  <title>Client Authentication</title>
@@ -347,6 +347,17 @@ hostnossl  <replaceable>database</replaceable>  <replaceable>user</replaceable>
         </listitem>
        </varlistentry>
 
+       <varlistentry>
+        <term><literal>gss</></term>
+        <listitem>
+         <para>
+          Use GSSAPI to authenticate the user. This is only 
+          available for TCP/IP connections. See <xref
+          linkend="gssapi-auth"> for details.
+         </para>
+        </listitem>
+       </varlistentry>
+
        <varlistentry>
         <term><literal>krb5</></term>
         <listitem>
@@ -635,6 +646,37 @@ local   db1,db2,@demodbs  all                         md5
 
   </sect2>
 
+  <sect2 id="gssapi-auth">
+   <title>GSSAPI authentication</title>
+
+   <indexterm zone="gssapi-auth">
+    <primary>GSSAPI</primary>
+   </indexterm>
+
+   <para>
+    <productname>GSSAPI</productname> is an industry-standard protocol
+    for secure authentication defined in RFC2743. 
+    <productname>PostgreSQL</productname> supports
+    <productname>GSSAPI</productname> with <productname>Kerberos</productname>
+    authentication according to RFC1964. <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 connection will be in clear unless
+    <acronym>SSL</acronym> is used.
+   </para>
+
+   <para>
+    When <productname>GSSAPI</productname> uses
+    <productname>Kerberos</productname>, it uses a standard principal
+    in format
+    <literal><replaceable>servicename</>/<replaceable>hostname</>@<replaceable>realm</></literal>. For information about the parts of the principal, and
+    how to set up the required keys, see <xref linkend="kerberos-auth">.
+    GSSAPI support has to be enabled when <productname>PostgreSQL</> is built;
+    see <xref linkend="installation"> for more information.
+   </para>
+   
+  </sect2>
+
   <sect2 id="kerberos-auth">
    <title>Kerberos authentication</title>
 

doc/src/sgml/config.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.130 2007/06/30 19:12:01 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.131 2007/07/18 12:00:47 mha Exp $ -->
 
 <chapter Id="runtime-config">
   <title>Server Configuration</title>
@@ -609,8 +609,8 @@ SET ENABLE_SEQSCAN TO OFF;
       <listitem>
        <para>
         Sets the location of the Kerberos server key file. See
-        <xref linkend="kerberos-auth"> for details. This parameter
-        can only be set at server start.
+        <xref linkend="kerberos-auth"> or <xref linkend="gssapi-auth"> 
+        for details. This parameter can only be set at server start.
        </para>
       </listitem>
      </varlistentry>
@@ -652,7 +652,8 @@ SET ENABLE_SEQSCAN TO OFF;
       </indexterm>
       <listitem>
        <para>
-        Sets whether Kerberos user names should be treated case-insensitively.
+        Sets whether Kerberos and GSSAPI user names should be treated
+        case-insensitively.
         The default is <literal>off</> (case sensitive). This parameter
         can only be set at server start.
        </para>

doc/src/sgml/installation.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.289 2007/04/25 13:01:41 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.290 2007/07/18 12:00:47 mha Exp $ -->
 
 <chapter id="installation">
  <title><![%standalone-include[<productname>PostgreSQL</>]]>
@@ -801,6 +801,23 @@ su - postgres
        </listitem>
       </varlistentry>
 
+      <varlistentry>
+       <term><option>--with-gssapi</option></term>
+       <listitem>
+        <para>
+         Build with support for GSSAPI authentication. On many
+         systems, the GSSAPI (usually a part of the Kerberos installation)
+         system is not installed in a location
+         that is searched by default (e.g., <filename>/usr/include</>,
+         <filename>/usr/lib</>), so you must use the options
+         <option>--with-includes</> and <option>--with-libraries</> in
+         addition to this option.  <filename>configure</> will check
+         for the required header files and libraries to make sure that
+         your GSSAPI installation is sufficient before proceeding.
+        </para>
+       </listitem>
+      </varlistentry>
+
       <varlistentry>
        <term><option>--with-krb5</option></term>
        <listitem>
@@ -821,9 +838,12 @@ su - postgres
        <term><option>--with-krb-srvnam=<replaceable>NAME</></option></term>
        <listitem>
         <para>
-         The default name of the Kerberos service principal.
+         The default name of the Kerberos service principal (also used
+         by GSSAPI).
          <literal>postgres</literal> is the default. There's usually no
-         reason to change this.
+         reason to change this unless you have a Windows environment,
+         in which case it must be set to uppercase
+         <literal>POSTGRES</literal>.
         </para>
        </listitem>
       </varlistentry>

doc/src/sgml/libpq.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.237 2007/07/08 18:28:55 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.238 2007/07/18 12:00:47 mha Exp $ -->
 
  <chapter id="libpq">
   <title><application>libpq</application> - C Library</title>
@@ -131,7 +131,7 @@ PGconn *PQconnectdb(const char *conninfo);
      <para>
       Using <literal>hostaddr</> instead of <literal>host</> allows the
       application to avoid a host name look-up, which might be important in
-      applications with time constraints. However, Kerberos authentication
+      applications with time constraints. However, Kerberos and GSSAPI authentication
       requires the host name. The following therefore applies: If
       <literal>host</> is specified without <literal>hostaddr</>, a host name
       lookup occurs. If <literal>hostaddr</> is specified without
@@ -281,10 +281,11 @@ PGconn *PQconnectdb(const char *conninfo);
      <term><literal>krbsrvname</literal></term>
      <listitem>
       <para>
-       Kerberos service name to use when authenticating with Kerberos 5.
+       Kerberos service name to use when authenticating with Kerberos 5
+       or GSSAPI.
        This must match the service name specified in the server
        configuration for Kerberos authentication to succeed. (See also
-       <xref linkend="kerberos-auth">.)
+       <xref linkend="kerberos-auth"> and <xref linkend="gssapi-auth">.)
       </para>
      </listitem>
     </varlistentry>
@@ -4214,7 +4215,7 @@ set, the secret key must be kept in a file.
  <primary><envar>PGKRBSRVNAME</envar></primary>
 </indexterm>
 <envar>PGKRBSRVNAME</envar> sets the Kerberos service name to use when
-authenticating with Kerberos 5.
+authenticating with Kerberos 5 or GSSAPI.
 </para>
 </listitem>
 <listitem>

doc/src/sgml/protocol.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.67 2007/01/31 20:56:18 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.68 2007/07/18 12:00:47 mha Exp $ -->
 
 <chapter id="protocol">
  <title>Frontend/Backend Protocol</title>
@@ -230,11 +230,11 @@
     The server then sends an appropriate authentication request message,
     to which the frontend must reply with an appropriate authentication
     response message (such as a password).
-    In principle the authentication request/response cycle could require
-    multiple iterations, but none of the present authentication methods
-    use more than one request and response.  In some methods, no response
+    For all authentication methods except GSSAPI, there is at most
+    one request and one response. In some methods, no response
     at all is needed from the frontend, and so no authentication request
-    occurs.
+    occurs. For GSSAPI, multiple iterations of packets may be needed to 
+    complete the authentication.
    </para>
 
    <para>
@@ -332,6 +332,34 @@
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term>AuthenticationGSS</term>
+      <listitem>
+       <para>
+        The frontend must now initiate a GSSAPI negotiation. The frontend
+        will send a PasswordMessage with the first part of the GSSAPI
+        data stream in response to this. If further messages are needed,
+        the server will respond with AuthenticationGSSContinue.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>AuthenticationGSSContinue</term>
+      <listitem>
+       <para>
+        This message contains the response data from the previous step
+        of GSSAPI negotiation (AuthenticationGSS or a previous
+        AuthenticationGSSContinue). If the GSSAPI data in this message
+        indicates more data is needed to complete the authentication,
+        the frontend must send this data as another PasswordMessage. If
+        GSSAPI authentication is completed by this message, the server
+        will also send AuthenticationOk to indicate successful authentication
+        or ErrorResponse to indicate failure.
+       </para>
+      </listitem>
+     </varlistentry>
+
     </variablelist>
    </para>
 
@@ -1633,6 +1661,106 @@ AuthenticationSCMCredential (B)
 </varlistentry>
 
 
+<varlistentry>
+<term>
+AuthenticationGSS (B)
+</term>
+<listitem>
+<para>
+
+<variablelist>
+<varlistentry>
+<term>
+        Byte1('R')
+</term>
+<listitem>
+<para>
+                Identifies the message as an authentication request.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int32(8)
+</term>
+<listitem>
+<para>
+                Length of message contents in bytes, including self.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int32(7)
+</term>
+<listitem>
+<para>
+                Specifies that GSSAPI authentication is required.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term>
+AuthenticationGSSContinue (B)
+</term>
+<listitem>
+<para>
+
+<variablelist>
+<varlistentry>
+<term>
+        Byte1('R')
+</term>
+<listitem>
+<para>
+                Identifies the message as an authentication request.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int32
+</term>
+<listitem>
+<para>
+                Length of message contents in bytes, including self.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Int32(8)
+</term>
+<listitem>
+<para>
+                Specifies that this message contains GSSAPI data.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+        Byte<replaceable>n</replaceable>
+</term>
+<listitem>
+<para>
+                GSSAPI authentication data.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</para>
+</listitem>
+</varlistentry>
+
+
 <varlistentry>
 <term>
 BackendKeyData (B)
@@ -3317,7 +3445,8 @@ PasswordMessage (F)
 </term>
 <listitem>
 <para>
-                Identifies the message as a password response.
+                Identifies the message as a password response. Note that
+                this is also used by GSSAPI response messages.
 </para>
 </listitem>
 </varlistentry>