the <literal>hostgssenc</literal> record is ignored except for logging

a warning that it cannot match any connections.

</para>

<para>

Note that the only supported

<link linkend="auth-methods">authentication methods</link> for use

with <acronym>GSSAPI</acronym> encryption

are <literal>gss</literal>, <literal>reject</literal>,

and <literal>trust</literal>.

</para>

</listitem>

</varlistentry>

<para>

<productname>GSSAPI</productname> is an industry-standard protocol

for secure authentication defined in RFC 2743.

for secure authentication defined in

<productname>PostgreSQL</productname>

supports <productname>GSSAPI</productname> foruse as either an encrypted,

authenticated layer, orfor authentication only.

supports <productname>GSSAPI</productname> forauthentication,

communications encryption, orboth.

<productname>GSSAPI</productname> provides automatic authentication

(single sign-on) for systems that support it. The authentication itself is

secure. If <productname>GSSAPI</productname> encryption

(see <literal>hostgssenc</literal>)or <acronym>SSL</acronym> encryptionare

or <acronym>SSL</acronym> encryptionis

used, the data sent along the database connection will be encrypted;

otherwise, it will not.

</para>

<para>

When <productname>GSSAPI</productname> uses

<productname>Kerberos</productname>, it uses a standardprincipal

in the format

<productname>Kerberos</productname>, it uses a standardservice

principal (authentication identity) namein the format

<literal><replaceable>servicename</replaceable>/<replaceable>hostname</replaceable>@<replaceable>realm</replaceable></literal>.

The PostgreSQL server will accept any principal that is included in the keytab used by

the server, but care needs to be taken to specify the correct principal details when

making the connection from the client using the <literal>krbsrvname</literal> connection parameter. (See

also <xref linkend="libpq-paramkeywords"/>.) The installation default can be

changed from the default <literal>postgres</literal> at build time using

<literal>./configure --with-krb-srvnam=</literal><replaceable>whatever</replaceable>.

In most environments,

this parameter never needs to be changed.

Some Kerberos implementations might require a different service name,

such as Microsoft Active Directory which requires the service name

to be in upper case (<literal>POSTGRES</literal>).

</para>

<para>

<replaceable>hostname</replaceable> is the fully qualified host name of the

server machine. The service principal's realm is the preferred realm

of the server machine.

</para>

<para>

Client principals can be mapped to different <productname>PostgreSQL</productname>

database user names with <filename>pg_ident.conf</filename>. For example,

The principal name used by a particular installation is not encoded in

the <productname>PostgreSQL</productname> server in any way; rather it

is specified in the <firstterm>keytab</firstterm> file that the server

reads to determine its identity. If multiple principals are listed in

the keytab file, the server will accept any one of them.

The server's realm name is the preferred realm specified in the Kerberos

configuration file(s) accessible to the server.

</para>

<para>

When connecting, the client must know the principal name of the server

it intends to connect to. The <replaceable>servicename</replaceable>

part of the principal is ordinarily <literal>postgres</literal>,

but another value can be selected via <application>libpq</application>'s

<xref linkend="libpq-connect-krbsrvname"/> connection parameter.

The <replaceable>hostname</replaceable> part is the fully qualified

host name that <application>libpq</application> is told to connect to.

The realm name is the preferred realm specified in the Kerberos

configuration file(s) accessible to the client.

</para>

<para>

The client will also have a principal name for its own identity

(and it must have a valid ticket for this principal). To

use <productname>GSSAPI</productname> for authentication, the client

principal must be associated with

a <productname>PostgreSQL</productname> database user name.

The <filename>pg_ident.conf</filename> configuration file can be used

to map principals to user names; for example,

<literal>pgusername@realm</literal> could be mapped to just <literal>pgusername</literal>.

Alternatively, you can use the full <literal>username@realm</literal> principal as

the role name in <productname>PostgreSQL</productname> without any mapping.

</para>

<para>

<productname>PostgreSQL</productname> also supports a parameter to strip the realm from

<productname>PostgreSQL</productname> also supports mapping

client principals to user names by just stripping the realm from

the principal. This method is supported for backwards compatibility and is

strongly discouraged as it is then impossible to distinguish different users

with the same user name but coming from different realms. To enable this,

</para>

<para>

Make sure that your server keytab file is readable (and preferably

only readable, not writable) by the <productname>PostgreSQL</productname>

server account. (See also <xref linkend="postgres-user"/>.) The location

of the key file is specified by the <xref

The location of the server's keytab file is specified by the <xref

linkend="guc-krb-server-keyfile"/> configuration

parameter. The default is

<filename>/usr/local/pgsql/etc/krb5.keytab</filename> (or whatever

directory was specified as <varname>sysconfdir</varname> at build time).

<filename>FILE:/usr/local/pgsql/etc/krb5.keytab</filename>

(where the directory part is whatever was specified

as <varname>sysconfdir</varname> at build time).

For security reasons, it is recommended to use a separate keytab

just for the <productname>PostgreSQL</productname> server rather

than opening up permissions on the system keytab file.

than allowing the server to read the system keytab file.

Make sure that your server keytab file is readable (and preferably

only readable, not writable) by the <productname>PostgreSQL</productname>

server account. (See also <xref linkend="postgres-user"/>.)

</para>

<para>

The keytab file is generated by the Kerberos software; see the

Kerberos documentation for details. The following example is

for MIT-compatible Kerberos 5 implementations:

The keytab file is generated using the Kerberos software; see the

Kerberos documentation for details. The following example shows

doing this using the <application>kadmin</application> tool of

MIT-compatible Kerberos 5 implementations:

<screen>

<prompt>kadmin% </prompt><userinput>ank -randkey postgres/server.my.domain.org</userinput>

<prompt>kadmin% </prompt><userinput>addprinc -randkey postgres/server.my.domain.org</userinput>

<prompt>kadmin% </prompt><userinput>ktadd -k krb5.keytab postgres/server.my.domain.org</userinput>

</screen>

</para>

<para>

When connecting to the database make sure you have a ticket for a

principal matching the requested database user name. For example, for

database user name <literal>fred</literal>, principal

<literal>fred@EXAMPLE.COM</literal> would be able to connect. To also allow

principal <literal>fred/users.example.com@EXAMPLE.COM</literal>, use a user name

map, as described in <xref linkend="auth-username-maps"/>.

</para>

<para>

The following configuration options are supported for <productname>GSSAPI</productname>:

The following authentication options are supported for

the <productname>GSSAPI</productname> authentication method:

<variablelist>

<varlistentry>

<term><literal>include_realm</literal></term>

<term><literal>map</literal></term>

<listitem>

<para>

Allowsformappingbetween system and database user names. See

Allows mappingfrom client principals to database user names. See

<xref linkend="auth-username-maps"/> for details. For a GSSAPI/Kerberos

principal, such as <literal>username@EXAMPLE.COM</literal> (or, less

commonly, <literal>username/hostbased@EXAMPLE.COM</literal>), the

</varlistentry>

</variablelist>

</para>

<para>

In addition to these settings, which can be different for

different <filename>pg_hba.conf</filename> entries, there is the

server-wide <xref linkend="guc-krb-caseins-users"/> configuration

parameter. If that is set to true, client principals are matched to

user map entries case-insensitively. <literal>krb_realm</literal>, if

set, is also matched case-insensitively.

</para>

</sect1>

<sect1 id="sspi-auth">

connection.<indexterm><primary>SSL</primary><secondary

sortas="libpq">with libpq</secondary></indexterm>

</para>

<para>

Note that if <acronym>GSSAPI</acronym> encryption is possible,

that will be used in preference to <acronym>SSL</acronym>

encryption, regardless of the value of <literal>sslmode</literal>.

To force use of <acronym>SSL</acronym> encryption in an

environment that has working <acronym>GSSAPI</acronym>

infrastructure (such as a Kerberos server), also

set <literal>gssencmode</literal> to <literal>disable</literal>.

</para>

</listitem>

</varlistentry>

This must match the service name specified in the server

configuration for Kerberos authentication to succeed. (See also

<xref linkend="gssapi-auth"/>.)

The default value is normally <literal>postgres</literal>,

but that can be changed when

building <productname>PostgreSQL</productname> via

the <option>--with-krb-srvnam</option> option

of <application>configure</application>.

In most environments, this parameter never needs to be changed.

Some Kerberos implementations might require a different service name,

such as Microsoft Active Directory which requires the service name

to be in upper case (<literal>POSTGRES</literal>).

</para>

</listitem>

</varlistentry>

<acronym>SSL</acronym>-encrypted. To continue after

<literal>N</literal>, send the usual StartupMessage and proceed without

encryption.

(Alternatively, it is permissible to issue a GSSENCRequest message

after an <literal>N</literal> response to try to

use <acronym>GSSAPI</acronym> encryption instead

of <acronym>SSL</acronym>.)

</para>

<para>

result from the server, until it returns no output. When sending the

results of <function>gss_init_sec_context()</function> to the server,

prepend the length of the message as a four byte integer in network byte

order. If this is successful, then use <function>gss_wrap()</function> to

encrypt the usual StartupMessage and all subsequent data, prepending the

length of the result from <function>gss_wrap()</function> as a four byte

integer in network byte order to the actual encrypted payload. Note that

the server will only accept encrypted packets from the client which are less

than 16kB; <function>gss_wrap_size_limit()</function> should be used by the

client to determine the size of the unencrypted message which will fit

within this limit and larger messages should be broken up into multiple

<function>gss_wrap()</function> calls. Typical segments are 8kB of

unencrypted data, resulting in encrypted packets of slightly larger than 8kB

but well within the 16kB maximum. The server can be expected to not send

encrypted packets of larger than 16kB to the client. To continue after

order.

To continue after

<literal>N</literal>, send the usual StartupMessage and proceed without

encryption.

(Alternatively, it is permissible to issue an SSLRequest message

after an <literal>N</literal> response to try to

use <acronym>SSL</acronym> encryption instead

of <acronym>GSSAPI</acronym>.)

</para>

<para>

support to <productname>PostgreSQL</productname>. In this case the

connection must be closed, but the frontend might choose to open a fresh

connection and proceed without requesting <acronym>GSSAPI</acronym>

encryption. Given the length limits specified above, the ErrorMessage can

not be confused with a proper response from the server with an appropriate

length.

encryption.

</para>

<para>

An initial GSSENCRequest can also be used in a connection that is being

opened to send a CancelRequest message.

</para>

<para>

Once <acronym>GSSAPI</acronym> encryption has been successfully

established, use <function>gss_wrap()</function> to

encrypt the usual StartupMessage and all subsequent data, prepending the

length of the result from <function>gss_wrap()</function> as a four byte

integer in network byte order to the actual encrypted payload. Note that

the server will only accept encrypted packets from the client which are less

than 16kB; <function>gss_wrap_size_limit()</function> should be used by the

client to determine the size of the unencrypted message which will fit

within this limit and larger messages should be broken up into multiple

<function>gss_wrap()</function> calls. Typical segments are 8kB of

unencrypted data, resulting in encrypted packets of slightly larger than 8kB

but well within the 16kB maximum. The server can be expected to not send

encrypted packets of larger than 16kB to the client.

</para>

<para>

While the protocol itself does not provide a way for the server to

force <acronym>GSSAPI</acronym> encryption, the administrator can

<productname>PostgreSQL</productname> also has native support for

using <acronym>GSSAPI</acronym> to encrypt client/server communications for

increased security. Support requires that a <acronym>GSSAPI</acronym>

implementation (such as MITkrb5) is installed on both client and server

implementation (such as MITKerberos) is installed on both client and server

systems, and that support in <productname>PostgreSQL</productname> is

enabled at build time (see <xref linkend="installation"/>).

</para>

some or all connections.

</para>

<para>

When using <acronym>GSSAPI</acronym> for encryption, it is common to

use <acronym>GSSAPI</acronym> for authentication as well, since the

underlying mechanism will determine both client and server identities

(according to the <acronym>GSSAPI</acronym> implementation) in any

case. But this is not required;

another <productname>PostgreSQL</productname> authentication method

can be chosen to perform additional verification.

</para>

<para>

Other than configuration of the negotiation

behavior, <acronym>GSSAPI</acronym> encryption requires no setup beyond

errmsg("connection requires a valid client certificate")));

}

if (port->gss->enc&&port->hba->auth_method!=uaReject&&

port->hba->auth_method!=uaGSS)

{

ereport(FATAL, (errcode(ERRCODE_INVALID_AUTHORIZATION_SPECIFICATION),

errmsg("GSSAPI encryption can only be used with gss, trust, or reject authentication methods")));

}

caseuaGSS:

if (port->gss==NULL)

port->gss= (pg_gssinfo*)

MemoryContextAllocZero(TopMemoryContext,

sizeof(pg_gssinfo));

port->gss->auth= true;

if (port->gss->enc)

status=pg_GSS_checkauth(port);

caseuaSSPI:

if (port->gss==NULL)

port->gss= (pg_gssinfo*)

MemoryContextAllocZero(TopMemoryContext,

sizeof(pg_gssinfo));

sendAuthRequest(port,AUTH_REQ_SSPI,NULL,0);

status=pg_SSPI_recvauth(port);

if (maj_stat!=GSS_S_COMPLETE&&maj_stat!=GSS_S_CONTINUE_NEEDED)

{

gss_delete_sec_context(&lmin_s,&port->gss->ctx,GSS_C_NO_BUFFER);

pg_GSS_error(ERROR,

_("accepting GSS security context failed"),

pg_GSS_error(_("accepting GSS security context failed"),

maj_stat,min_stat);

returnSTATUS_ERROR;

}

if (maj_stat==GSS_S_CONTINUE_NEEDED)

maj_stat=gss_display_name(&min_stat,port->gss->name,&gbuf,NULL);

if (maj_stat!=GSS_S_COMPLETE)

_("retrieving GSS user name failed"),

pg_GSS_error(_("retrieving GSS user name failed"),

maj_stat,min_stat);

returnSTATUS_ERROR;

}