-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.5 2000/08/29 04:15:43 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.6 2000/09/06 19:54:45 petere Exp $ -->
<chapter id="client-authentication">
<title>Client Authentication</title>
of a set of records, one per line. Blank lines and lines beginning
with a hash character (<quote>#</quote>) are ignored. A record is
made up of a number of fields which are separated by spaces and/or
- tabs.
+ tabs and cannot be continued across several lines.
</para>
<para>
- A record may have one of the two formats
+ A record may have one of the three formats
<synopsis>
-local <replaceable>database</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
-host <replaceable>database</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
+local <replaceable>database</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
+host <replaceable>database</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
</synopsis>
The meaning of the fields is as follows:
<listitem>
<para>
This record pertains to connection attemps with SSL over
- TCP/IP. Note that SSL connections are completely disabled
- unless the server is started with the <option>-i</option>,
- and also require ordinary TCP/IP connections to be enabled.
- SSL connections also require SSL support to be enabled in
- the backend at compile time.
+ TCP/IP. To make use of this option the server must be
+ built with SSL support enabled. Furthermore, SSL must be
+ enabled with the <option>-l</> option or equivalent configuration
+ setting when the server is started.
</para>
</listitem>
</varlistentry>
<para>
Specifies the database that this record applies to. The value
<literal>all</literal> specifies that it applies to all
- databases.
+ databases, the value <literal>sameuser</> identifies the
+ database with the same name as the connecting user.
</para>
</listitem>
</varlistentry>
<term><replaceable>authentication method</replaceable></term>
<listitem>
<para>
- Specifies the method a user must use to authenticate themselves
- when connecting to that database.
+ Specifies the method that users must use to authenticate themselves
+ when connecting to that database. The possible choices follow,
+ details are in <xref linkend="auth-methods">.
+
+ <variablelist>
+ <varlistentry>
+ <term>trust</>
+ <listitem>
+ <para>
+ The connection is allowed unconditionally. This method allows
+ any user that has login access to the client host to connect as
+ any user whatsoever.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>reject</>
+ <listitem>
+ <para>
+ The connection is rejected unconditionally. This is mostly
+ useful to <quote>filter out</> certain hosts from a group.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>password</>
+ <listitem>
+ <para>
+ The client is required to supply a password with the connection
+ attempt which is required to match the password that was set up
+ for the user.
+ </para>
+
+ <para>
+ An optional file name may be specified after the
+ <literal>password</literal> keyword. This file is expected to
+ contain a list of users that this record pertains to, and
+ optionally alternative passwords.
+ </para>
+
+ <para>
+ The password is sent over the wire in clear text. For better
+ protection, use the <literal>crypt</literal> method.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>crypt</>
+ <listitem>
+ <para>
+ Like the <literal>password</literal> method, but the password
+ is sent over the wire encrypted using a simple
+ challenge-response protocol. This is still not
+ cryptographically secure but it protects against incidental
+ wire-sniffing. The name of a file may follow the
+ <literal>crypt</literal> keyword that contains a list of users
+ that this record pertains to.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>krb4</>
+ <listitem>
+ <para>
+ Kerberos V4 is used to authenticate the user. This is only
+ available for TCP/IP connections.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>krb5</term>
+ <listitem>
+ <para>
+ Kerberos V5 is used to authenticate the user. This is only
+ available for TCP/IP connections.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ident</term>
+ <listitem>
+ <para>
+ The ident server on the client host is asked for the identity
+ of the connecting user. <productname>Postgres</productname>
+ then verifies whether the so identified operating system user
+ is allowed to connect as the database user that is requested.
+ The <replaceable>authentication option</replaceable> following
+ the <literal>ident</> keyword specifies the name of an
+ <firstterm>ident map</firstterm> that specifies which operating
+ system users equate with which database users. See below for
+ details.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
</para>
</listitem>
</varlistentry>
<listitem>
<para>
This field is interpreted differently depending on the
- authentication method.
+ authentication method, as described there.
</para>
</listitem>
</varlistentry>
</variablelist>
- The first record that matches a connection attempt is used. Note
- that there is no <quote>fall-through</quote> or
- <quote>backup</quote>, that is, if one record is chosen and the
+ The first record that matches a connection attempt is used. There
+ is no <quote>fall-through</> or <quote>backup</>, that means, if
+ one record is chosen and the
authentication fails, the following records are not considered. If
no record matches, the access will be denied.
</para>
<example id="example-pg-hba.conf">
<title>An example <filename>pg_hba.conf</filename> file</title>
<programlisting>
-# Trust any connection via Unix domain sockets.
-local trust
-# Trust any connection via TCP/IP from this machine.
-host all 127.0.0.1 255.255.255.255 trust
-# We don't like this machine.
-host all 192.168.0.10 255.255.255.0 reject
-# This machine can't encrypt so we ask for passwords in clear.
-host all 192.168.0.3 255.255.255.0 password
-# The rest of this group of machines should provide encrypted passwords.
-host all 192.168.0.0 255.255.255.0 crypt
-# Authenticate these networks using ident
-host all 192.168.1.0 255.255.255.0 ident usermap
-host all 192.168.2.0 255.255.255.0 ident othermap
+#TYPE DATABASE IP-ADDRESS MASK AUTHTYPE ARG
+
+# Allow any user on the local system to connect to any database under
+# any user name.
+#
+host all 127.0.0.1 255.255.255.255 trust
+
+# Allow any user from any host with IP address 192.168.93.x to connect
+# to database "template1" as the same user name that ident on that
+# host identifies him as (typically his Unix user name).
+#
+host template1 192.168.93.0 255.255.255.0 ident sameuser
+
+# Allow a user from host 192.168.12.10 to connect to database
+# "template1" if the user's password in pg_shadow is supplied.
+#
+host template1 192.168.12.10 255.255.255.255 crypt
+
+# In absence of the other records, this would allow anyone anywhere
+# except from 192.168.54.1 to connect to any database under any user
+# name.
+#
+host all 192.168.54.1 255.255.255.255 reject
+host all 0.0.0.0 0.0.0.0 trust
+
+# Allow users from 192.168.77.x hosts to connect to any database, but if,
+# for example, ident says the user is "bryanh" and he requests to
+# connect as PostgreSQL user "guest1", the connection is only allowed if
+# there is an entry for map "omicron" in `pg_ident.conf' that says
+# "bryanh" is allowed to connect as "guest1".
+#
+host all 192.168.77.0 255.255.255.0 ident omicron
+
+# Allow all users to connect to all databases via Unix sockets.
+#
+local all trust
</programlisting>
</example>
</para>
<sect1 id="auth-methods">
<title>Authentication methods</title>
<para>
- The following authentication methods are supported. They are
- descibed in detail below.
-
- <variablelist>
- <varlistentry>
- <term>trust</term>
- <listitem>
- <para>
- The connection is allowed unconditionally. This method allows
- any user that has login access to the client host to connect as
- any user whatsoever. Use with care.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>reject</term>
- <listitem>
- <para>
- The connection is rejected unconditionally. This is mostly
- useful to <quote>filter out</quote> certain hosts from a group.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>password</term>
- <listitem>
- <para>
- The client is required to supply a password with the connection
- attempt which is required to match the password that was set up
- for the user.
- </para>
- <para>
- An optional file name may be specified after the
- <literal>password</literal> keyword. This file is expected to
- contain a list of users that this record pertains to, and
- optionally alternative passwords.
- </para>
- <para>
- The password is sent over the wire in clear text. For better
- protection, use the <literal>crypt</literal> method.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>crypt</term>
- <listitem>
- <para>
- Like the <literal>password</literal> method, but the password
- is sent over the wire encrypted using a simple
- challenge-response protocol. This is still not
- cryptographically secure but it protects against incidental
- wire-sniffing. The name of a file may follow the
- <literal>crypt</literal> keyword that contains a list of users
- that this record pertains to.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>krb4</term>
- <listitem>
- <para>
- Kerberos V4 is used to authenticate the user. This is only
- available for TCP/IP connections.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>krb5</term>
- <listitem>
- <para>
- Kerberos V5 is used to authenticate the user. This is only
- available for TCP/IP connections.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ident</term>
- <listitem>
- <para>
- The ident server on the client host is asked for the identity
- of the connecting user. <productname>Postgres</productname>
- then verifies whether the so identified operating system user
- is allowed to connect as the database user that is requested.
- The <replaceable>authentication option</replaceable> following
- the <literal>ident</> keyword specifies the name of an
- <firstterm>ident map</firstterm> that specifies which operating
- system users equate with which database users. See below for
- details.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
+ The following describes the authentication methods in detail.
</para>
<sect2>
<para>
To generate the keytab file, use for example (with version 5)
<screen>
-kadmin% <userinput>ank -randkey postgres/server.my.domain.org</>
-kadmin% <userinput>ktadd -k krb5.keytab postgres/server.my.domain.org</>
+<prompt>kadmin% </><userinput>ank -randkey postgres/server.my.domain.org</>
+<prompt>kadmin% </><userinput>ktadd -k krb5.keytab postgres/server.my.domain.org</>
</screen>
Read the <productname>Kerberos</> documentation for defails.
</para>
conjunction with the <filename>pg_hba.conf</> file in <xref
linkend="example-pg-hba.conf"> is shown in <xref
linkend="example-pg-ident.conf">. In that example setup, anyone
- logged in to a machine on the 192.168.1 network that does not have
- the a user name joe, robert, or ann would not be granted access.
+ logged in to a machine on the 192.168.77 network that does not have
+ the a user name bryanh, ann, or robert would not be granted access.
Unix user robert would only be allowed access when he tries to
connect as <quote>bob</quote>, not as <quote>robert</quote> or
- anyone else. <quote>ann</quote> and <quote>joe</quote> would only
- be allowed to connect <quote>as themselves</quote>. On the
- 192.168.2 network, however, a user <quote>ann</quote> would not be
- allowed to connect at all, only the user <quote>bob</> can connect
- as <quote>bob</> and some user <quote>karl</> can connect as
- <quote>joe</> as well.
+ anyone else. <quote>ann</quote> would only be allowed to connect
+ <quote>as herself</>. User bryanh would be allowed to connect as either
+ <quote>bryanh</> himself or as <quote>guest1</>.
</para>
<example id="example-pg-ident.conf">
<title>An example <filename>pg_ident.conf</> file</title>
<programlisting>
-usermap joe joe
-# bob has username robert on these machines
-usermap robert bob
-usermap ann ann
+#MAP IDENT-NAME POSTGRESQL-NAME
-othermap joe joe
-othermap bob bob
-othermap karl joe
+omicron bryanh bryanh
+omicron ann ann
+# bob has username robert on these machines
+omicron robert bob
+# bryanh can also connect as guest1
+omicron bryanh guest1
</programlisting>
</example>
</sect2>
</sect1>
</chapter>
-
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.23 2000/08/29 20:02:07 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.24 2000/09/06 19:54:45 petere Exp $
-->
<Chapter Id="runtime">
</listitem>
</varlistentry>
- <varlistentry>
- <term>TCPIP_SOCKET (<type>boolean</type>)</term>
- <listitem>
- <para>
- If this is true, then the server will accept TCP/IP
- connections. Otherwise only local Unix domain socket
- connections are accepted. It is off by default. This option
- can only be set at server start.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term>PORT (<type>integer</type>)</term>
<listitem>
</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term>SSL (<type>boolean</type>)</term>
+ <listitem>
+ <para>
+ Enables <acronym>SSL</> connections. Please read
+ <xref linkend="ssl"> before using this. The default
+ is off.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>TCPIP_SOCKET (<type>boolean</type>)</term>
+ <listitem>
+ <para>
+ If this is true, then the server will accept TCP/IP
+ connections. Otherwise only local Unix domain socket
+ connections are accepted. It is off by default. This option
+ can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</para>
</sect2>
<entry>tcpip_socket = on</entry>
<entry></entry>
</row>
+ <row>
+ <entry>-l</entry>
+ <entry>ssl = on</entry>
+ <entry></entry>
+ </row>
<row>
<entry>-N <replaceable>x</replaceable></entry>
<entry>max_connections = <replaceable>x</replaceable></entry>
</para>
</sect1>
- <sect1>
- <title>Secure TCP/IP Connection with SSL</title>
+ <sect1 id="ssl">
+ <title>Secure TCP/IP Connections with SSL</title>
<para>
- PostgreSQL has native support for connections over SSL to encrypt
+ <productname>PostgreSQL</> has native support for connections over
+ <acronym>SSL</> to encrypt
client/server communications for increased security. This requires
<productname>OpenSSL</productname> to be installed on both client
- and server systems and support enabled at compile-time using
- the configure script.
+ and server systems and support enabled at build-time (see <xref
+ linkend="installation">).
</para>
<para>
- With SSL support compiled in, the Postgres backend can be
- started with argument -l to enable SSL connections.
- When starting in SSL mode, the postmaster will look for the
- files <filename>server.key</filename> and
- <filename>server.cert</filename> in the <envar>PGDATA</envar>
- directory. These files should contain the server private key and
- certificate respectively. If the private key is protected with a
- passphrase, the postmaster will prompt for the passphrase and not
- start until it has been provided.
+ With SSL support compiled in, the <productname>PostgreSQL</> server
+ can be started with the argument <option>-l</> (ell) to enable
+ SSL connections. When starting in SSL mode, the postmaster will look
+ for the files <filename>server.key</> and <filename>server.crt</> in
+ the data directory. These files should contain the server private key
+ and certificate respectively. These files must be set up correctly
+ before an SSL-enabled server can start. If the private key is protected
+ with a passphrase, the postmaster will prompt for the passphrase and will
+ not start until it has been provided.
</para>
<para>
The postmaster will listen for both standard and SSL connections
on the same TCP/IP port, and will negotiate with any connecting
- client wether to use SSL or not. Use the <filename>pg_hba.conf</filename>
- file to optionally require SSL in order to accept a connection.
+ client wether to use SSL or not. See <xref linkend="client-authentication">
+ about how to force on the server side the use of SSL for certain
+ connections.
</para>
<para>
For details on how to create your server private key and certificate,
- refer to the OpenSSL documentation. A simple self-signed certificate
- can be used to get started testing, but a certificate signed by a CA
- (either one of the global CAs or a local one) should be used in
+ refer to the <productname>OpenSSL</> documentation. A simple self-signed
+ certificate can be used to get started testing, but a certificate signed
+ by a CA (either one of the global CAs or a local one) should be used in
production so the client can verify the servers identity. To create
a quick self-signed certificate, use the <filename>CA.pl</filename>
script included in OpenSSL:
<programlisting>
- CA.pl -newcert
+CA.pl -newcert
</programlisting>
Fill out the information the script asks for. Make sure to enter
- the local hostname as Common Name. The script will generate a key
- which is passphrase protected. To remove the passphrase (required
+ the local host name as Common Name. The script will generate a key
+ that is passphrase protected. To remove the passphrase (required
if you want automatic start-up of the postmaster), run the command
<programlisting>
- openssl x509 -inform PEM -outform PEM -in newreq.pem -out newkey_no_passphrase.pem
+openssl x509 -inform PEM -outform PEM -in newreq.pem -out newkey_no_passphrase.pem
</programlisting>
Enter the old passphrase to unlock the existing key. Copy the file
- <filename>newreq.pem</filename> to <filename>PGDATA/server.cert</filename>
- and <filename>newkey_no_passphrase.pem</filename> to
- <filename>PGDATA/server.key</filename>. Remove the PRIVATE KEY part
- from the <filename>server.cert</filename> using any text editor.
+ <filename>newreq.pem</> to <filename><replaceable>PGDATA</>/server.crt</>
+ and <filename>newkey_no_passphrase.pem</> to
+ <filename><replaceable>PGDATA</>/server.key</>. Remove the PRIVATE KEY part
+ from the <filename>server.crt</filename> using any text editor.
</para>
</sect1>
<sect1>
- <title>Secure TCP/IP Connection with SSH</title>
+ <title>Secure TCP/IP Connections with SSH tunnels</title>
<note>
<title>Acknowledgement</title>
terminal session.
</para>
+ <tip>
+ <para>
+ Several other products exist that can provide secure tunnels using
+ a procedure similar in concept to the one just described.
+ </para>
+ </tip>
+
</sect1>
</Chapter>
projects / postgresql / commitdiff