-<!-- $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>
</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>
<para>
</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>
-<!-- $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>
<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>
</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>
-<!-- $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</>]]>
</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>
<para>
<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>
-<!-- $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>
<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
<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>
<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>
-<!-- $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>
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>
</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>
<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)
</term>
<listitem>
</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>