From c1c88bf03e1eb85d5ca04bc7cfe2630154ec70d3 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Mon, 28 Dec 2020 17:44:17 -0500 Subject: Fix assorted issues in backend's GSSAPI encryption support. Unrecoverable errors detected by GSSAPI encryption can't just be reported with elog(ERROR) or elog(FATAL), because attempting to send the error report to the client is likely to lead to infinite recursion or loss of protocol sync. Instead make this code do what the SSL encryption code has long done, which is to just report any such failure to the server log (with elevel COMMERROR), then pretend we've lost the connection by returning errno = ECONNRESET. Along the way, fix confusion about whether message translation is done by pg_GSS_error() or its callers (the latter should do it), and make the backend version of that function work more like the frontend version. Avoid allocating the port->gss struct until it's needed; we surely don't need to allocate it in the postmaster. Improve logging of "connection authorized" messages with GSS enabled. (As part of this, I back-patched the code changes from dc11f31a1.) Make BackendStatusShmemSize() account for the GSS-related space that will be allocated by CreateSharedBackendStatus(). This omission could possibly cause out-of-shared-memory problems with very high max_connections settings. Remove arbitrary, pointless restriction that only GSS authentication can be used on a GSS-encrypted connection. Improve documentation; notably, document the fact that libpq now prefers GSS encryption over SSL encryption if both are possible. Per report from Mikael Gustavsson. Back-patch to v12 where this code was introduced. Discussion: https://postgr.es/m/e5b0b6ed05764324a2f3fe7acfc766d5@smhi.se --- doc/src/sgml/client-auth.sgml | 123 ++++++++++++++++++++++-------------------- doc/src/sgml/libpq.sgml | 19 +++++++ doc/src/sgml/protocol.sgml | 42 +++++++++------ doc/src/sgml/runtime.sgml | 12 ++++- 4 files changed, 121 insertions(+), 75 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index a0d584fb34e..92f474e8e6b 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -196,14 +196,6 @@ hostnogssenc database userhostgssenc record is ignored except for logging a warning that it cannot match any connections. - - - Note that the only supported - authentication methods for use - with GSSAPI encryption - are gss, reject, - and trust. - @@ -1196,15 +1188,15 @@ omicron bryanh guest1 GSSAPI is an industry-standard protocol - for secure authentication defined in RFC 2743. - + for secure authentication defined in + RFC 2743. PostgreSQL - supports GSSAPI for use as either an encrypted, - authenticated layer, or for authentication only. + supports GSSAPI for authentication, + communications encryption, or both. GSSAPI provides automatic authentication (single sign-on) for systems that support it. The authentication itself is secure. If GSSAPI encryption - (see hostgssenc) or SSL encryption are + or SSL encryption is used, the data sent along the database connection will be encrypted; otherwise, it will not. @@ -1216,37 +1208,46 @@ omicron bryanh guest1 When GSSAPI uses - Kerberos, it uses a standard principal - in the format + Kerberos, it uses a standard service + principal (authentication identity) name in the format servicename/hostname@realm. - 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 krbsrvname connection parameter. (See - also .) The installation default can be - changed from the default postgres at build time using - ./configure --with-krb-srvnam=whatever. - 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 (POSTGRES). - - - hostname is the fully qualified host name of the - server machine. The service principal's realm is the preferred realm - of the server machine. - - - - Client principals can be mapped to different PostgreSQL - database user names with pg_ident.conf. For example, + The principal name used by a particular installation is not encoded in + the PostgreSQL server in any way; rather it + is specified in the keytab 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. + + + + When connecting, the client must know the principal name of the server + it intends to connect to. The servicename + part of the principal is ordinarily postgres, + but another value can be selected via libpq's + connection parameter. + The hostname part is the fully qualified + host name that libpq is told to connect to. + The realm name is the preferred realm specified in the Kerberos + configuration file(s) accessible to the client. + + + + The client will also have a principal name for its own identity + (and it must have a valid ticket for this principal). To + use GSSAPI for authentication, the client + principal must be associated with + a PostgreSQL database user name. + The pg_ident.conf configuration file can be used + to map principals to user names; for example, pgusername@realm could be mapped to just pgusername. Alternatively, you can use the full username@realm principal as the role name in PostgreSQL without any mapping. - PostgreSQL also supports a parameter to strip the realm from + PostgreSQL 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, @@ -1260,39 +1261,34 @@ omicron bryanh guest1 - Make sure that your server keytab file is readable (and preferably - only readable, not writable) by the PostgreSQL - server account. (See also .) The location - of the key file is specified by the configuration parameter. The default is - /usr/local/pgsql/etc/krb5.keytab (or whatever - directory was specified as sysconfdir at build time). + FILE:/usr/local/pgsql/etc/krb5.keytab + (where the directory part is whatever was specified + as sysconfdir at build time). For security reasons, it is recommended to use a separate keytab just for the PostgreSQL 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 PostgreSQL + server account. (See also .) + - 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 kadmin tool of + MIT-compatible Kerberos 5 implementations: -kadmin% ank -randkey postgres/server.my.domain.org +kadmin% addprinc -randkey postgres/server.my.domain.org kadmin% ktadd -k krb5.keytab postgres/server.my.domain.org - 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 fred, principal - fred@EXAMPLE.COM would be able to connect. To also allow - principal fred/users.example.com@EXAMPLE.COM, use a user name - map, as described in . - - - - The following configuration options are supported for GSSAPI: + The following authentication options are supported for + the GSSAPI authentication method: include_realm @@ -1315,7 +1311,7 @@ omicron bryanh guest1 map - Allows for mapping between system and database user names. See + Allows mapping from client principals to database user names. See for details. For a GSSAPI/Kerberos principal, such as username@EXAMPLE.COM (or, less commonly, username/hostbased@EXAMPLE.COM), the @@ -1342,6 +1338,15 @@ omicron bryanh guest1 + + + In addition to these settings, which can be different for + different pg_hba.conf entries, there is the + server-wide configuration + parameter. If that is set to true, client principals are matched to + user map entries case-insensitively. krb_realm, if + set, is also matched case-insensitively. + diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index aa246e64479..e6b96b21f6c 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1577,6 +1577,16 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname connection.SSLwith libpq + + + Note that if GSSAPI encryption is possible, + that will be used in preference to SSL + encryption, regardless of the value of sslmode. + To force use of SSL encryption in an + environment that has working GSSAPI + infrastructure (such as a Kerberos server), also + set gssencmode to disable. + @@ -1778,6 +1788,15 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname This must match the service name specified in the server configuration for Kerberos authentication to succeed. (See also .) + The default value is normally postgres, + but that can be changed when + building PostgreSQL via + the option + of configure. + 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 (POSTGRES). diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 2a0197eeb36..6efcab37342 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1454,6 +1454,10 @@ SELCT 1/0; SSL-encrypted. To continue after N, send the usual StartupMessage and proceed without encryption. + (Alternatively, it is permissible to issue a GSSENCRequest message + after an N response to try to + use GSSAPI encryption instead + of SSL.) @@ -1508,20 +1512,14 @@ SELCT 1/0; result from the server, until it returns no output. When sending the results of gss_init_sec_context() to the server, prepend the length of the message as a four byte integer in network byte - order. If this is successful, then use gss_wrap() to - encrypt the usual StartupMessage and all subsequent data, prepending the - length of the result from gss_wrap() 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; gss_wrap_size_limit() 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 - gss_wrap() 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 N, send the usual StartupMessage and proceed without encryption. + (Alternatively, it is permissible to issue an SSLRequest message + after an N response to try to + use SSL encryption instead + of GSSAPI.) @@ -1531,9 +1529,7 @@ SELCT 1/0; support to PostgreSQL. In this case the connection must be closed, but the frontend might choose to open a fresh connection and proceed without requesting GSSAPI - 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. @@ -1541,6 +1537,22 @@ SELCT 1/0; opened to send a CancelRequest message. + + Once GSSAPI encryption has been successfully + established, use gss_wrap() to + encrypt the usual StartupMessage and all subsequent data, prepending the + length of the result from gss_wrap() 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; gss_wrap_size_limit() 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 + gss_wrap() 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. + + While the protocol itself does not provide a way for the server to force GSSAPI encryption, the administrator can diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index f9cc8503c07..3e7db2cf6d3 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -2549,7 +2549,7 @@ openssl x509 -req -in server.csr -text -days 365 \ PostgreSQL also has native support for using GSSAPI to encrypt client/server communications for increased security. Support requires that a GSSAPI - implementation (such as MIT krb5) is installed on both client and server + implementation (such as MIT Kerberos) is installed on both client and server systems, and that support in PostgreSQL is enabled at build time (see ). @@ -2568,6 +2568,16 @@ openssl x509 -req -in server.csr -text -days 365 \ some or all connections. + + When using GSSAPI for encryption, it is common to + use GSSAPI for authentication as well, since the + underlying mechanism will determine both client and server identities + (according to the GSSAPI implementation) in any + case. But this is not required; + another PostgreSQL authentication method + can be chosen to perform additional verification. + + Other than configuration of the negotiation behavior, GSSAPI encryption requires no setup beyond -- cgit v1.2.3