Skip to content

Commit dc32d2c

Browse files
mhagandermhagander
committed
GSSAPI documentation
1 parent 9e19063 commit dc32d2c

File tree

5 files changed

+212
-19
lines changed

5 files changed

+212
-19
lines changed

‎doc/src/sgml/client-auth.sgml

Lines changed: 43 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.98 2007/03/24 21:46:23 momjian Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.99 2007/07/18 12:00:47 mha Exp $ -->
22

33
<chapter id="client-authentication">
44
<title>Client Authentication</title>
@@ -347,6 +347,17 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
347347
</listitem>
348348
</varlistentry>
349349

350+
<varlistentry>
351+
<term><literal>gss</></term>
352+
<listitem>
353+
<para>
354+
Use GSSAPI to authenticate the user. This is only
355+
available for TCP/IP connections. See <xref
356+
linkend="gssapi-auth"> for details.
357+
</para>
358+
</listitem>
359+
</varlistentry>
360+
350361
<varlistentry>
351362
<term><literal>krb5</></term>
352363
<listitem>
@@ -635,6 +646,37 @@ local db1,db2,@demodbs all md5
635646

636647
</sect2>
637648

649+
<sect2 id="gssapi-auth">
650+
<title>GSSAPI authentication</title>
651+
652+
<indexterm zone="gssapi-auth">
653+
<primary>GSSAPI</primary>
654+
</indexterm>
655+
656+
<para>
657+
<productname>GSSAPI</productname> is an industry-standard protocol
658+
for secure authentication defined in RFC2743.
659+
<productname>PostgreSQL</productname> supports
660+
<productname>GSSAPI</productname> with <productname>Kerberos</productname>
661+
authentication according to RFC1964. <productname>GSSAPI</productname>
662+
provides automatic authentication (single sign-on) for systems
663+
that support it. The authentication itself is secure, but the
664+
data sent over the connection will be in clear unless
665+
<acronym>SSL</acronym> is used.
666+
</para>
667+
668+
<para>
669+
When <productname>GSSAPI</productname> uses
670+
<productname>Kerberos</productname>, it uses a standard principal
671+
in format
672+
<literal><replaceable>servicename</>/<replaceable>hostname</>@<replaceable>realm</></literal>. For information about the parts of the principal, and
673+
how to set up the required keys, see <xref linkend="kerberos-auth">.
674+
GSSAPI support has to be enabled when <productname>PostgreSQL</> is built;
675+
see <xref linkend="installation"> for more information.
676+
</para>
677+
678+
</sect2>
679+
638680
<sect2 id="kerberos-auth">
639681
<title>Kerberos authentication</title>
640682

‎doc/src/sgml/config.sgml

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.130 2007/06/30 19:12:01 tgl Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.131 2007/07/18 12:00:47 mha Exp $ -->
22

33
<chapter Id="runtime-config">
44
<title>Server Configuration</title>
@@ -609,8 +609,8 @@ SET ENABLE_SEQSCAN TO OFF;
609609
<listitem>
610610
<para>
611611
Sets the location of the Kerberos server key file. See
612-
<xref linkend="kerberos-auth"> for details. This parameter
613-
can only be set at server start.
612+
<xref linkend="kerberos-auth"> or <xref linkend="gssapi-auth">
613+
for details. This parameter can only be set at server start.
614614
</para>
615615
</listitem>
616616
</varlistentry>
@@ -652,7 +652,8 @@ SET ENABLE_SEQSCAN TO OFF;
652652
</indexterm>
653653
<listitem>
654654
<para>
655-
Sets whether Kerberos user names should be treated case-insensitively.
655+
Sets whether Kerberos and GSSAPI user names should be treated
656+
case-insensitively.
656657
The default is <literal>off</> (case sensitive). This parameter
657658
can only be set at server start.
658659
</para>

‎doc/src/sgml/installation.sgml

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.289 2007/04/25 13:01:41 momjian Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.290 2007/07/18 12:00:47 mha Exp $ -->
22

33
<chapter id="installation">
44
<title><![%standalone-include[<productname>PostgreSQL</>]]>
@@ -801,6 +801,23 @@ su - postgres
801801
</listitem>
802802
</varlistentry>
803803

804+
<varlistentry>
805+
<term><option>--with-gssapi</option></term>
806+
<listitem>
807+
<para>
808+
Build with support for GSSAPI authentication. On many
809+
systems, the GSSAPI (usually a part of the Kerberos installation)
810+
system is not installed in a location
811+
that is searched by default (e.g., <filename>/usr/include</>,
812+
<filename>/usr/lib</>), so you must use the options
813+
<option>--with-includes</> and <option>--with-libraries</> in
814+
addition to this option. <filename>configure</> will check
815+
for the required header files and libraries to make sure that
816+
your GSSAPI installation is sufficient before proceeding.
817+
</para>
818+
</listitem>
819+
</varlistentry>
820+
804821
<varlistentry>
805822
<term><option>--with-krb5</option></term>
806823
<listitem>
@@ -821,9 +838,12 @@ su - postgres
821838
<term><option>--with-krb-srvnam=<replaceable>NAME</></option></term>
822839
<listitem>
823840
<para>
824-
The default name of the Kerberos service principal.
841+
The default name of the Kerberos service principal (also used
842+
by GSSAPI).
825843
<literal>postgres</literal> is the default. There's usually no
826-
reason to change this.
844+
reason to change this unless you have a Windows environment,
845+
in which case it must be set to uppercase
846+
<literal>POSTGRES</literal>.
827847
</para>
828848
</listitem>
829849
</varlistentry>

‎doc/src/sgml/libpq.sgml

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.237 2007/07/08 18:28:55 tgl Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.238 2007/07/18 12:00:47 mha Exp $ -->
22

33
<chapter id="libpq">
44
<title><application>libpq</application> - C Library</title>
@@ -131,7 +131,7 @@ PGconn *PQconnectdb(const char *conninfo);
131131
<para>
132132
Using <literal>hostaddr</> instead of <literal>host</> allows the
133133
application to avoid a host name look-up, which might be important in
134-
applications with time constraints. However, Kerberos authentication
134+
applications with time constraints. However, Kerberos and GSSAPI authentication
135135
requires the host name. The following therefore applies: If
136136
<literal>host</> is specified without <literal>hostaddr</>, a host name
137137
lookup occurs. If <literal>hostaddr</> is specified without
@@ -281,10 +281,11 @@ PGconn *PQconnectdb(const char *conninfo);
281281
<term><literal>krbsrvname</literal></term>
282282
<listitem>
283283
<para>
284-
Kerberos service name to use when authenticating with Kerberos 5.
284+
Kerberos service name to use when authenticating with Kerberos 5
285+
or GSSAPI.
285286
This must match the service name specified in the server
286287
configuration for Kerberos authentication to succeed. (See also
287-
<xref linkend="kerberos-auth">.)
288+
<xref linkend="kerberos-auth"> and <xref linkend="gssapi-auth">.)
288289
</para>
289290
</listitem>
290291
</varlistentry>
@@ -4214,7 +4215,7 @@ set, the secret key must be kept in a file.
42144215
<primary><envar>PGKRBSRVNAME</envar></primary>
42154216
</indexterm>
42164217
<envar>PGKRBSRVNAME</envar> sets the Kerberos service name to use when
4217-
authenticating with Kerberos 5.
4218+
authenticating with Kerberos 5 or GSSAPI.
42184219
</para>
42194220
</listitem>
42204221
<listitem>

‎doc/src/sgml/protocol.sgml

Lines changed: 135 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.67 2007/01/31 20:56:18 momjian Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.68 2007/07/18 12:00:47 mha Exp $ -->
22

33
<chapter id="protocol">
44
<title>Frontend/Backend Protocol</title>
@@ -230,11 +230,11 @@
230230
The server then sends an appropriate authentication request message,
231231
to which the frontend must reply with an appropriate authentication
232232
response message (such as a password).
233-
In principle the authentication request/response cycle could require
234-
multiple iterations, but none of the present authentication methods
235-
use more than one request and response. In some methods, no response
233+
For all authentication methods except GSSAPI, there is at most
234+
one request and one response. In some methods, no response
236235
at all is needed from the frontend, and so no authentication request
237-
occurs.
236+
occurs. For GSSAPI, multiple iterations of packets may be needed to
237+
complete the authentication.
238238
</para>
239239

240240
<para>
@@ -332,6 +332,34 @@
332332
</listitem>
333333
</varlistentry>
334334

335+
<varlistentry>
336+
<term>AuthenticationGSS</term>
337+
<listitem>
338+
<para>
339+
The frontend must now initiate a GSSAPI negotiation. The frontend
340+
will send a PasswordMessage with the first part of the GSSAPI
341+
data stream in response to this. If further messages are needed,
342+
the server will respond with AuthenticationGSSContinue.
343+
</para>
344+
</listitem>
345+
</varlistentry>
346+
347+
<varlistentry>
348+
<term>AuthenticationGSSContinue</term>
349+
<listitem>
350+
<para>
351+
This message contains the response data from the previous step
352+
of GSSAPI negotiation (AuthenticationGSS or a previous
353+
AuthenticationGSSContinue). If the GSSAPI data in this message
354+
indicates more data is needed to complete the authentication,
355+
the frontend must send this data as another PasswordMessage. If
356+
GSSAPI authentication is completed by this message, the server
357+
will also send AuthenticationOk to indicate successful authentication
358+
or ErrorResponse to indicate failure.
359+
</para>
360+
</listitem>
361+
</varlistentry>
362+
335363
</variablelist>
336364
</para>
337365

@@ -1633,6 +1661,106 @@ AuthenticationSCMCredential (B)
16331661
</varlistentry>
16341662

16351663

1664+
<varlistentry>
1665+
<term>
1666+
AuthenticationGSS (B)
1667+
</term>
1668+
<listitem>
1669+
<para>
1670+
1671+
<variablelist>
1672+
<varlistentry>
1673+
<term>
1674+
Byte1('R')
1675+
</term>
1676+
<listitem>
1677+
<para>
1678+
Identifies the message as an authentication request.
1679+
</para>
1680+
</listitem>
1681+
</varlistentry>
1682+
<varlistentry>
1683+
<term>
1684+
Int32(8)
1685+
</term>
1686+
<listitem>
1687+
<para>
1688+
Length of message contents in bytes, including self.
1689+
</para>
1690+
</listitem>
1691+
</varlistentry>
1692+
<varlistentry>
1693+
<term>
1694+
Int32(7)
1695+
</term>
1696+
<listitem>
1697+
<para>
1698+
Specifies that GSSAPI authentication is required.
1699+
</para>
1700+
</listitem>
1701+
</varlistentry>
1702+
</variablelist>
1703+
1704+
</para>
1705+
</listitem>
1706+
</varlistentry>
1707+
1708+
1709+
<varlistentry>
1710+
<term>
1711+
AuthenticationGSSContinue (B)
1712+
</term>
1713+
<listitem>
1714+
<para>
1715+
1716+
<variablelist>
1717+
<varlistentry>
1718+
<term>
1719+
Byte1('R')
1720+
</term>
1721+
<listitem>
1722+
<para>
1723+
Identifies the message as an authentication request.
1724+
</para>
1725+
</listitem>
1726+
</varlistentry>
1727+
<varlistentry>
1728+
<term>
1729+
Int32
1730+
</term>
1731+
<listitem>
1732+
<para>
1733+
Length of message contents in bytes, including self.
1734+
</para>
1735+
</listitem>
1736+
</varlistentry>
1737+
<varlistentry>
1738+
<term>
1739+
Int32(8)
1740+
</term>
1741+
<listitem>
1742+
<para>
1743+
Specifies that this message contains GSSAPI data.
1744+
</para>
1745+
</listitem>
1746+
</varlistentry>
1747+
<varlistentry>
1748+
<term>
1749+
Byte<replaceable>n</replaceable>
1750+
</term>
1751+
<listitem>
1752+
<para>
1753+
GSSAPI authentication data.
1754+
</para>
1755+
</listitem>
1756+
</varlistentry>
1757+
</variablelist>
1758+
1759+
</para>
1760+
</listitem>
1761+
</varlistentry>
1762+
1763+
16361764
<varlistentry>
16371765
<term>
16381766
BackendKeyData (B)
@@ -3317,7 +3445,8 @@ PasswordMessage (F)
33173445
</term>
33183446
<listitem>
33193447
<para>
3320-
Identifies the message as a password response.
3448+
Identifies the message as a password response. Note that
3449+
this is also used by GSSAPI response messages.
33213450
</para>
33223451
</listitem>
33233452
</varlistentry>

0 commit comments

Comments
 (0)