Rework SSL/TLS documentation.

vertx-core/src/main/asciidoc/client_ssl.adoc

@@ -0,0 +1,115 @@
+=== Client SSL/TLS configuration
+
+==== Client trust configuration
+
+Like server configuration, the client trust can be configured in several ways:
+
+The first method is by specifying the location of a Java trust-store which contains the certificate authority.
+
+It is just a standard Java key store, the same as the key stores on the server side. The client
+trust store location is set by using the function {@link io.vertx.core.net.JksOptions#setPath path} on the
+{@link io.vertx.core.net.JksOptions jks options}. If a server presents a certificate during connection which is not
+in the client trust store, the connection attempt will not succeed.
+
+[source,$lang]
+----
+{@link examples.SslExamples#example30}
+----
+
+Buffer configuration is also supported:
+
+[source,$lang]
+----
+{@link examples.SslExamples#example31}
+----
+
+Certificate authority in PKCS#12 format (http://en.wikipedia.org/wiki/PKCS_12), usually with the `.pfx`  or the `.p12`
+extension can also be loaded in a similar fashion than JKS trust stores:
+
+[source,$lang]
+----
+{@link examples.SslExamples#example32}
+----
+
+Buffer configuration is also supported:
+
+[source,$lang]
+----
+{@link examples.SslExamples#example33}
+----
+
+Another way of providing server certificate authority using a list `.pem` files.
+
+[source,$lang]
+----
+{@link examples.SslExamples#example34}
+----
+
+Buffer configuration is also supported:
+
+[source,$lang]
+----
+{@link examples.SslExamples#example35}
+----
+
+If the {@link io.vertx.core.net.ClientSSLOptions#setTrustAll trustALl} is set to true on the client, then the client will
+trust all server certificates. The connection will still be encrypted but this mode is vulnerable to 'man in the middle' attacks. I.e. you can't
+be sure who you are connecting to. Use this with caution. Default value is false.
+
+[source,$lang]
+----
+{@link examples.SslExamples#example29}
+----
+
+==== Specifying key/certificate for the client
+
+If the server requires client authentication then the client must present its own certificate to the server when
+connecting. The client can be configured in several ways:
+
+The first method is by specifying the location of a Java key-store which contains the key and certificate.
+Again it's just a regular Java key store. The client keystore location is set by using the function
+{@link io.vertx.core.net.JksOptions#setPath(java.lang.String) path} on the
+{@link io.vertx.core.net.JksOptions jks options}.
+
+[source,$lang]
+----
+{@link examples.SslExamples#example36}
+----
+
+Buffer configuration is also supported:
+
+[source,$lang]
+----
+{@link examples.SslExamples#example37}
+----
+
+Key/certificate in PKCS#12 format (http://en.wikipedia.org/wiki/PKCS_12), usually with the `.pfx`  or the `.p12`
+extension can also be loaded in a similar fashion than JKS key stores:
+
+[source,$lang]
+----
+{@link examples.SslExamples#example38}
+----
+
+Buffer configuration is also supported:
+
+[source,$lang]
+----
+{@link examples.SslExamples#example39}
+----
+
+Another way of providing server private key and certificate separately using `.pem` files.
+
+[source,$lang]
+----
+{@link examples.SslExamples#example40}
+----
+
+Buffer configuration is also supported:
+
+[source,$lang]
+----
+{@link examples.SslExamples#example41}
+----
+
+Keep in mind that pem configuration, the private key is not crypted.

vertx-core/src/main/asciidoc/index.adoc

@@ -909,6 +909,16 @@ SEVERE: java.io.IOException: Connection reset by peer
 It means that the client is resetting the HTTP connection instead of closing it. This message also indicates that you
 may have not consumed the complete payload (the connection was cut before you were able to).
 
+== Configuring SSL
+
+[[server_ssl]]
+include::server_ssl.adoc[]
+
+[[client_ssl]]
+include::client_ssl.adoc[]
+
+include::ssl.adoc[]
+
 == Host name resolution
 
 Vert.x uses an an address resolver for resolving host name into IP addresses instead of