mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

GSSAPI documentation

Browse Source
This commit is contained in:
Magnus Hagander 2007-07-18 12:00:47 +00:00
parent 9e19063abc
commit dc32d2cefa
5 changed files with 212 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
doc/src/sgml/client-auth.sgml
View File

@ -1,4 +1,4 @@
<!-- $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>

9
doc/src/sgml/config.sgml
View File

@ -1,4 +1,4 @@
<!-- $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>

26
doc/src/sgml/installation.sgml
View File

@ -1,4 +1,4 @@
<!-- $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>

11
doc/src/sgml/libpq.sgml
View File

@ -1,4 +1,4 @@
<!-- $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>

141
doc/src/sgml/protocol.sgml
View File

@ -1,4 +1,4 @@
<!-- $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>