More clearly document what the different sslmode options mean, both the new

and the old ones.

Consistently talk about certificate verification, and not validation.

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 61a3e5d5e0e7da052dd64069d0d3ec3cc763dc33..9334cbede21dd4e1b7a971de833fefdd9688ce2e 100644 (file)
--- 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