docs: improve documentation on SSL

docs/documentation/head/connect.md

@@ -95,11 +95,14 @@ Connection conn = DriverManager.getConnection(url);
 
 * **sslmode** = String
 
- possible values include "disable", "require", "verify-ca" and "verify-full", "allow" and "prefer" 
- will throw an exception. "require" will default to a non validating SSL factory and not check the 
- validity of the certificates. "verify-ca" and "verify-full" use a validating SSL factory and will 
- check that the ca is correct and the host is correct. Setting these will necessitate storing the 
- server certificate on the client machine ["Configuring the client"](ssl-client.html).
+ possible values include `disable`, `allow`, `prefer`, `require`, `verify-ca` and `verify-full`
+ . `require`, `allow` and `prefer` all default to a non validating SSL factory and do not check the
+ validity of the certificate or the host name. `verify-ca` validates the certificate, but does not
+ verify the hostname. `verify-full` will validate that the certificate is correct and verify the
+ host connected to has the same hostname as the certificate.
+
+ Setting these will necessitate storing the server certificate on the client machine see
+ ["Configuring the client"](ssl-client.html) for details.
 
 * **sslcert** = String
 
@@ -117,7 +120,7 @@ Connection conn = DriverManager.getConnection(url);
 
 * **sslhostnameverifier** = String
 
- Class name of hostname verifier. Defaults to using `org.postgresql.ssl.jdbc4.LibPQFactory.verify()`
+ Class name of hostname verifier. Defaults to using `org.postgresql.ssl.PGjdbcHostnameVerifier`
 
 * **sslpasswordcallback** = String
 

docs/documentation/head/media/css/table.css

@@ -14,7 +14,7 @@ div.tblBasic table {
 
 div.tblBasic table th {
  padding-top: 20px;
- border-bottom: 1px solid #EFEFEF;
+ border-bottom: 1px solid #F0F8FF;
  vertical-align: bottom;
 }
 
@@ -99,3 +99,9 @@ div.tblBasic table td.colLastRT {
  text-align: right;
  vertical-align: top;
 }
+div.tblBasic table.tblBasicWhite th {
+ background-color: aliceblue;
+}
+div.tblBasic table.tblBasicWhite td {
+ background-color: white;
+}

docs/documentation/head/ssl-client.md

@@ -9,24 +9,79 @@ nexttitle: Custom SSLSocketFactory
 next: ssl-factory.html
 ---
 
-Unlike psql and other libpq based programs the JDBC driver does server certificate
-validation by default. This means that when establishing a SSL connection the
-JDBC driver will validate the server's identity preventing "man in the middle"
-attacks. It does this by checking that the server certificate is signed by a
-trusted authority. If you have a certificate signed by a global certificate
-authority (CA), there is nothing further to do because Java comes with copies of
-the most common CA's certificates. If you are dealing with a self-signed certificate
-though, you need to make this available to the Java client to enable it to validate
-the server's certificate.
-
-> ### Note
-
-> Only the JDBC driver version 3 and greater supports SSL. The 1.4 JDK was the 
-first version to come bundled with SSL support. Previous JDK versions that wanted 
-to use SSL could make use of the additional JSSE library, but it does not support 
-the full range of features utilized by the PostgreSQL™ JDBC driver.
-
-To make the server certificate available to Java, the first step is to convert
+There are a number of connection parameters for configuring the client for SSL. See [SSL Connection parameters](connect.html#ssl)
+
+The simplest being `ssl=true`, passing this into the driver will cause the driver to validate both
+the SSL certificate and verify the hostname (same as `verify-full`). **Note** this is different than
+libpq which defaults to a non-validating SSL connection.
+
+In this mode, when establishing a SSL connection the JDBC driver will validate the server's
+identity preventing "man in the middle" attacks. It does this by checking that the server
+certificate is signed by a trusted authority, and that the host you are connecting to is the
+same as the hostname in the certificate.
+
+If you **require** encryption and want the connection to fail if it can't be encrypted then set
+`sslmode=require` this ensures that the server is configured to accept SSL connections for this
+Host/IP address and that the server recognizes the client certificate. In other words if the server
+does not accept SSL connections or the client certificate is not recognized the connection will fail.
+**Note** in this mode we will accept all server certificates.
+
+If `sslmode=verify-ca`, the server is verified by checking the certificate chain up to the root
+certificate stored on the client.
+
+If `sslmode=verify-full`, the server host name will be verified to make sure it matches the name
+stored in the server certificate.
+
+The SSL connection will fail if the server certificate cannot be verified. `verify-full` is recommended
+in most security-sensitive environments.
+
+
+In the case where the certificate validation is failing you can try `sslcert=` and LibPQFactory will
+not send the client certificate. If the server is not configured to authenticate using the certificate
+it should connect.
+
+The location of the client certificate, client key and root certificate can be overridden with the
+`sslcert`, `sslkey`, and `sslrootcert` settings respectively. These default to /defaultdir/postgresql.crt,
+/defaultdir/postgresql.pk8, and /defaultdir/root.crt respectively where defaultdir is
+${user.home}/.postgresql/ in *nix systems and %appdata%/postgresql/ on windows
+
+Finer control of the SSL connection can be achieved using the `sslmode` connection parameter.
+This parameter is the same as the libpq `sslmode` parameter and the currently SSL implements the
+following
+
+<div class="tblBasic">
+<table class="tblBasicWhite" border="1" summary="SSL Mode Descriptions" cellspacing="0" cellpadding="0">
+<thead>
+<tr>
+ <th>sslmode</th><th>Eavesdropping Protection</th><th> MITM Protection</th><th/>
+</tr>
+</thead>
+<tr>
+ <td>disable</td><td>No</td><td>No</td><td>I don't care about security and don't want to pay the overhead for encryption</td>
+</tr>
+<tr>
+ <td>allow</td><td>Maybe</td><td>No</td><td>I don't care about security but will pay the overhead for encryption if the server insists on it</td>
+</tr>
+<tr>
+ <td>prefer</td><td>Maybe</td><td>No</td><td>I don't care about encryption but will pay the overhead of encryption if the server supports it</td>
+</tr>
+<tr>
+ <td>require</td><td>Yes</td><td>No</td><td>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.</td>
+</tr>
+<tr>
+ <td>verify-ca</td><td>Yes</td><td>Depends on CA policy</td><td>I want my data encrypted, and I accept the overhead. I want to be sure that I connect to a server that I trust.</td>
+</tr>
+<tr>
+ <td>verify-full</td><td>Yes</td><td>Yes</td><td>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.</td>
+</tr>
+</table>
+</div>
+
+
+### Note
+
+If you are using Java's default mechanism (not LibPQFactory) to create the SSL connection you will
+need to make the server certificate available to Java, the first step is to convert
 it to a form Java understands.
 
 `openssl x509 -in server.crt -out server.crt.der -outform der`
@@ -52,9 +107,6 @@ to use.
 In the event of problems extra debugging information is available by adding
 `-Djavax.net.debug=ssl` to your command line.
 
-To instruct the JDBC driver to try and establish a SSL connection you must add
-the connection URL parameter `ssl=true`. See [SSL Connection parameters](connect.html#ssl)
-
 <a name="nonvalidating"></a>
 ## Using SSL without Certificate Validation
 
@@ -65,6 +117,6 @@ certificate authority, but that is not always an option. The JDBC driver provid
 an option to establish a SSL connection without doing any validation, but please
 understand the risk involved before enabling this option.
 
-A non-validating connection is established via a custom `SSLSocketFactory` class
-that is provided with the driver. Setting the connection URL parameter `sslfactory=org.postgresql.ssl.NonValidatingFactory`
-will turn off all SSL validation.
+A non-validating connection is established via a custom `SSLSocketFactory` class that is provided
+with the driver. Setting the connection URL parameter `sslfactory=org.postgresql.ssl.NonValidatingFactory`
+will turn off all SSL validation.

docs/documentation/head/ssl-factory.md

@@ -12,18 +12,15 @@ next: query.html
 PostgreSQL™ provides a way for developers to customize how a SSL connection is
 established. This may be used to provide a custom certificate source or other
 extensions by allowing the developer to create their own `SSLContext` instance.
-The connection URL parameters `sslfactory` and `sslfactoryarg` allow the user
-to specify which custom class to use for creating the `SSLSocketFactory`. The
-class name specified by `sslfactory` must extend `javax.net.ssl.SSLSocketFactory`
-and be available to the driver's classloader. This class must have a zero argument
-constructor or a single argument constructor taking a String argument. This
-argument may optionally be supplied by `sslfactoryarg`.
+The connection URL parameters `sslfactory` allow the user to specify which custom
+class to use for creating the `SSLSocketFactory`. The class name specified by `sslfactory`
+must extend ` javax.net.ssl.SSLSocketFactory` and be available to the driver's classloader.
+
+This class must have a zero argument constructor or a single argument constructor preferentially taking
+a `Properties` argument. There is a simple `org.postgresql.ssl.DefaultJavaSSLFactory` provided which uses the
+default java SSLFactory.
 
 Information on how to actually implement such a class is beyond the scope of this
 documentation. Places to look for help are the [JSSE Reference Guide](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html)
 and the source to the `NonValidatingFactory` provided by the JDBC driver.
 
-The Java SSL API is not very well known to the JDBC driver developers and we
-would be interested in any interesting and generally useful extensions that you
-have implemented using this mechanism. Specifically it would be nice to be able
-to provide client certificates to be validated by the server.