diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/client-auth.sgml | 253 | ||||
| -rw-r--r-- | doc/src/sgml/config.sgml | 6 | ||||
| -rw-r--r-- | doc/src/sgml/install-windows.sgml | 2 | ||||
| -rw-r--r-- | doc/src/sgml/installation.sgml | 20 | ||||
| -rw-r--r-- | doc/src/sgml/libpq.sgml | 9 | ||||
| -rw-r--r-- | doc/src/sgml/passwordcheck.sgml | 2 | ||||
| -rw-r--r-- | doc/src/sgml/protocol.sgml | 3 |
7 files changed, 77 insertions, 218 deletions
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index 9fc583ce574..14870401fb8 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -451,17 +451,6 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> </varlistentry> <varlistentry> - <term><literal>krb5</></term> - <listitem> - <para> - Use Kerberos V5 to authenticate the user. This is only - available for TCP/IP connections. See <xref - linkend="kerberos-auth"> for details. - </para> - </listitem> - </varlistentry> - - <varlistentry> <term><literal>ident</></term> <listitem> <para> @@ -650,13 +639,13 @@ host all all .example.com md5 # In the absence of preceding "host" lines, these two lines will # reject all connections from 192.168.54.1 (since that entry will be -# matched first), but allow Kerberos 5 connections from anywhere else +# matched first), but allow GSSAPI connections from anywhere else # on the Internet. The zero mask causes no bits of the host IP # address to be considered, so it matches any host. # # TYPE DATABASE USER ADDRESS METHOD host all all 192.168.54.1/32 reject -host all all 0.0.0.0/0 krb5 +host all all 0.0.0.0/0 gss # Allow users from 192.168.x.x hosts to connect to any database, if # they pass the ident check. If, for example, ident says the user is @@ -925,16 +914,74 @@ omicron bryanh guest1 </para> <para> + GSSAPI support has to be enabled when <productname>PostgreSQL</> is built; + see <xref linkend="installation"> for more information. + </para> + + <para> When <productname>GSSAPI</productname> uses <productname>Kerberos</productname>, it uses a standard principal 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">. + <literal><replaceable>servicename</>/<replaceable>hostname</>@<replaceable>realm</></literal>. + <replaceable>servicename</> can be set on the server side using the + <xref linkend="guc-krb-srvname"> configuration parameter, and on the + client side using the <literal>krbsrvname</> 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=</><replaceable>whatever</>. + In most environments, + this parameter never needs to be changed. However, it is necessary + when supporting multiple <productname>PostgreSQL</> installations + on the same host. + Some Kerberos implementations might also 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</> 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> - GSSAPI support has to be enabled when <productname>PostgreSQL</> is built; - see <xref linkend="installation"> for more information. + Client principals must have their <productname>PostgreSQL</> database user + name as their first component, for example + <literal>pgusername@realm</>. Alternatively, you can use a user name + mapping to map from the first component of the principal name to the + database user name. By default, the realm of the client is + not checked by <productname>PostgreSQL</>. If you have cross-realm + authentication enabled and need to verify the realm, use the + <literal>krb_realm</> parameter, or enable <literal>include_realm</> + and use user name mapping to check the realm. + </para> + + <para> + Make sure that your server keytab file is readable (and preferably + only readable) by the <productname>PostgreSQL</productname> server + account. (See also <xref linkend="postgres-user">.) The location + of the key file is specified by the <xref + linkend="guc-krb-server-keyfile"> configuration + parameter. The default is + <filename>/usr/local/pgsql/etc/krb5.keytab</> (or whatever + directory was specified as <varname>sysconfdir</> at build time). + </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: +<screen> +<prompt>kadmin% </><userinput>ank -randkey postgres/server.my.domain.org</> +<prompt>kadmin% </><userinput>ktadd -k krb5.keytab postgres/server.my.domain.org</> +</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</>, principal + <literal>fred@EXAMPLE.COM</> would be able to connect. To also allow + principal <literal>fred/users.example.com@EXAMPLE.COM</>, use a user name + map, as described in <xref linkend="auth-username-maps">. </para> <para> @@ -1050,178 +1097,6 @@ omicron bryanh guest1 </para> </sect2> - <sect2 id="kerberos-auth"> - <title>Kerberos Authentication</title> - - <indexterm zone="kerberos-auth"> - <primary>Kerberos</primary> - </indexterm> - - <note> - <para> - 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 method (see <xref linkend="gssapi-auth">) instead. - </para> - </note> - - <para> - <productname>Kerberos</productname> is an industry-standard secure - authentication system suitable for distributed computing over a public - network. A description of the <productname>Kerberos</productname> system - is beyond the scope of this document; in full generality it can be - quite complex (yet powerful). The - <ulink url="http://www.cmf.nrl.navy.mil/CCS/people/kenh/kerberos-faq.html"> - Kerberos <acronym>FAQ</></ulink> or - <ulink url="http://web.mit.edu/kerberos/www/">MIT Kerberos page</ulink> - can be good starting points for exploration. - Several sources for <productname>Kerberos</> distributions exist. - <productname>Kerberos</productname> provides secure authentication but - does not encrypt queries or data passed over the network; for that - use <acronym>SSL</acronym>. - </para> - - <para> - <productname>PostgreSQL</> supports Kerberos version 5. Kerberos - support has to be enabled when <productname>PostgreSQL</> is built; - see <xref linkend="installation"> for more information. - </para> - - <para> - <productname>PostgreSQL</> operates like a normal Kerberos service. - The name of the service principal is - <literal><replaceable>servicename</>/<replaceable>hostname</>@<replaceable>realm</></literal>. - </para> - - <para> - <replaceable>servicename</> can be set on the server side using the - <xref linkend="guc-krb-srvname"> configuration parameter, and on the - client side using the <literal>krbsrvname</> 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=</><replaceable>whatever</>. - In most environments, - this parameter never needs to be changed. However, it is necessary - when supporting multiple <productname>PostgreSQL</> installations - on the same host. - Some Kerberos implementations might also 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</> 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 must have their <productname>PostgreSQL</> database user - name as their first component, for example - <literal>pgusername@realm</>. Alternatively, you can use a user name - mapping to map from the first component of the principal name to the - database user name. By default, the realm of the client is - not checked by <productname>PostgreSQL</>. If you have cross-realm - authentication enabled and need to verify the realm, use the - <literal>krb_realm</> parameter, or enable <literal>include_realm</> - and use user name mapping to check the realm. - </para> - - <para> - Make sure that your server keytab file is readable (and preferably - only readable) by the <productname>PostgreSQL</productname> server - account. (See also <xref linkend="postgres-user">.) The location - of the key file is specified by the <xref - linkend="guc-krb-server-keyfile"> configuration - parameter. The default is - <filename>/usr/local/pgsql/etc/krb5.keytab</> (or whatever - directory was specified as <varname>sysconfdir</> at build time). - </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: -<screen> -<prompt>kadmin% </><userinput>ank -randkey postgres/server.my.domain.org</> -<prompt>kadmin% </><userinput>ktadd -k krb5.keytab postgres/server.my.domain.org</> -</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</>, principal - <literal>fred@EXAMPLE.COM</> would be able to connect. To also allow - principal <literal>fred/users.example.com@EXAMPLE.COM</>, use a user name - map, as described in <xref linkend="auth-username-maps">. - </para> - - <para> - If you use <ulink url="http://modauthkerb.sf.net"> - <application>mod_auth_kerb</application></ulink> - and <application>mod_perl</application> on your - <productname>Apache</productname> web server, you can use - <literal>AuthType KerberosV5SaveCredentials</literal> with a - <application>mod_perl</application> script. This gives secure - database access over the web, with no additional passwords required. - </para> - - <para> - The following configuration options are supported for - <productname>Kerberos</productname>: - <variablelist> - <varlistentry> - <term><literal>map</literal></term> - <listitem> - <para> - Allows for mapping between system and database user names. See - <xref linkend="auth-username-maps"> for details. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>include_realm</literal></term> - <listitem> - <para> - If set to 1, the realm name from the authenticated user - principal is included in the system user name that's passed through - user name mapping (<xref linkend="auth-username-maps">). This is - useful for handling users from multiple realms. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>krb_realm</literal></term> - <listitem> - <para> - Sets the realm to match user principal names against. If this parameter - is set, only users of that realm will be accepted. If it is not set, - users of any realm can connect, subject to whatever user name mapping - is done. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>krb_server_hostname</literal></term> - <listitem> - <para> - Sets the host name part of the service principal. - This, combined with <varname>krb_srvname</>, is used to generate - the complete service principal, that is - <varname>krb_srvname</><literal>/</><varname>krb_server_hostname</><literal>@</>REALM. - If not set, the default is the server host name. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </sect2> - <sect2 id="auth-ident"> <title>Ident Authentication</title> diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 0f2f2bf925b..3c4bb9becaa 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -964,7 +964,7 @@ include 'filename' <listitem> <para> Sets the location of the Kerberos server key file. See - <xref linkend="kerberos-auth"> or <xref linkend="gssapi-auth"> + <xref linkend="gssapi-auth"> for details. This parameter can only be set in the <filename>postgresql.conf</> file or on the server command line. </para> @@ -978,7 +978,7 @@ include 'filename' </indexterm> <listitem> <para> - Sets the Kerberos service name. See <xref linkend="kerberos-auth"> + Sets the Kerberos service name. See <xref linkend="gssapi-auth"> for details. This parameter can only be set in the <filename>postgresql.conf</> file or on the server command line. </para> @@ -992,7 +992,7 @@ include 'filename' </indexterm> <listitem> <para> - Sets whether Kerberos and GSSAPI user names should be treated + Sets whether GSSAPI user names should be treated case-insensitively. The default is <literal>off</> (case sensitive). This parameter can only be set in the <filename>postgresql.conf</> file or on the server command line. diff --git a/doc/src/sgml/install-windows.sgml b/doc/src/sgml/install-windows.sgml index 4c9ce5b1455..f3b1a12b05f 100644 --- a/doc/src/sgml/install-windows.sgml +++ b/doc/src/sgml/install-windows.sgml @@ -269,7 +269,7 @@ $ENV{PATH}=$ENV{PATH} . ';c:\some\where\bison\bin'; <varlistentry> <term><productname>MIT Kerberos</productname></term> <listitem><para> - Required for Kerberos authentication support. MIT Kerberos can be + Required for GSSAPI authentication support. MIT Kerberos can be downloaded from <ulink url="http://web.mit.edu/Kerberos/dist/index.html"></>. </para></listitem> diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index fc6559d7084..a4cdf5f1042 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -772,27 +772,11 @@ su - postgres </varlistentry> <varlistentry> - <term><option>--with-krb5</option></term> - <listitem> - <para> - Build with support for Kerberos 5 authentication. On many - systems, the Kerberos 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 Kerberos installation is sufficient before proceeding. - </para> - </listitem> - </varlistentry> - - <varlistentry> <term><option>--with-krb-srvnam=<replaceable>NAME</></option></term> <listitem> <para> - The default name of the Kerberos service principal (also used - by GSSAPI). + The default name of the Kerberos service principal used + by GSSAPI. <literal>postgres</literal> is the default. There's usually no reason to change this unless you have a Windows environment, in which case it must be set to upper case diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 15bc42cd61c..3ab06a1a1b7 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -896,7 +896,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname 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, a host name is - required for Kerberos, GSSAPI, or SSPI authentication + required for GSSAPI or SSPI authentication methods, as well as for <literal>verify-full</> SSL certificate verification. The following rules are used: <itemizedlist> @@ -1331,11 +1331,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <term><literal>krbsrvname</literal></term> <listitem> <para> - Kerberos service name to use when authenticating with Kerberos 5 - or GSSAPI. + Kerberos service name to use when authenticating with GSSAPI. This must match the service name specified in the server configuration for Kerberos authentication to succeed. (See also - <xref linkend="kerberos-auth"> and <xref linkend="gssapi-auth">.) + <xref linkend="gssapi-auth">.) </para> </listitem> </varlistentry> @@ -6652,7 +6651,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) <application>libpq</application> applications will attempt authentication with servers for this realm and use separate ticket files to avoid conflicts with local ticket files. This - environment variable is only used if Kerberos authentication is + environment variable is only used if GSSAPI authentication is selected by the server. </para> </listitem> diff --git a/doc/src/sgml/passwordcheck.sgml b/doc/src/sgml/passwordcheck.sgml index 415749d5424..6e6e4ef4356 100644 --- a/doc/src/sgml/passwordcheck.sgml +++ b/doc/src/sgml/passwordcheck.sgml @@ -48,7 +48,7 @@ module, because in that case it can only try to guess the password. For this reason, <filename>passwordcheck</filename> is not recommended if your security requirements are high. - It is more secure to use an external authentication method such as Kerberos + It is more secure to use an external authentication method such as GSSAPI (see <xref linkend="client-authentication">) than to rely on passwords within the database. </para> diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 0b2e60eeb13..7d99976a49c 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -271,7 +271,8 @@ authentication dialog (not described here, part of the Kerberos specification) with the server. If this is successful, the server responds with an AuthenticationOk, - otherwise it responds with an ErrorResponse. + otherwise it responds with an ErrorResponse. This is no + longer supported. This is not supported any more. </para> </listitem> </varlistentry> |