Documentation: improve TLS docs.

[stuclem]

From @stuclem on November 8, 2016 12:27

The TLS docs need more work.

Comment from @hickeng by email:

---

I suggest we separate (the TLS doc) in the following manner:

1. How to supply a server certificate for a VCH (this is a really common thing for many servers - should be the piece people are most familiar with).
2. How to configure client authentication (mutual authentication)
3. How to disable TLS
   --> what certificates are required for each of these (certificate authority, server certificate and key, client certificate and key), which role needs which certificates and how they're used in installation.
   --> explicitly not talking about how those certificates are obtained

Then a separate section on the fact that we generate trivial versions of these certificates as a convenience when possible (--tls-cname or --client-network-ip), and that if wanting more control over the certificates than we provide for that the certificates can be generated by standard means (e.g. openssl for linux) or obtained from a certificate provider (https://en.wikipedia.org/wiki/Certificate_authority#Providers)

---

See also:

• The changes to doc/user/usage.md in https://github.com/vmware/vic/pull/3049/files.
• @hickeng 's comments in [skip ci] Doc updates related to help reorg, option renaming, TLS  vic#2939 (review) , [skip ci] Doc updates related to help reorg, option renaming, TLS  vic#2939 (review) and [skip ci] Doc updates related to help reorg, option renaming, TLS  vic#2939 (review)

Copied from original issue: vmware/vic#3055

[stuclem]

There's a great writeup of TLS from @hickeng in vmware/vic#3087 (comment).

[stuclem]

Too late for GA. TLS is well-covered by @hickeng 's rewrites. Reinstate the security overview to the doc in a post-GA update.

[stuclem]

Definitely something that we should try to squeeze into 1.1.

[stuclem]

Comment from vmware/vic#3486, that needs checking.

Following a question from @mreferre:

We do currently state that --no-tlsverify only creates/uploads server certs, and that clients are unverified. However, the writeup of --no-tls states pretty much the same about the client side and doesn't say much about the absence of a server cert. We need to make it 100% clear that with --no-tls there is no server cert. In other words, with --no-tlsverify, any client can connect, but at least the connection between the client and server is a secure one. With --no-tls, any client can connect, and the connection itself is insecure.

---

[hickeng]

@stuclem @mreferre is correct in his characterization, and if it's not apparent in the current docs the we should make it so. The primary vulnerabilities by config are:

• no-tls - no access control & connections have no encryption so are open to snooping
• no-tlsverify - no access control & susceptible to man-in-the-middle when using docker client, but connections are encrypted.

[stuclem]

Thanks @hickeng. Bumping this up to a To Do.

[stuclem]

Added the detail about encrypted/unencrypted comms, and moved all of the security options into the Security section (i.e. moved the so-called advanced ones out of the Advanced Options section) in stuclem@7902648.

Moving back to backlog and 1.1 refresh as more work required after GA.

[stuclem]

This is a bigger job than we have time for in 1.1.1. Pushing out to 1.2, where it will be addressed as a part of #26.

[stuclem]

For convenience, here is @hickeng 's text from vmware/vic#3087 (comment):

---

Certificates in general

A certificate is made up of two parts and I try to refer to those two parts as a single entity, but do fall into plurals on occasion:

• public certificate portion (given out to anyone who asks)
• private key (kept secret)

The naming conventions are as follows for paired certificate and key files:
cert.pem & key.pem
<prefix>.pem & <prefix>-key.pem
<prefix>-cert.pem & <prefix>-key.pem

Docker and certificate usage

There are four certificates in play with a tlsverify configuration:

1. client certificate (held by the client)
2. server certificate (held by the server)
3. certificate authority (CA) used to sign the server certificate
4. certificate authority used to sign the client certificate (held by the server)

As a convenience, vic-machine generates one CA that is used for both (3) and (4), and uses that to sign both (1) and (2). This means that the clients must be given the public part of the CA in order to be able to trust the server, as well as the client certificate, for each VCH they use (unless sharing access across VCHs).

In a production deployment I would expect:
(3) to be signed by a company certificate, rooted by a public or corporate trust authority (e.g. verisign)
(4) to be unique per client or group of clients - this allows each client to have a unique certificate, but for the group to be authorized as a whole. This could be one per VCH, multiple per VCH, or one per group of VCHs.

DOCKER_CERT_PATH

Docker requires the following names to be used if certificates are to be automatically consumed from DOCKER_CERT_PATH on the client machine:
cert.pem key.pem - the client certifcate (1)
server-cert.pem server-key.pem - the server certificate (2)
ca.pem - the public portion of the certificate authority that signed the servers certificate (3)

vic-machine TLS options:

--no-tls: this is a horrible deployment choice for anything but a lab but was common prior to the addition of the tlsverify mechanism in 0.7.0 - hopefully Admiral will be updated soon to allow for the tlsverify configuration

--no-tlsverify: the certificate generated with this option is a server certificate and should exist on the VCH endpoint VM and should not be needed by Admiral - the fact it's not saved in 0.7.0 is entirely my fault (see PR at the bottom of this comment). This certificate allows the client to confirm the servers identity (as with banking websites, etc) so long as the client can validate the certificate chain - this may require the CA be provided to the client if using self-signed certificates. The server certificate files should now be named as expected by the docker client. This does not require the client to verify it's identity for the server.

--tls-cname: supplying this option also creates a certificate authority and client certificates signed by that authority so allow the server (endpointVM) to confirm the clients identity. The client certificate files should be the ones that Admiral requires.

• ca.pem (used on the server to confirm a client is authorized)
• cert.pem - (client certificate - should be in DOCKER_CERT_PATH on the client machine)
• key.pem - (the private key only the client needs - should be in DOCKER_CERT_PATH)

If generating authority (CA), client, and server certificates then the same CA is used for both client and server. In this case the ca.pem file needs to be:
a. placed in DOCKER_CERT_PATH or specified on the docker client command line
b. registered with a browser in order to access the vic-admin log server on port 2378

---

Some of this info is already in the docs, but we need to check that all of it is there.

[stuclem]

Merged in #1259. Reviewed by @zjs.