From b0b39f72b9904bcb80f97b35837ccff1578aa4b8 Mon Sep 17 00:00:00 2001 From: Stephen Frost Date: Wed, 3 Apr 2019 15:02:33 -0400 Subject: GSSAPI encryption support On both the frontend and backend, prepare for GSSAPI encryption support by moving common code for error handling into a separate file. Fix a TODO for handling multiple status messages in the process. Eliminate the OIDs, which have not been needed for some time. Add frontend and backend encryption support functions. Keep the context initiation for authentication-only separate on both the frontend and backend in order to avoid concerns about changing the requested flags to include encryption support. In postmaster, pull GSSAPI authorization checking into a shared function. Also share the initiator name between the encryption and non-encryption codepaths. For HBA, add "hostgssenc" and "hostnogssenc" entries that behave similarly to their SSL counterparts. "hostgssenc" requires either "gss", "trust", or "reject" for its authentication. Similarly, add a "gssencmode" parameter to libpq. Supported values are "disable", "require", and "prefer". Notably, negotiation will only be attempted if credentials can be acquired. Move credential acquisition into its own function to support this behavior. Add a simple pg_stat_gssapi view similar to pg_stat_ssl, for monitoring if GSSAPI authentication was used, what principal was used, and if encryption is being used on the connection. Finally, add documentation for everything new, and update existing documentation on connection security. Thanks to Michael Paquier for the Windows fixes. Author: Robbie Harwood, with changes to the read/write functions by me. Reviewed in various forms and at different times by: Michael Paquier, Andres Freund, David Steele. Discussion: https://www.postgresql.org/message-id/flat/jlg1tgq1ktm.fsf@thriss.redhat.com --- doc/src/sgml/client-auth.sgml | 78 ++++++++++++++++++++++++++++++++++--------- doc/src/sgml/libpq.sgml | 59 +++++++++++++++++++++++++++++++- doc/src/sgml/monitoring.sgml | 57 +++++++++++++++++++++++++++++++ doc/src/sgml/runtime.sgml | 77 +++++++++++++++++++++++++++++++++++++++--- 4 files changed, 249 insertions(+), 22 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index c7e4d3817f1..45a3cf3defd 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -108,6 +108,8 @@ hostnossl database user host database user IP-address IP-mask auth-method auth-options hostssl database user IP-address IP-mask auth-method auth-options hostnossl database user IP-address IP-mask auth-method auth-options +hostgssenc database user IP-address IP-mask auth-method auth-options +hostnogssenc database user IP-address IP-mask auth-method auth-options The meaning of the fields is as follows: @@ -128,9 +130,10 @@ hostnossl database user This record matches connection attempts made using TCP/IP. - host records match either + host records match SSL or non-SSL connection - attempts. + attempts as well as GSSAPI encrypted or + non-GSSAPI encrypted connection attempts. @@ -176,6 +179,42 @@ hostnossl database user + + hostgssenc + + + This record matches connection attempts made using TCP/IP, + but only when the connection is made with GSSAPI + encryption. + + + + To make use of this option the server must be built with + GSSAPI support. Otherwise, + the hostgssenc record is ignored except for logging + a warning that it cannot match any connections. + + + + Note that the only supported for use + with GSSAPI encryption + are gss, reject, + and trust. + + + + + + hostnogssenc + + + This record type has the opposite behavior of hostgssenc; + it only matches connection attempts made over + TCP/IP that do not use GSSAPI encryption. + + + + database @@ -450,8 +489,9 @@ hostnossl database user Use GSSAPI to authenticate the user. This is only - available for TCP/IP connections. See for details. + available for TCP/IP connections . See for details. It can be used in conjunction + with GSSAPI encryption. @@ -703,15 +743,18 @@ host postgres all 192.168.12.10/32 scram-sha-256 host all mike .example.com md5 host all all .example.com scram-sha-256 -# In the absence of preceding "host" lines, these two lines will +# In the absence of preceding "host" lines, these three lines will # reject all connections from 192.168.54.1 (since that entry will be -# 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. +# matched first), but allow GSSAPI-encrypted 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. Unencrypted GSSAPI connections +# (which "fall through" to the third line since "hostgssenc" only matches +# encrypted GSSAPI connections) are allowed, but only from 192.168.12.10. # # TYPE DATABASE USER ADDRESS METHOD host all all 192.168.54.1/32 reject -host all all 0.0.0.0/0 gss +hostgssenc all all 0.0.0.0/0 gss +host all all 192.168.12.10/32 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 @@ -1058,13 +1101,16 @@ omicron bryanh guest1 GSSAPI is an industry-standard protocol for secure authentication defined in RFC 2743. - PostgreSQL supports - GSSAPI with Kerberos - authentication according to RFC 1964. GSSAPI - 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 be sent unencrypted unless - SSL is used. + + PostgreSQL + supports GSSAPI for use as either an encrypted, + authenticated layer, or for authentication only. + 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 + used, the data sent along the database connection will be encrypted; + otherwise, it will not. diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index c1d1b6b2db3..0863a02411d 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1316,6 +1316,63 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname + + gssencmode + + + This option determines whether or with what priority a secure + GSS TCP/IP connection will be negotiated with the + server. There are three modes: + + + + disable + + + only try a non-GSSAPI-encrypted connection + + + + + + prefer (default) + + + if there are GSSAPI credentials present (i.e., + in a credentials cache), first try + a GSSAPI-encrypted connection; if that fails or + there are no credentials, try a + non-GSSAPI-encrypted connection. This is the + default when PostgreSQL has been + compiled with GSSAPI support. + + + + + + require + + + only try a GSSAPI-encrypted connection + + + + + + + + gssencmode is ignored for Unix domain socket + communication. If PostgreSQL is compiled + without GSSAPI support, using the require option + will cause an error, while prefer will be accepted + but libpq will not actually attempt + a GSSAPI-encrypted + connection.GSSAPIwith + libpq + + + + sslmode @@ -7948,7 +8005,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) - For a connection to be known secure, SSL usage must be configured + For a connection to be known SSL-secured, SSL usage must be configured on both the client and the server before the connection is made. If it is only configured on the server, the client may end up sending sensitive information (e.g. passwords) before diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index 66792605082..b946e13fdc3 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -336,6 +336,14 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser + + pg_stat_gssapipg_stat_gssapi + One row per connection (regular and replication), showing information about + GSSAPI authentication and encryption used on this connection. + See for details. + + + pg_stat_progress_create_indexpg_stat_progress_create_index One row for each backend running CREATE INDEX, showing @@ -2281,6 +2289,55 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i connection. + + <structname>pg_stat_gssapi</structname> View + + + + Column + Type + Description + + + + + + pid + integer + Process ID of a backend + + + gss_authenticated + boolean + True if GSSAPI authentication was used for this connection + + + principal + text + Principal used to authenticate this connection, or NULL + if GSSAPI was not used to authenticate this connection. This + field is truncated if the principal is longer than + NAMEDATALEN (64 characters in a standard build). + + + + encrypted + boolean + True if GSSAPI encryption is in use on this connection + + + +
+ + + The pg_stat_gssapi view will contain one row per + backend, showing information about GSSAPI usage on this connection. It can + be joined to pg_stat_activity or + pg_stat_replication on the + pid column to get more details about the + connection. + + <structname>pg_stat_archiver</structname> View diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index d786ebfb71d..fde9dbc1346 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -2037,9 +2037,13 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 - To prevent spoofing on TCP connections, the best solution is to use - SSL certificates and make sure that clients check the server's certificate. - To do that, the server + To prevent spoofing on TCP connections, either use + SSL certificates and make sure that clients check the server's certificate, + or use GSSAPI encryption (or both, if they're on separate connections). + + + + To prevent spoofing with SSL, the server must be configured to accept only hostssl connections () and have SSL key and certificate files (). The TCP client must connect using @@ -2047,6 +2051,14 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 verify-full and have the appropriate root certificate file installed (). + + + To prevent spoofing with GSSAPI, the server must be configured to accept + only hostgssenc connections + () and use gss + authentication with them. The TCP client must connect + using gssencmode=require. + @@ -2143,8 +2155,24 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 which hosts can use non-encrypted connections (host) and which require SSL-encrypted connections (hostssl). Also, clients can specify that they - connect to servers only via SSL. Stunnel or - SSH can also be used to encrypt transmissions. + connect to servers only via SSL. + + + + GSSAPI-encrypted connections encrypt all data sent across the network, + including queries and data returned. (No password is sent across the + network.) The pg_hba.conf file allows + administrators to specify which hosts can use non-encrypted connections + (host) and which require GSSAPI-encrypted connections + (hostgssenc). Also, clients can specify that they + connect to servers only on GSSAPI-encrypted connections + (gssencmode=require). + + + + Stunnel or + SSH can also be used to encrypt + transmissions. @@ -2561,6 +2589,45 @@ openssl x509 -req -in server.csr -text -days 365 \ + + Secure TCP/IP Connections with GSSAPI encryption + + + gssapi + + + + 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 + systems, and that support in PostgreSQL is + enabled at build time (see ). + + + + Basic Setup + + + The PostgreSQL server will listen for both + normal and GSSAPI-encrypted connections on the same TCP + port, and will negotiate with any connecting client on whether to + use GSSAPI for encryption (and for authentication). By + default, this decision is up to the client (which means it can be + downgraded by an attacker); see about + setting up the server to require the use of GSSAPI for + some or all conections. + + + + Other than configuration of the negotiation + behavior, GSSAPI encryption requires no setup beyond + that which is necessary for GSSAPI authentication. (For more information + on configuring that, see .) + + + + Secure TCP/IP Connections with <application>SSH</application> Tunnels -- cgit v1.2.3