Merge pull request #796 from vladimirvivien/tls-support-583

Support for REX-Ray TLS configuration and documentation

.docs/user-guide/config.md

@@ -285,6 +285,187 @@ libStorage Storage Drivers page has information about the configuration details
 of [each driver](http://libstorage.readthedocs.io/en/stable/user-guide/storage-providers),
 including [VirtualBox](http://libstorage.readthedocs.io/en/stable/user-guide/storage-providers/#virtualbox).
 
+### TLS Configuration ###
+REX-Ray supports several ways of configuring TLS for secure connection between
+a REX-Ray client and a process running REX-Ray as a service.  This section 
+discusses how to configure REX-Ray using the followings:
+
+* YAML files
+* Environmental variables
+* `rexray` command arguments
+
+**Note:** TLS configuration assumes that you are using REX-Ray as a client and server. See
+the section on [Service Mode](./#service-mode) for detail on how to run REX-Ray this way.
+
+Before you get started, you will need at your disposal a keypair (certificate
+and private key) for the server and a separate keypair for the client both signed by 
+a CA.  You can use tools such as [OpenSSL](https://www.openssl.org) or Cloud 
+Flare's CFSSL [CFSSL](https://cfssl.org/) to generate self-signed certificates for your
+setup.
+
+### TLS Configuration ###
+REX-Ray supports several ways of configuring TLS for secure connection between
+a REX-Ray client and a process running REX-Ray as a service.  This section 
+discusses how to configure REX-Ray using the followings:
+
+* YAML files
+* Environmental variables
+* `rexray` command arguments
+
+**Note:** TLS configuration assumes that you are using REX-Ray as a client and server. See
+the section on [Service Mode](./#service-mode) for detail on how to run REX-Ray this way.
+
+Before you get started, you will need at your disposal a keypair (certificate
+and private key) for the server and a separate keypair for the client both signed by 
+a CA.  You can use tools such as [OpenSSL](https://www.openssl.org) or Cloud 
+Flare's CFSSL [CFSSL](https://cfssl.org/) to generate self-signed certificates for your
+setup.
+
+#### Secured transport with TLS
+This section shows how to setup both client and server for secured communication between
+them.  
+
+##### Server configuration
+First configure your REX-Ray server process with a configuration similar to the following.  Ensure to setup the `tls:` section to specify the certificate and the private key files for the server.
+```
+rexray:
+  modules:
+    default-docker:
+      disabled: true
+libstorage:
+  embedded: true
+  client:
+    type: controller
+  server:
+    endpoints:
+      public:
+        address: tcp://:7979
+    tls:
+      certFile: /etc/rexray/certs/server.pem
+      keyFile:  /etc/rexray/certs/server-key.pem
+    services:
+      virtualbox:
+        driver: virtualbox
+virtualbox:
+  volumePath: $HOME/VirtualBox/Volumes
+```
+
+##### Client configuration
+We also will use a small YAML configuration file for the client to avoid unnecessary typing.  The following instructs the REX-Ray client process to connect to the REX-Ray service process using TLS.
+
+```
+libstorage:
+  embedded: false
+  host:    tcp://localhost:7979
+  service: virtualbox
+  client:
+    tls: true
+```
+
+When the client connects to the server. It will fail as shown below:
+```
+# rexray volume -c ./rexray-config.yaml ls
+  Get http://localhost:7979/services: x509: certificate signed by unknown authority
+...
+```
+
+The error is telling us that the client attempted to validate the server certificate and
+it failed.  At this point we can tell REX-Ray client process to _ignore_ that verification step.  This 
+would make the setup no longer secure as shown below. 
+```
+libstorage:
+...
+  client:
+    tls: insecure
+```
+_This should only be done in a non-production environment for testing purposes._
+
+The proper way to setup the REX-Ray client for a secure connection is to provide the CA
+certificate, which contains signed certificate of known servers.  The client configuration below 
+uses `client.tls.trustedCertsFile` to specify the CA certificate.
+
+```
+libstorage:
+  embedded: false
+  host:    tcp://localhost:7979
+  service: virtualbox
+  client:
+    tls:
+      trustedCertsFile: /etc/rexray/certs/ca.pem
+```
+This setup ensures that only servers with signed certificates by the CA are allowed to interact
+with the client.
+
+#### Authenticate client using certificates
+A REX-Ray service can be configured to require a properly signed certificate from the client as well.  
+This approach can be used as a way of authenticating client connections coming to the server.
+This is done by updating the configuration for both the client and the server processes.
+
+#####  Server configuration
+Update the server configuration by adding `server.tls.trustedCertsFile` to specify the CA certificate
+and `server.tls.clientCertRequired` to force the server to validate the client certificate. 
+```
+libstorage:
+...
+  server:
+    endpoints:
+      public:
+        address: tcp://:7979
+    tls:
+      certFile: /etc/rexray/certs/server.pem
+      keyFile:  /etc/rexray/certs/server-key.pem
+      trustedCertsFile: /etc/rexray/certs/ca.pem
+      clientCertRequired: true
+...
+```
+##### Client configuration
+In this configuration, the client must also provide its own certificate to be allowed to communicate
+with the server with `client.tls.certFile` and `client.tls.keyFile`.
+```
+libstorage:
+  embedded: false
+  host:    tcp://localhost:7979
+  service: virtualbox
+  client:
+    tls:
+      certFile: /home/vladimir/certs3/client.pem
+      keyFile: /home/vladimir/certs3/client-key.pem
+      trustedCertsFile: /home/vladimir/certs3/ca.pem
+```
+#### TLS with Cert Fingerprints
+A REX-Ray client can be configured for TLS by providing the fingerprint of the server's certificate. This 
+approach is designed to keep configuration on the lighter side, but secure.  Rather than setup a full 
+separate keypair for the client, you can simply extract the fingerprint from the known self-signed server 
+certificate as a `SHA-256` hash:
+```
+openssl x509 -in /etc/rexray/certs/server.pem -fingerprint -sha256 -noout
+SHA256 Fingerprint=F5:F8:F5:0B:E8:22:5C:35:AF:...:10:48:57:8B:A8:1C:30:E3:47:D1:1C:F5:44:51:39
+```
+Next, configure the REX-Ray client to use the fingerprint value as follows:
+```
+libstorage:
+  embedded: false
+  host:    tcp://localhost:7979
+  service: virtualbox
+  client:
+    tls: "sha256:F5:F8:F5:0B:E8:22:5C:35:AF:0F:7A:1D:A0:7D:9B:9A:50:10:48:57:8B:A8:1C:30:E3:47:D1:1C:F5:44:51:39"
+```
+Notice the `sha256:` prefix when setting the client configuration attribute `client.tls`.
+
+Lastly, the server process must be configured with its keypair as follows:
+```
+libstorage:
+...
+ server:
+    endpoints:
+      public:
+        address: tcp://:7979
+    tls:
+      certFile: /home/vladimir/certs3/server.pem
+      keyFile:  /home/vladimir/certs3/server-key.pem
+...
+```
+
 ### Logging
 The `-l|--logLevel` option or `rexray.logLevel` configuration key can be set
 to any of the following values to increase or decrease the verbosity of the