From af2cf3be03f284aa12a07bce2b95d4a2768b290f Mon Sep 17 00:00:00 2001 From: Magnus Hagander Date: Fri, 24 Apr 2009 14:10:41 +0000 Subject: [PATCH] More clearly document what the different sslmode options mean, both the new and the old ones. Consistently talk about certificate verification, and not validation. --- doc/src/sgml/libpq.sgml | 187 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 183 insertions(+), 4 deletions(-) diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 61a3e5d5e0..9334cbede2 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,4 +1,4 @@ - + <application>libpq</application> - C Library @@ -254,7 +254,7 @@ This option determines whether or with what priority a SSL TCP/IP connection will be negotiated with the - server. There are four modes: + server. There are six modes: @@ -311,6 +311,11 @@
+ + See for a detailed description of how + these options work. + + sslmode is ignored for Unix domain socket communication. @@ -6133,11 +6138,11 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) Certificate verification - By default, PostgreSQL will not perform any validation of + 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, - SSL certificate validation must be used. + SSL certificate verification must be used. @@ -6204,6 +6209,180 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) + + + Protection provided in different modes + + + 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: + + + SSL attacks + + + + Type + Description + + + + + + Eavesdropping + If a third party can listen to 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. + + + + + Man in the middle (MITM) + If a third party can modify the data while passing between the + client and server, it can pretend to be the server and therefore see and + modify data even if it is encrypted. The third party can then + forward the connection information and data to the original server, + making it impossible to detect this attack. Common vectors to do this + include DNS poisoning and address hijacking, whereby the client is directed + to a different server than intended. There are also several other + attack methods that can accomplish this. SSL uses certificate + verification to prevent this, by authenticating the server to the client. + + + + + Impersonation + If a third party can pretend to be an authorized client, it can + simply access data it should not have access to. Typically this can + happen through insecure password management. SSL uses + client certificates to prevent this, by making sure that only holders + of valid certificates can access the server. + + + + +
+ + + 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 + 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 + 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 + 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 + 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 + and security. The following table illustrates the risks the different + sslmode values protect against, and what statement they make + about security and overhead: + + + + SSL mode descriptions + + + + sslmode + Eavesdropping protection + MITM protection + Statement + + + + + + disabled + No + No + I don't care about security, and I don't want to pay the overhead + of encryption. + + + + + allow + Maybe + No + I don't care about security, but I will pay the overhead of + encryption if the server insists on it. + + + + + prefer + Maybe + No + I don't care about encryption, but I wish to pay the overhead of + encryption if the server supports it. + + + + + require + Yes + No + I want my data to be encrypted, and I accept the overhead. I trust + that the network will make sure I always connect to the server I want. + + + + + verify-ca + Yes + Depends on CA-policy + I want my data encrypted, and I accept the overhead. I want to be + sure that I connect to a server that I trust. + + + + + verify-full + Yes + Yes + I want my data encrypted, and I accept the overhead. I want to be + sure that I connect to a server I trust, and that it's the one I + specify. + + + + + +
+ + + 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 + a local CA is used, or even a self-signed certificate, using + verify-ca often provides enough protection. + + + + 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 compatiblity, and not recommended in secure deployments. + + + + SSL File Usage -- 2.40.0