From 1e6b654edcdcf0db75d1c086fff4124ea8bb39b5 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Wed, 26 May 2010 23:49:19 +0000 Subject: [PATCH] Improve SSL-related documentation. Explain how to deal with certificate chains, do assorted wordsmithing. --- doc/src/sgml/client-auth.sgml | 51 +++++++------- doc/src/sgml/config.sgml | 26 ++++---- doc/src/sgml/libpq.sgml | 121 ++++++++++++++++++++++------------ doc/src/sgml/runtime.sgml | 80 ++++++++++++++-------- 4 files changed, 173 insertions(+), 105 deletions(-) diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index d2f30a47c4..1c145b578a 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -1,4 +1,4 @@ - + Client Authentication @@ -314,9 +314,9 @@ hostnossl database user Reject the connection unconditionally. This is useful for - filtering out certain hosts from a group, e.g. a - reject line blocks a specific host from connecting, - but a later line allows the remaining hosts in a specific + filtering out certain hosts from a group, for example a + reject line could block a specific host from connecting, + while a later line allows the remaining hosts in a specific network to connect. @@ -446,7 +446,7 @@ hostnossl database user After the auth-method field, there can be field(s) of the form name=value that specify options for the authentication method. Details about which - options are available for which authentication method appear below. + options are available for which authentication methods appear below. @@ -624,17 +624,15 @@ local db1,db2,@demodbs all md5 in a map should be thought of as meaning this operating system user is allowed to connect as this database user, rather than implying that they are equivalent. The connection will be allowed if - there is any map entry that matches the user name obtained from the - external authentication system to the database user name that the + there is any map entry that pairs the user name obtained from the + external authentication system with the database user name that the user has requested to connect as. If the system-username field starts with a slash (/), the remainder of the field is treated as a regular expression. (See for details of - PostgreSQL's regular expression syntax. - Regular expressions in username maps are always treated as being - advanced flavor.) The regular + PostgreSQL's regular expression syntax.) The regular expression can include a single capture, or parenthesized subexpression, which can then be referenced in the database-username field as \1 (backslash-one). This allows the mapping of @@ -768,7 +766,7 @@ omicron bryanh guest1 The password-based authentication methods are md5 and 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, namely MD5-hashed and clear-text respectively. @@ -811,7 +809,7 @@ omicron bryanh guest1 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 send unencrypted unless + data sent over the database connection will be sent unencrypted unless SSL is used. @@ -821,6 +819,9 @@ omicron bryanh guest1 in the format servicename/hostname@realm. For information about the parts of the principal, and how to set up the required keys, see . + + + GSSAPI support has to be enabled when PostgreSQL is built; see for more information. @@ -845,7 +846,7 @@ omicron bryanh guest1 Allows for mapping between system and database usernames. See - for details. For a Kerboros + for details. For a Kerberos principal username/hostbased@EXAMPLE.COM, the username used for mapping is username/hostbased if include_realm is disabled, and @@ -948,7 +949,7 @@ omicron bryanh guest1 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 GSSAPI - authentication (see ) instead. + authentication method (see ) instead. @@ -1040,7 +1041,7 @@ omicron bryanh guest1 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 - principle fred/users.example.com@EXAMPLE.COM, use a username + principal fred/users.example.com@EXAMPLE.COM, use a username map, as described in . @@ -1121,7 +1122,7 @@ omicron bryanh guest1 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. @@ -1195,7 +1196,10 @@ omicron bryanh guest1 class="osname">Linux, FreeBSD, NetBSD, OpenBSD, BSD/OS, and Solaris), ident authentication can also - be applied to local connections. In this case, no security risk is added by + be applied to local connections. + PostgreSQL uses SO_PEERCRED 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. @@ -1272,7 +1276,7 @@ omicron bryanh guest1 Port number on LDAP server to connect to. If no port is specified, - the default port in the LDAP library will be used. + the LDAP library's default port setting will be used. @@ -1309,7 +1313,7 @@ omicron bryanh guest1 ldapbasedn - DN to root the search for the user in, when doing search+bind + Root DN to begin the search for the user in, when doing search+bind authentication. @@ -1403,7 +1407,7 @@ ldapserver=ldap.example.net ldapprefix="cn=" ldapsuffix=", dc=example, dc=net" 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 this is a string of + and RADIUS servers. It is recommended that this be a string of at least 16 characters. This parameter is required. @@ -1434,7 +1438,7 @@ ldapserver=ldap.example.net ldapprefix="cn=" ldapsuffix=", dc=example, dc=net" The string used as 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 database user the user is attempting to authenticate as, which can be used for policy matching on the RADIUS server. If no identifier is specified, the default postgresql will be used. @@ -1458,7 +1462,8 @@ ldapserver=ldap.example.net ldapprefix="cn=" ldapsuffix=", dc=example, dc=net" 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 cn attribute of the certificate + to the client. The cn (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 cn to be different from the database username. @@ -1548,7 +1553,7 @@ FATAL: no pg_hba.conf entry for host "123.123.123.123", user "andym", database -FATAL: Password authentication failed for user "andym" +FATAL: password authentication failed for user "andym" Messages like this indicate that you contacted the server, and it is willing to talk to you, but not until you pass the authorization diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 6fe27541cf..faf858f04c 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -1,4 +1,4 @@ - + Server Configuration @@ -590,7 +590,7 @@ SET ENABLE_SEQSCAN TO OFF; - + ssl (boolean) @@ -614,20 +614,22 @@ SET ENABLE_SEQSCAN TO OFF; - Specifies how much data can flow over an 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 512MB. + Specifies how much data can flow over an 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 512MB. 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. diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 7dc2983a89..57357b18bb 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,4 +1,4 @@ - + <application>libpq</application> - C Library @@ -293,7 +293,7 @@ sslmode - This option determines whether or with what priority a + This option determines whether or with what priority a secure SSL TCP/IP connection will be negotiated with the server. There are six modes: @@ -337,7 +337,7 @@ verify-ca only try an SSL connection, and verify that - the server certificate is issued by a trusted CA. + the server certificate is issued by a trusted CA @@ -345,7 +345,7 @@ verify-full only try an SSL connection, verify that the server certificate is issued by a trusted CA and - that the server hostname matches that in the certificate. + that the server hostname matches that in the certificate @@ -361,7 +361,8 @@ sslmode is ignored for Unix domain socket communication. If PostgreSQL is compiled without SSL support, - using option require will cause an error, while + using options require, verify-ca, or + verify-full will cause an error, while options allow and prefer will be accepted but libpq will not actually attempt an SSL @@ -398,7 +399,9 @@ This parameter specifies the file name of the client SSL - certificate. + certificate, replacing the default + ~/.postgresql/postgresql.crt. + This parameter is ignored if an SSL connection is not made. @@ -407,13 +410,15 @@ sslkey - This parameter specifies the location for the secret key - used for the client certificate. It can either specify a filename - that will be used instead of the default - ~/.postgresql/postgresql.key, or can specify an external - engine (engines are OpenSSL loadable modules). The - external engine specification should consist of a colon-separated - engine name and an engine-specific key identifier. + This parameter specifies the location for the secret key used for + the client certificate. It can either specify a filename that will + be used instead of the default + ~/.postgresql/postgresql.key, or it can specify a key + obtained from an external engine (engines are + OpenSSL loadable modules). An external engine + specification should consist of a colon-separated engine name and + an engine-specific key identifier. This parameter is ignored if an + SSL connection is not made. @@ -422,7 +427,11 @@ sslrootcert - This parameter specifies the file name of the root SSL certificate. + This parameter specifies the name of a file containing SSL + certificate authority (CA) certificate(s). + If the file exists, the server's certificate will be verified + to be signed by one of these authorities. The default is + ~/.postgresql/root.crt. @@ -432,7 +441,10 @@ This parameter specifies the file name of the SSL certificate - revocation list (CRL). + revocation list (CRL). Certificates listed in this file, if it + exists, will be rejected while attempting to authenticate the + server's certificate. The default is + ~/.postgresql/root.crl. @@ -1482,8 +1494,9 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); You must define USE_SSL in order to get the - correct prototype for this function. Doing this will also - automatically include ssl.h from OpenSSL. + correct prototype for this function. Doing so will also + automatically include ssl.h from + OpenSSL. @@ -6398,23 +6411,24 @@ user=admin By default, PostgreSQL will not perform any verification of the server certificate. This means that it is possible to spoof the server identity (for example by modifying a DNS record or by taking over the server - IP address) without the client knowing. In order to prevent this, + IP address) without the client knowing. In order to prevent spoofing, SSL certificate verification must be used. - If the parameter sslmode is set to verify-ca - libpq will verify that the server is trustworthy by checking the certificate - chain up to a trusted CA. If sslmode is set to - verify-full, libpq will also verify that the server - hostname matches that of the certificate. The SSL connection will fail if - the server certificate cannot be verified. verify-full is - recommended in most security sensitive environments. + If the parameter sslmode is set to verify-ca, + libpq will verify that the server is trustworthy by checking the + certificate chain up to a trusted certificate authority + (CA). If sslmode is set to verify-full, + libpq will also verify that the server hostname matches its + certificate. The SSL connection will fail if the server certificate cannot + be verified. verify-full is recommended in most + security-sensitive environments. - In verify-full mode, the cn attribute of the - certificate is matched against the hostname. If the cn + In verify-full mode, the cn (Common Name) attribute + of the certificate is matched against the hostname. If the cn attribute starts with an asterisk (*), it will be treated as a wildcard, and will match all characters except a dot (.). This means the certificate will not match subdomains. @@ -6423,7 +6437,8 @@ user=admin - To allow verification, the certificate of a trusted CA must be + To allow server certificate verification, the certificate(s) of one or more + trusted CAs must be placed in the file ~/.postgresql/root.crt in the user's home directory. (On Microsoft Windows the file is named %APPDATA%\postgresql\root.crt.) @@ -6437,8 +6452,9 @@ user=admin - The location of the root certificate store and the CRL can be overridden - by the connection parameters sslrootcert and sslcrl + The location of the root certificate file and the CRL can be changed by + setting + the connection parameters sslrootcert and sslcrl or the environment variables PGSSLROOTCERT and PGSSLCRL. @@ -6465,6 +6481,24 @@ user=admin environment variables PGSSLCERT and PGSSLKEY. + + In some cases, the client certificate might be signed by an + intermediate certificate authority, rather than one that is + directly trusted by the server. To use such a certificate, append the + certificate of the signing authority to the postgresql.crt + file, then its parent authority's certificate, and so on up to a + root authority that is trusted by the server. The root + certificate should be included in every case where + postgresql.crt contains more than one certificate. + + + + Note that root.crt lists the top-level CAs that are + considered trusted for signing server certificates. In principle it need + not list the CA that signed the client's certificate, though in most cases + that CA would also be trusted for server certificates. + + @@ -6472,8 +6506,8 @@ user=admin The different values for the sslmode parameter provide different - levels of protection, in different environments. SSL itself provides - protection against three different types of attacks: + levels of protection. SSL can provide + protection against three types of attacks: SSL attacks @@ -6488,7 +6522,7 @@ user=admin Eavesdropping - If a third party can listen to the network traffic between the + If a third party can examine the network traffic between the client and the server, it can read both connection information (including the username and password) and the data that is passed. SSL uses encryption to prevent this. @@ -6523,27 +6557,28 @@ user=admin
- For a connection to be known secure, the two first of these have to be - set up on both the client and the server before the connection + For a connection to be known secure, 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 - it knows that the server requires high security. In libpq, this is controlled + it knows that the server requires high security. In libpq, secure + connections can be ensured by setting the sslmode parameter to verify-full or verify-ca, and providing the system with a root certificate to - verify against. This is analogous to using a https + verify against. This is analogous to using an https URL for encrypted web browsing. Once the server has been authenticated, the client can pass sensitive data. This means that up until this point, the client does not need to know if - certificates will be used for authentication, making it safe to specify this + certificates will be used for authentication, making it safe to specify that only in the server configuration. All SSL options carry overhead in the form of encryption and - key-exchange, and it is a tradeoff that has to be made between performance + key-exchange, so there is a tradeoff that has to be made between performance and security. The following table illustrates the risks the different sslmode values protect against, and what statement they make about security and overhead: @@ -6625,8 +6660,8 @@ user=admin The difference between verify-ca and verify-full depends on the policy of the root CA. If a public CA is used, verify-ca allows connections to a server - that somebody else may have registered with the CA - to succeed. In this case, verify-full should always be used. If + that somebody else may have registered with the CA. + In this case, verify-full should always be used. If a local CA is used, or even a self-signed certificate, using verify-ca often provides enough protection. @@ -6635,7 +6670,7 @@ user=admin The default value for sslmode is prefer. As is shown in the table, this makes no sense from a security point of view, and it only promises performance overhead if possible. It is only provided as the default - for backwards compatibility, and not recommended in secure deployments. + for backwards compatibility, and is not recommended in secure deployments. @@ -6671,7 +6706,7 @@ user=admin ~/.postgresql/root.crt trusted certificate authorities - checks server certificate is signed by a trusted certificate + checks that server certificate is signed by a trusted certificate authority diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index 2e83dda9cf..8590cfa35f 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -1,4 +1,4 @@ - + Server Setup and Operation @@ -731,7 +731,7 @@ psql: could not connect to server: No such file or directory files (nofiles) might be too low. - + BSD/OS @@ -1438,28 +1438,30 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid` - The simplest way to prevent invalid servers for local + The simplest way to prevent spoofing for local connections is to use a Unix domain socket directory () that has write permission only for a trusted local user. This prevents a malicious user from creating their own socket file in that directory. If you are concerned that some applications might still reference /tmp for the socket file and hence be vulnerable to spoofing, during operating system - startup create symbolic link /tmp/.s.PGSQL.5432 that points + startup create a symbolic link /tmp/.s.PGSQL.5432 that points to the relocated socket file. You also might need to modify your - /tmp cleanup script to preserve the symbolic link. + /tmp cleanup script to prevent removal of the symbolic link. - For TCP connections the server - must accept only hostssl connections (hostssl connections () and have SSL server.key (key) and server.crt (certificate) files (). The TCP client must connect using - sslmode='verify-ca' or - 'verify-full' and have the required certificate - files present (). + sslmode=verify-ca or + verify-full and have the appropriate root certificate + file installed (). @@ -1583,13 +1585,13 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`SSL Host Authentication - + It is possible for both the client and server to provide SSL certificates to each other. It takes some extra configuration on each side, but this provides stronger verification of identity than the mere use of passwords. It prevents a computer from pretending to be the server just long enough to read the password - send by the client. It also helps prevent "man in the middle" + sent by the client. It also helps prevent man in the middle attacks where a computer between the client and server pretends to be the server and reads and passes all data between the client and server. @@ -1602,7 +1604,8 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid` - If the system administrator cannot be trusted, it is necessary + If the system administrator for the server's machine cannot be trusted, + it is necessary for the client to encrypt the data; this way, unencrypted data never appears on the database server. Data is encrypted on the client before being sent to the server, and database results have @@ -1680,20 +1683,33 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`server.key must disallow any access to world or group; achieve this by the command - chmod 0600 server.key. + chmod 0600 server.key. If the private key is protected with a passphrase, the server will prompt for the passphrase and will not start until it has been entered. + + In some cases, the server certificate might be signed by an + intermediate certificate authority, rather than one that is + directly trusted by clients. To use such a certificate, append the + certificate of the signing authority to the server.crt file, + then its parent authority's certificate, and so on up to a root + authority that is trusted by the clients. The root certificate should + be included in every case where server.crt contains more than + one certificate. + + Using client certificates + To require the client to supply a trusted certificate, place - certificates of the certificate authorities (CA) + certificates of the certificate authorities (CAs) you trust in the file root.crt in the data directory, and set the clientcert parameter - to 1 on the appropriate line(s) in pg_hba.conf. + to 1 on the appropriate hostssl line(s) in + pg_hba.conf. A certificate will then be requested from the client during SSL connection startup. (See for a description of how to set up certificates on the client.) The server will @@ -1707,16 +1723,26 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid` - The clientcert option in pg_hba.conf - is available for all authentication methods, but only for rows - specified as hostssl. Unless specified, the default is - not to verify the client certificate. + The clientcert option in pg_hba.conf is + available for all authentication methods, but only for rows specified as + hostssl. When clientcert is not specified + or is set to 0, the server will still verify presented client + certificates against root.crt if that file exists + — but it will not insist that a client certificate be presented. - You can use the authentication method cert to use the - client certificate for authenticating users. See - for details. + Note that root.crt lists the top-level CAs that are + considered trusted for signing client certificates. In principle it need + not list the CA that signed the server's certificate, though in most cases + that CA would also be trusted for client certificates. + + + + If you are setting up client certificates, you may wish to use + the cert authentication method, so that the certificates + control user authentication as well as providing connection security. + See for details. @@ -1725,7 +1751,7 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid` The files server.key, server.crt, root.crt, and root.crl - are only examined during server start; so you must restart + are only examined during server start; so you must restart the server for changes in them to take effect. @@ -1745,13 +1771,13 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid` server.crt server certificate - requested by client + sent to client to indicate server's identity server.key server private key - proves server certificate was sent by the owner; it does not indicate + proves server certificate was sent by the owner; does not indicate certificate owner is trustworthy @@ -1812,7 +1838,7 @@ chmod og-rwx server.key A self-signed certificate can be used for testing, but a certificate signed by a certificate authority (CA) (either one of the global CAs or a local one) should be used in production - so the client can verify the server's identity. If all the clients + so that clients can verify the server's identity. If all the clients are local to the organization, using a local CA is recommended.