<!-- $PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.137 2010/04/21 03:32:53 tgl Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.138 2010/05/26 23:49:18 tgl Exp $ -->

<chapter id="client-authentication">

<title>Client Authentication</title>

<listitem>

<para>

Reject the connection unconditionally. This is useful for

<quote>filtering out</> certain hosts from a group,e.g. a

<literal>reject</> lineblocks a specific host from connecting,

but a later line allows the remaining hosts in a specific

<quote>filtering out</> certain hosts from a group,for example a

<literal>reject</> linecould block a specific host from connecting,

while a later line allows the remaining hosts in a specific

network to connect.

</para>

</listitem>

After the <replaceable>auth-method</> field, there can be field(s) of

the form <replaceable>name</><literal>=</><replaceable>value</> that

specify options for the authentication method. Details about which

options are available for which authenticationmethod appear below.

options are available for which authenticationmethods appear below.

</para>

</listitem>

</varlistentry>

in a map should be thought of as meaning <quote>this operating system

user is allowed to connect as this database user</quote>, rather than

implying that they are equivalent. The connection will be allowed if

there is any map entry thatmatches the user name obtained from the

external authentication systemto the database user name that the

there is any map entry thatpairs the user name obtained from the

external authentication systemwith the database user name that the

user has requested to connect as.

</para>

<para>

If the <replaceable>system-username</> field starts with a slash (<literal>/</>),

the remainder of the field is treated as a regular expression.

(See <xref linkend="posix-syntax-details"> for details of

<productname>PostgreSQL</>'s regular expression syntax.

Regular expressions in username maps are always treated as being

<quote>advanced</> flavor.) The regular

<productname>PostgreSQL</>'s regular expression syntax.) The regular

expression can include a single capture, or parenthesized subexpression,

which can then be referenced in the <replaceable>database-username</>

field as <literal>\1</> (backslash-one). This allows the mapping of

The password-based authentication methods are <literal>md5</>

and <literal>password</>. These methods operate

similarly except for the way that the password is sent across the

connection,i.e. respectively,MD5-hashed and clear-text.

connection,namelyMD5-hashed and clear-text respectively.

</para>

<para>

authentication according to RFC 1964. <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 database connection will besend unencrypted unless

data sent over the database connection will besent unencrypted unless

<acronym>SSL</acronym> is used.

</para>

in the 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">.

</para>

<para>

GSSAPI support has to be enabled when <productname>PostgreSQL</> is built;

see <xref linkend="installation"> for more information.

</para>

<listitem>

<para>

Allows for mapping between system and database usernames. See

<xref linkend="auth-username-maps"> for details. For aKerboros

<xref linkend="auth-username-maps"> for details. For aKerberos

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

username used for mapping is <literal>username/hostbased</literal>

if <literal>include_realm</literal> is disabled, and

Native Kerberos authentication has been deprecated and should be used

only for backward compatibility. New and upgraded installations are

encouraged to use the industry-standard <productname>GSSAPI</productname>

authentication (see <xref linkend="gssapi-auth">) instead.

authenticationmethod(see <xref linkend="gssapi-auth">) instead.

</para>

</note>

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

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

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

principle <literal>fred/users.example.com@EXAMPLE.COM</>, use a username

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

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

</para>

name (with an optional username mapping).

The determination of the client's

user name is the security-critical point, and it works differently

depending on the connection type.

depending on the connection type, as described below.

</para>

<para>

class="osname">Linux</>, <systemitem class="osname">FreeBSD</>,

<systemitem class="osname">NetBSD</>, <systemitem class="osname">OpenBSD</>,

<systemitem class="osname">BSD/OS</>, and <systemitem class="osname">Solaris</systemitem>), ident authentication can also

be applied to local connections. In this case, no security risk is added by

be applied to local connections.

<productname>PostgreSQL</> uses <symbol>SO_PEERCRED</symbol> to find out

the operating system name of the connected client process.

In this case, no security risk is added by

using ident authentication; indeed it is a preferable choice for

local connections on such systems.

</para>

<listitem>

<para>

Port number on LDAP server to connect to. If no port is specified,

the default portin the LDAP library will be used.

theLDAP library'sdefault portsetting will be used.

</para>

</listitem>

</varlistentry>

<term><literal>ldapbasedn</literal></term>

<listitem>

<para>

DN toroot the search for the user in, when doing search+bind

RootDN tobegin the search for the user in, when doing search+bind

authentication.

</para>

</listitem>

<para>

The shared secret used when talking securely to the RADIUS

server. This must have exactly the same value on the PostgreSQL

and RADIUS servers. It is recommended that thisis a string of

and RADIUS servers. It is recommended that thisbe a string of

at least 16 characters. This parameter is required.

<note>

<para>

<para>

The string used as <literal>NAS Identifier</> in the RADIUS

requests. This parameter can be used as a second parameter

identifying for example which database the user is attempting

identifying for example which databaseuserthe user is attempting

to authenticate as, which can be used for policy matching on

the RADIUS server. If no identifier is specified, the default

<literal>postgresql</> will be used.

authentication. It is therefore only available for SSL connections.

When using this authentication method, the server will require that

the client provide a valid certificate. No password prompt will be sent

to the client. The <literal>cn</literal> attribute of the certificate

to the client. The <literal>cn</literal> (Common Name) attribute of the

certificate

will be compared to the requested database username, and if they match

the login will be allowed. Username mapping can be used to allow

<literal>cn</literal> to be different from the database username.

<para>

<programlisting>

FATAL:Password authentication failed for user "andym"

FATAL:password authentication failed for user "andym"

</programlisting>

Messages like this indicate that you contacted the server, and it is

willing to talk to you, but not until you pass the authorization

<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.278 2010/05/20 20:32:27 tgl Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.279 2010/05/26 23:49:18 tgl Exp $ -->

<chapter Id="runtime-config">

<title>Server Configuration</title>

</para>

</listitem>

</varlistentry>

<varlistentry id="guc-ssl" xreflabel="ssl">

<term><varname>ssl</varname> (<type>boolean</type>)</term>

<indexterm>

</indexterm>

<listitem>

<para>

Specifies how much data can flow over an <acronym>SSL</> encrypted connection

before renegotiation of the session will take place. Renegotiation of the

session decreases the chance of doing cryptanalysis when large amounts of data

are sent, but it also carries a large performance penalty. The sum of

sent and received traffic is used to check the limit. If the parameter is

set to 0, renegotiation is disabled. The default is <literal>512MB</>.

Specifies how much data can flow over an <acronym>SSL</>-encrypted

connection before renegotiation of the session keys will take

place. Renegotiation decreases an attacker's chances of doing

cryptanalysis when large amounts of traffic can be examined, but it

also carries a large performance penalty. The sum of sent and received

traffic is used to check the limit. If this parameter is set to 0,

renegotiation is disabled. The default is <literal>512MB</>.

</para>

<note>

<para>

SSL libraries from before November 2009 are insecure when using SSL

renegotiation, due to a vulnerability in the SSL protocol. As a stop-gap fix

for this vulnerability, some vendors also shipped SSL libraries incapable

of doing renegotiation. If any of these libraries are in use on the client

or server, SSL renegotiation should be disabled.

renegotiation, due to a vulnerability in the SSL protocol. As a

stop-gap fix for this vulnerability, some vendors shipped SSL

libraries incapable of doing renegotiation. If any such libraries

are in use on the client or server, SSL renegotiation should be

disabled.

</para>

</note>

</listitem>