From c36adfba9d46787fa760256352105d7091af83fb Mon Sep 17 00:00:00 2001 From: Stuart Clements Date: Fri, 22 Dec 2017 10:46:30 +0100 Subject: [PATCH] More security updates --- docs/user_doc/SUMMARY.md | 4 +- docs/user_doc/vic_vsphere_admin/SUMMARY.md | 4 +- .../vic_vsphere_admin/public_network.md | 2 + .../vic_vsphere_admin/security_reference.md | 2 +- .../vic_vsphere_admin/tls_auto_certs.md | 196 +++++++++++++----- .../vic_vsphere_admin/tls_custom_certs.md | 6 +- .../vic_vsphere_admin/tls_unrestricted.md | 67 +++--- docs/user_doc/vic_vsphere_admin/vch_admin.md | 1 + .../vic_vsphere_admin/vch_registry.md | 2 +- .../vic_vsphere_admin/vch_security.md | 88 +++++++- 10 files changed, 286 insertions(+), 86 deletions(-) diff --git a/docs/user_doc/SUMMARY.md b/docs/user_doc/SUMMARY.md index ae59fd2fc6..446d265f1f 100644 --- a/docs/user_doc/SUMMARY.md +++ b/docs/user_doc/SUMMARY.md @@ -48,7 +48,7 @@ * [Security](vic_vsphere_admin/vch_security.md) * [Auto-Generated Certificates](vic_vsphere_admin/tls_auto_certs.md) * [Custom Certificates](vic_vsphere_admin/tls_custom_certs.md) - * [Unrestricted Access](vic_vsphere_admin/tls_unrestricted.md) + * [Disable Certificate Verification](vic_vsphere_admin/tls_unrestricted.md) * [Registry Access](vic_vsphere_admin/vch_registry.md) * [Operations User](vic_vsphere_admin/set_up_ops_user.md) * [Finish VCH Deployment](vic_vsphere_admin/complete_vch_deployment_client.md) @@ -65,10 +65,10 @@ * [Obtain General VCH Information and Connection Details](vic_vsphere_admin/inspect_vch.md) * [Obtain VCH Configuration Information](vic_vsphere_admin/inspect_vch_config.md) * [Configure Running VCHs](vic_vsphere_admin/configure_vch.md) - * [Delete VCHs](vic_vsphere_admin/remove_vch.md) * [Debug Running VCHs](vic_vsphere_admin/debug_vch.md) * [Enable Shell Access](vic_vsphere_admin/vch_shell_access.md) * [Authorize SSH Access](vic_vsphere_admin/vch_ssh_access.md) + * [Delete VCHs](vic_vsphere_admin/remove_vch.md) * [VCH Admin Portal](vic_vsphere_admin/access_vicadmin.md) * [Browser-Based Certificate Login](vic_vsphere_admin/browser_login.md) * [Command Line Certificate Login](vic_vsphere_admin/cmdline_login.md) diff --git a/docs/user_doc/vic_vsphere_admin/SUMMARY.md b/docs/user_doc/vic_vsphere_admin/SUMMARY.md index 1c2c1b5bbf..19a7d5ac3b 100644 --- a/docs/user_doc/vic_vsphere_admin/SUMMARY.md +++ b/docs/user_doc/vic_vsphere_admin/SUMMARY.md @@ -37,7 +37,7 @@ * [Security](vch_security.md) * [Auto-Generated Certificates](tls_auto_certs.md) * [Custom Certificates](tls_custom_certs.md) - * [Unrestricted Access](tls_unrestricted.md) + * [Disable Certificate Verification](tls_unrestricted.md) * [Registry Access](vch_registry.md) * [Operations User](set_up_ops_user.md) * [Finish VCH Deployment](complete_vch_deployment_client.md) @@ -54,10 +54,10 @@ * [Obtain General VCH Information and Connection Details](inspect_vch.md) * [Obtain VCH Configuration Information](inspect_vch_config.md) * [Configure Running VCHs](configure_vch.md) - * [Delete VCHs](remove_vch.md) * [Debug Running VCHs](debug_vch.md) * [Enable Shell Access](vch_shell_access.md) * [Authorize SSH Access](vch_ssh_access.md) + * [Delete VCHs](remove_vch.md) * [VCH Admin Portal](access_vicadmin.md) * [Browser-Based Certificate Login](browser_login.md) * [Command Line Certificate Login](cmdline_login.md) diff --git a/docs/user_doc/vic_vsphere_admin/public_network.md b/docs/user_doc/vic_vsphere_admin/public_network.md index 483f305d48..9fd30cabda 100644 --- a/docs/user_doc/vic_vsphere_admin/public_network.md +++ b/docs/user_doc/vic_vsphere_admin/public_network.md @@ -101,6 +101,8 @@ A DNS server for the VCH endpoint VM to use on the public, client, and managemen Enter a comma-separated list of DNS server addresses in the **DNS server** text box, for example `192.168.10.10,192.168.10.11`. +If you are using the Create Virtual Container Host wizard and you set a static IP address on the public network, you must configure a DNS server. + #### vic-machine Option `--dns-server`, None diff --git a/docs/user_doc/vic_vsphere_admin/security_reference.md b/docs/user_doc/vic_vsphere_admin/security_reference.md index 0dcedb817f..2b09fbe65d 100644 --- a/docs/user_doc/vic_vsphere_admin/security_reference.md +++ b/docs/user_doc/vic_vsphere_admin/security_reference.md @@ -19,7 +19,7 @@ When deploying VCHs, you must provide the certificate thumbprint of the vCenter ### Docker Client Authentication with VCHs -VCHs authenticate Docker API clients by using client certificates. For information about VCHs and client authentication, see [Virtual Container Host Security](vch_security.md). Be aware that it is possible to use the `--no-tlsverify` and `--no-tls` options to deploy VCHs that do not authenticate client connections. For information about the `--no-tlsverify` and `--no-tls` options, see [Unrestricted Access to the Docker API](tls_unrestricted.md). +VCHs authenticate Docker API clients by using client certificates. For information about VCHs and client authentication, see [Virtual Container Host Security](vch_security.md). Be aware that it is possible to use the `--no-tlsverify` and `--no-tls` options to deploy VCHs that do not authenticate client connections. For information about the `--no-tlsverify` and `--no-tls` options, see [Disable Certificate Authentication](tls_unrestricted.md). ## Network Security diff --git a/docs/user_doc/vic_vsphere_admin/tls_auto_certs.md b/docs/user_doc/vic_vsphere_admin/tls_auto_certs.md index 45b00e3aa7..8e326fb2ef 100644 --- a/docs/user_doc/vic_vsphere_admin/tls_auto_certs.md +++ b/docs/user_doc/vic_vsphere_admin/tls_auto_certs.md @@ -1,43 +1,51 @@ -# Restrict Access to the Docker API with Auto-Generated Certificates +# Use Automatically Generated Server Certificates -As a convenience, `vic-machine create` provides the option of automatically generating a client certificate, server certificate, and certificate authority (CA) as appropriate when you deploy a VCH. The generated certificates are functional, but they do not allow for fine control over aspects such as expiration, intermediate certificate authorities, and so on. To use more finely configured certificates, see [Restrict Access to the Docker API with Custom Certificates](tls_custom_certs.md). +As a convenience, vSphere Integrated Containers Engine provides the option of automatically generating a server certificate for the Docker API endpoint in the VCH. The generated certificates are functional, but they do not allow for fine control over aspects such as expiration, intermediate certificate authorities, and so on. To use more finely configured certificates, see [Use Custom Server Certificates](tls_custom_certs.md). -VCHs accept client certificates if they are signed by a CA that you provide by specifying one or more instances of the `--tls-ca` option. In the case of the certificates that `vic-machine create` generates, `vic-machine create` creates a CA and uses it to create and sign a single client certificate. +VCHs accept client certificates if they are signed by a CA that you optionally provide to the VCH. Alternatively, you can configure a VCH so that vSphere Integrated Containers Engine creates a Certificate Authority (CA) certificate that it uses to automatically generate and sign a single client certificate. -When using the Docker client, the client validates the server either by using CAs that are present in the root certificate bundle of the client system, or that are provided explicitly by using the `--tlscacert` option when running Docker commands. As a part of this validation, the server certificate must explicitly state at least one of the following, and must match the name or address that the client uses to access the server: +**NOTE**: The Create Virtual Container Host wizard in the vSphere Client does not support automatically generated CA or client certificates. To use automatically generated CA and client certificates, you must use the `vic-machine` CLI utility to create the VCH. -- The FQDN used to communicate with the server -- The IP address used to communicate with the server -- A wildcard domain that matches all of the FQDNs in a specific subdomain. For an example of a domain wildcard, see [https://en.wikipedia.org/wiki/Wildcard_certificate#Example](https://en.wikipedia.org/wiki/Wildcard_certificate#Example). +This topic describes how to use automatically generated server certificates in combination with automatically generated CA and client certificates, custom CA and client certificates, and with no client certificate validation. -This topic includes the following sections. +- [Options](#options) + - [Common Name (CN)](#tls-cname) + - [Organization (O)](#org) + - [Certificate key size](#keysize) + - [Certificate Path](#cert-path) +- [Automatically Generate Server, Client, and CA Certificates](#full-auto) +- [Automatically Generate Server Certificates and Use Custom CA and Client Certificates](#auto-server) +- [Automatically Generate Server Certificates and Disable Client Certificate Verification](#auto-notlsverify) -- [`vic-machine` Options](#options) -- [Example `vic-machine` Command](#example) +## Options -## `vic-machine` Options - -The `vic-machine create` options in this section allow you to deploy a VCH that uses auto-generated certificates to validate client connections. +The sections in this topic each correspond to an entry in the Security page of the Create Virtual Container Host wizard if you select **Docker API Access** > **Source of certificates**: **Auto-generate**. Each section also includes a description of the corresponding `vic-machine create` option. Certain options in this section are exposed in the `vic-machine create` help if you run `vic-machine create --extended-help`, or `vic-machine create -x`. -### `--tls-cname` +### Common Name (CN) + +The IP address, FQDN, or a domain wildcard for the client system or systems that connect to this VCH, to embed in an automatically generated server certificate. + +**NOTE**: Specifying an FQDN or wildcard assumes that there is a DHCP server offering IP addresses on the client network, and that those addresses have corresponding DNS entries such as `dhcp-a-b-c.example.com`. -**Short name**: None +#### Create VCH Wizard -The FQDN or IP address to embed in an auto-generated server certificate. Specify an FQDN, IP address, or a domain wildcard. If you provide a custom server certificate by using the `--tls-server-cert` option, you can use `--tls-cname` as a sanity check to ensure that the certificate is valid for the deployment. +Enter the IP address, FQDN, or a domain wildcard in the **Common Name (CN)** text box. -If you do not specify `--tls-cname` but you do set a static address for the VCH on the client network interface, `vic-machine create` uses that address for the Common Name, with the same results as if you had specified `--tls-cname=x.x.x.x`. For information about setting a static IP address on the client network, see [Configure the Client Network](client_network.md). +#### vic-machine Option -When you specify the `--tls-cname` option, `vic-machine create` performs the following actions during the deployment of the VCH: +`--tls-cname`, None -- Checks for an existing certificate in either a folder that has the same name as the VCH that you are deploying, or in a location that you specify in the [`--tls-cert-path`](#cert-path) option. If a valid certificate exists that includes the same Common Name attribute as the one that you specify in `--tls-cname`, `vic-machine create` reuses it. Reusing certificates allows you to delete and recreate VCHs for which you have already distributed the certificates to container developers. +Specify the IP address, FQDN, or a domain wildcard in the `--tls-cname` option. If you specify `--tls-cname`, `vic-machine create` performs the following actions during the deployment of the VCH: + +- Checks for an existing certificate in either a folder that has the same name as the VCH that you are deploying, or in a location that you can optionally specify in the [`--tls-cert-path`](#cert-path) option. If a valid certificate exists that includes the same Common Name attribute as the one that you specify in `--tls-cname`, `vic-machine create` reuses that certificate. Reusing certificates allows you to delete and recreate VCHs for which you have already distributed the client certificates to container developers. - If certificates are present in the certificate folder that include a different Common Name attribute to the one that you specify in `--tls-cname`, `vic-machine create` fails. - If a certificate folder does not exist, `vic-machine create` creates a folder with the same name as the VCH, or creates a folder in the location that you specify in the `--tls-cert-path` option. -- If valid certificates do not already exist, `vic-machine create` creates the following trusted CA, server, and client certificate/key pairs in the certificate folder: +- If valid certificates do not already exist, `vic-machine create` creates a CA certificate and a client certificate signed by that authority. The CA and client certificate allow the server to confirm the identity of the client. The `vic-machine create` command creates the following CA, server, and client certificate/key pairs in the certificate folder: - `ca.pem` - `ca-key.pem` - - `cert.pem` + - `cert.pem` - `key.pem` - `server-cert.pem` - `server-key.pem` @@ -52,61 +60,86 @@ Running `vic-machine create` with the `--tls-cname` option also creates an envir - The address of the VCH.
DOCKER_HOST=vch_address:2376
You must provide copies of the `cert.pem` and `key.pem` client certificate files and the environment file to container developers so that they can connect Docker clients to the VCH. If you deploy the VCH with the `--tls-cname` option, container developers must configure the client appropriately with one of the following options: + - By using the `tlsverify`, `tlscert`, and `tlskey` options in Docker commands, adding `tlscacert` if a custom CA was used to sign the server certificate. - By setting the `DOCKER_CERT_PATH=/path/to/client/cert.pem` and `DOCKER_TLS_VERIFY=1` Docker environment variables. For more information about how to connect Docker clients to VCHs, see [Configure the Docker Client for Use with vSphere Integrated Containers](../vic_app_dev/configure_docker_client.md). -**Usage**: +**NOTE**: If you do not specify `--tls-cname` but you do set a static address for the VCH on the client network interface, `vic-machine create` uses that address for the Common Name, with the same results as if you had specified `--tls-cname`. For information about setting a static IP address on the client network, see [Configure the Client Network](client_network.md). 
--tls-cname vch-name.example.org
--tls-cname *.example.org
-### `--tls-cert-path` +### Organization (O) -**Short name**: none +A list of identifiers to record in automatically generated server certificates, to add basic descriptive information to the certificate. This information is visible to clients if they inspect the server certificate. -By default `--tls-cert-path` is a folder in the current directory, that takes its name from the VCH name that you specify in the `--name` option. If specified, `vic-machine create` checks in `--tls-cert-path` for existing certificates with the standard names and uses those certificates if they are present: +**NOTE**: The `client-ip-address` is used for `CommonName` but not for `Organisation`. -* `server-cert.pem` -* `server-key.pem` -* `ca.pem` +#### Create VCH Wizard -If `vic-machine create` does not find existing certificates with the standard names in the folder you specify in `--tls-cert-path`, or if you do not specify certificates directly by using the `--tls-server-cert`, `--tls-server-key`, and `--tls-ca` options, `vic-machine create` generates certificates. Generated certificates are saved in the `--tls-cert-path` folder with the standard names listed. `vic-machine create` additionally generates other certificates: -* `cert.pem` and `key.pem` for client certificates, if required. -* `ca-key.pem`, the private key for the certificate authority. -**Usage**: +#### vic-machine Option -
--tls-cert-path 'path_to_certificate_folder'
-
+`--organization`, None + +If you specify `--tls-cname`, you can optionally specify `--organization`. If not specified,`vic-machine create` uses the name of the VCH as the `organization` value. + +
--organization my_organization_name
+ +### Certificate key size -### `--certificate-key-size` ### +The size of the key for vSphere Integrated Containers Engine to use when it creates auto-generated trusted certificates. It is not recommended to use key sizes of less than the default of 2048 bits. -**Short name**: `--ksz` +#### Create VCH Wizard -The size of the key for `vic-machine create` to use when it creates auto-generated trusted certificates. If you specify `--tls-cname`, you can optionally specify `--certificate-key-size`. If not specified, `vic-machine create` creates keys with default size of 2048 bits. It is not recommended to use key sizes of less than 2048 bits. -**Usage**: + +#### vic-machine Option + +`--certificate-key-size`, `--ksz` + +If you specify `--tls-cname`, you can optionally specify `--certificate-key-size`. If not specified, `vic-machine create` creates keys with default size of 2048 bits. 
--certificate-key-size 3072
-### `--organization` ### +### Certificate Path -**Short name**: None +If you are using the Create Virtual Container Host wizard, setting the certificate path is not applicable. -A list of identifiers to record in certificates generated by `vic-machine`. If you specify `--tls-cname`, you can optionally use `--organization` to add basic descriptive information to the server certificate. This information is visible to clients if they inspect the server certificate. If not specified,`vic-machine create` uses the name of the VCH as the `organization` value. +#### vic-machine Option -**NOTE**: The `client-ip-address` is used for `CommonName` but not for `Organisation`. +`--tls-cert-path`, none -**Usage**: +By default `--tls-cert-path` is a folder in the current directory, that takes its name from the VCH name that you specify in the `--name` option. If specified, `vic-machine create` checks in `--tls-cert-path` for existing certificates with the standard names and uses those certificates if they are present: -
--organization my_organization_name
+* `server-cert.pem` +* `server-key.pem` +* `ca.pem` + +If `vic-machine create` does not find existing certificates with the standard names in the folder you specify in `--tls-cert-path`, or if you do not specify certificates directly by using the `--tls-server-cert`, `--tls-server-key`, and `--tls-ca` options, `vic-machine create` generates certificates. Generated certificates are saved in the `--tls-cert-path` folder with the standard names listed. `vic-machine create` additionally generates other certificates: + +* `cert.pem` and `key.pem` for client certificates, if required. +* `ca-key.pem`, the private key for the certificate authority. + +
--tls-cert-path 'path_to_certificate_folder'
+
+ +## Automatically Generate Server, Client, and CA Certificates -## Example `vic-machine` Command +This example deploys a VCH with the following security configuration. -This example `vic-machine create` command deploys a VCH that implements client authentication with trusted auto-generated TLS certificates that are signed by a CA. +- Uses an automatically generated server certificate +- Implements client authentication with an automatically generated client certificate +- Uses an automatically generated CA to sign the client and server certificates + +### Create VCH Wizard + +You cannot use the Create Virtual Container Host wizard to deploy VCHs with automatically generated CA and client certificates. + +### `vic-machine` Command To automatically generate a server certificate that can pass client verification, you must specify the Common Name (CN) for the certificate by using the [`--tls-cname`](#tls-cname) option. The CN should be the FQDN or IP address of the server, or a domain with a wildcard. The CN value must match the name or address that clients will use to connect to the server. @@ -135,4 +168,73 @@ This example `vic-machine create` command deploys a VCH with the following confi The Docker API for this VCH will be accessible at https://dhcp-a-b-c.example.org:2376. -You can also deploy a VCH to use custom server certificates in combination with auto-generated client certificates, as demonstrated in the example [Combine Custom Server Certificates and Auto-Generated Client Certificates](tls_custom_certs.md#certcombo). \ No newline at end of file +## Automatically Generate Server Certificates and Use Custom CA and Client Certificates + +This section provides examples of using both the Create Virtual Container Host wizard and `vic-machine create` to deploy a VCH with the following security configuration: + +- Uses an automatically generated server certificate. +- Uploads the CA certificate for the custom CA that you use to sign the client certificates. +- Implements client authentication with a custom client certificate. + +### Prerequisites + +- Create or obtain the `ca.pem` file for the CA that you use to sign client certificates. +- Create client certificates. + +### Create VCH Wizard + +1. Leave the **Enable secure access to this VCH** switch in the green ON position. +2. For **Source of certificates**, select the **Auto-generate** radio button. +3. In the **Common Name (CN)** text box, enter the IP address, FQDN, or a domain wildcard for the client systems that connect to this VCH. +4. In the **Organization (O)** text box, leave the default setting of the VCH name, or enter a different organization identifier. +5. In the **Certificate key size** text box, leave the default setting of 2048 bits, or enter a higher value. +6. Leave the **Client Certificates** switch in the green ON position, to enable verification of client certificates. +7. Click **Select** and navigate to an existing `ca.pem` file for the custom CA that you use to sign client certificates. + +### `vic-machine` Command + +This example `vic-machine create` command deploys a VCH with the following configuration: + +- Provides a wildcard domain `*.example.org` as the FQDN for the client systems that connect to the VCH, for use as the Common Name in the certificate. +- Specifies a folder for the certificates in the `--tls-cert-path` option. +- Sets the certificate's `organization` (`O`) field to `My Organization`. +- Generates certificates with a key size of 3072 bits. +- Provides the path to an existing `ca.pem` file for the CA that you use to sign client certificates. + +
vic-machine-operating_system create
+--target 'Administrator@vsphere.local':password@vcenter_server_address/dc1
+--compute-resource cluster1
+--image-store datastore1
+--bridge-network vch1-bridge
+--tls-cname *.example.org
+--tls-cert-path path_to_cert_folder
+--organization 'My Organization'
+--certificate-key-size 3072
+--tls-cname path_to_folder/ca.pem
+--thumbprint certificate_thumbprint
+--name vch1
+
+ +### Result + +To be able to connect to this VCH, Docker clients must hold the `cert.pem` and `key.pem` files for client certificates that you create and sign with the specified CA. The Docker clients also require the `ca.pem` file of the specified CA. + +## Automatically Generate Server Certificates and Disable Client Certificate Verification + +This example deploys a VCH with the following security configuration. + +- Uses an automatically generated server certificate. +- Disables client certification authentication. + +### Create VCH Wizard + +1. Leave the **Enable secure access to this VCH** switch in the green ON position. +2. For **Source of certificates**, select the **Auto-generate** radio button. +3. In the **Common Name (CN)** text box, enter the IP address, FQDN, or a domain wildcard for the client systems that connect to this VCH. +4. In the **Organization (O)** text box, leave the default setting of the VCH name, or enter a different organization identifier. +5. In the **Certificate key size** text box, leave the default setting of 2048 bits, or enter a higher value. +3. Toggle the **Client Certificates** switch to the gray off position. + +### Example `vic-machine` Command + +Command here \ No newline at end of file diff --git a/docs/user_doc/vic_vsphere_admin/tls_custom_certs.md b/docs/user_doc/vic_vsphere_admin/tls_custom_certs.md index fba8c2c88a..1e75537d53 100644 --- a/docs/user_doc/vic_vsphere_admin/tls_custom_certs.md +++ b/docs/user_doc/vic_vsphere_admin/tls_custom_certs.md @@ -1,4 +1,4 @@ -# Restrict Access to the Docker API with Custom Certificates +# Use Custom Server Certificates To exercise fine control over the certificates that VCHs use, you must obtain or generate custom certificates yourself before you deploy a VCH. You can create a VCH that uses a custom server certificate, for example a server certificate that has been signed by Verisign or another public root. For information about how to create custom certificates for use with Docker, see [Protect the Docker daemon socket](https://docs.docker.com/engine/security/https/) in the Docker documentation. @@ -32,6 +32,8 @@ The path to a custom X.509 server certificate. This certificate identifies the V - Use this option in combination with the `--tls-server-key` option, that provides the path to the private key file for the custom certificate. - Include the names of the certificate and key files in the paths. +If you provide a custom server certificate by using the `--tls-server-cert` option, you can use `--tls-cname` as a sanity check to ensure that the certificate is valid for the deployment. + If you use custom certificates, container developers run Docker commands with the `--tlsverify`, `--tlscacert`, `--tlscert`, and `--tlskey` options. For more information about how to connect Docker clients to VCHs, see [Configure the Docker Client for Use with vSphere Integrated Containers](../vic_app_dev/configure_docker_client.md). **Usage**: @@ -86,6 +88,8 @@ This example `vic-machine create` command deploys a VCH with the following confi + + ### Combine Custom Server Certificates and Auto-Generated Client Certificates You can create a VCH with a custom server certificate by specifying the paths to custom `server-cert.pem` and `server-key.pem` files in the `--tls-server-cert` and `--tls-server-key` options. The key should be un-encrypted. Specifying the `--tls-server-cert` and `--tls-server-key` options for the server certificate does not affect the automatic generation of client certificates. If you specify the [`--tls-cname`](tls_auto_certs.md#tls-cname) option to match the common name value of the server certificate, `vic-machine create` generates self-signed certificates for Docker client authentication and deployment of the VCH succeeds. diff --git a/docs/user_doc/vic_vsphere_admin/tls_unrestricted.md b/docs/user_doc/vic_vsphere_admin/tls_unrestricted.md index 9651cc8267..7022d9a670 100644 --- a/docs/user_doc/vic_vsphere_admin/tls_unrestricted.md +++ b/docs/user_doc/vic_vsphere_admin/tls_unrestricted.md @@ -1,19 +1,41 @@ -# Unrestricted Access to the Docker API +# Disable Certificate Authentication -To deploy a VCH that does not restrict access to the Docker API but still encrypts communication between clients and the VCH, use the `--no-tlsverify` option. To completely disable TLS authentication and encryption, use the `--no-tls` option. +To deploy a virtual container host (VCH) that does not restrict access to the Docker API but still encrypts communication between clients and the VCH, you can disable client certificate verification. You can also completely disable TLS authentication and encryption on both the client and server sides. -- [`vic-machine` Options](#options) +- [Options](#options) + - [Disable Secure Access](#no-tls) + - [Disable Client Certificate Verification](#no-tlsverify) - [Example `vic-machine` Commands](#examples) -## `vic-machine` Options +## Options -The `--no-tls` option is exposed in the `vic-machine create` help if you run `vic-machine create --extended-help`, or `vic-machine create -x`. +The sections in this topic each correspond to an entry in the Docker API Access tab in the Security page of the Create Virtual Container Host wizard, and to the corresponding `vic-machine create` options. -### `--no-tlsverify` +### Disable Secure Access -**Short name**: `--kv` +You can completely disable TLS authentication of connections between Docker clients and the VCH. VCHs use neither client nor server certificates. Any Docker client can connect to the VCH if you disable TLS authentication and connections are not encrypted. -The `--no-tlsverify` option prevents the use of CAs for client authentication. You still require a server certificate if you use `--no-tlsverify`. You can supply a custom server certificate by using the [`--tls-server-cert`](tls_custom_certs.md#cert) and [`--tls-server-key`](tls_custom_certs.md#key) options. If you specify `--no-tlsverify` but do not use `--tls-server-cert` and `--tls-server-key` to supply a custom server certificate, `vic-machine create` generates a self-signed server certificate. If you specify `--no-tlsverify` there is no access control, however connections remain encrypted. +**IMPORTANT**: Disabling secure access is for testing purposes only. Do not disable secure access in production environments. + +If you use the `no-tls` option, container developers connect Docker clients to the VCH via the HTTP port, 2375, instead of via the HTTPS port, 2376. + +#### Create VCH Wizard + +Toggle the **Enable secure access to this VCH** switch to the gray off position. + +#### vic-machine Option + +`--no-tls`, `-k` + +Run `vic-machine create` with the `--no-tls` option. The `--no-tls` option is exposed in the `vic-machine create` help if you run `vic-machine create --extended-help`, or `vic-machine create -x`. + +The `--no-tls` option takes no arguments. + +
--no-tls
+ +### Disable Client Certificate Verification + +Disabling client certificate verification prevents the use of CAs for client authentication. You still require a server certificate if you use `--no-tlsverify`. You can supply a custom server certificate by using the [`--tls-server-cert`](tls_custom_certs.md#cert) and [`--tls-server-key`](tls_custom_certs.md#key) options. If you specify `--no-tlsverify` but do not use `--tls-server-cert` and `--tls-server-key` to supply a custom server certificate, `vic-machine create` generates a self-signed server certificate. If you specify `--no-tlsverify` there is no access control, however connections remain encrypted. When you specify the `--no-tlsverify` option, `vic-machine create` performs the following actions during the deployment of the VCH. @@ -23,27 +45,19 @@ When you specify the `--no-tlsverify` option, `vic-machine create` performs the If you deploy a VCH with the `--no-tlsverify` option, container developers run Docker commands with the `--tls` option, and the `DOCKER_TLS_VERIFY` environment variable must not be set. Note that setting `DOCKER_TLS_VERIFY` to 0 or `false` has no effect. For more information about how to connect Docker clients to VCHs, see [Configure the Docker Client for Use with vSphere Integrated Containers](../vic_app_dev/configure_docker_client.md). -**Usage**: - -The `--no-tlsverify` option takes no arguments. - -
--no-tlsverify
- -### `--no-tls` +#### Create VCH Wizard -**Short name**: `-k` +Toggle the **Client Certificates** switch to the gray off position. -Disables TLS authentication of connections between the Docker client and the VCH. VCHs use neither client nor server certificates. +#### vic-machine Option -Set the `no-tls` option if you do not require TLS authentication between the VCH and the Docker client, for example for testing purposes. Any Docker client can connect to the VCH if you disable TLS authentication and connections are not encrypted. +`--no-tlsverify`, `--kv` -If you use the `no-tls` option, container developers connect Docker clients to the VCH via the HTTP port, 2375, instead of via the HTTPS port, 2376. +--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. 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. -**Usage**: +Run `vic-machine create` with the `--no-tlsverify` option. The `--no-tlsverify` option takes no arguments. -The `--no-tls` option takes no arguments. - -
--no-tls
+
--no-tlsverify
## Example `vic-machine` Commands @@ -55,7 +69,7 @@ The `--no-tls` option takes no arguments. You use the `--no-tlsverify` option with no other TLS options to disable client authentication and auto-generate a server certificate. -This example `vic-machine create` command deploys a VCH with the following configuration: +This example deploys a VCH with the following configuration: - Specifies the user name, password, image store, cluster, bridge network, and name for the VCH. - Specifies `--no-tlsverify` to disable client authentication. @@ -74,7 +88,7 @@ This example `vic-machine create` command deploys a VCH with the following confi You use the `--tls-server-cert`, `--tls-server-key`, and `--no-tlsverify` options to use a custom X.509 server certificate and key and disable client authentication. -This example `vic-machine create` command deploys a VCH with the following configuration: +This example deploys a VCH with the following configuration: - Specifies the user name, password, image store, cluster, bridge network, and name for the VCH. - Provides the paths relative to the current location of the `*.pem` files for the custom server certificate and key files. @@ -96,7 +110,7 @@ This example `vic-machine create` command deploys a VCH with the following confi You use the `--no-tls` option with no other TLS options to disable client and server authentication. -This example `vic-machine create` command deploys a VCH with the following configuration: +This example deploys a VCH with the following configuration: - Specifies the user name, password, image store, cluster, bridge network, and name for the VCH. - Specifies `--no-tls` to disable client and server authentication. @@ -110,4 +124,3 @@ This example `vic-machine create` command deploys a VCH with the following confi --thumbprint certificate_thumbprint --no-tls - diff --git a/docs/user_doc/vic_vsphere_admin/vch_admin.md b/docs/user_doc/vic_vsphere_admin/vch_admin.md index cb73a13765..ea00a70979 100644 --- a/docs/user_doc/vic_vsphere_admin/vch_admin.md +++ b/docs/user_doc/vic_vsphere_admin/vch_admin.md @@ -5,6 +5,7 @@ You can monitor and perform administration tasks on virtual container hosts (VCH * [Interoperability](interop.md) * [Virtual Container Host Administration in the vSphere Client](vch_admin_client.md) * [Virtual Container Host Administration with `vic-machine`](vch_admin_vicmachine.md) +* [Delete Virtual Container Hosts](remove_vch.md) * [Virtual Container Host Administration Portal](access_vicadmin.md) diff --git a/docs/user_doc/vic_vsphere_admin/vch_registry.md b/docs/user_doc/vic_vsphere_admin/vch_registry.md index 409679c08f..48c6fef870 100644 --- a/docs/user_doc/vic_vsphere_admin/vch_registry.md +++ b/docs/user_doc/vic_vsphere_admin/vch_registry.md @@ -1,4 +1,4 @@ -# Connect Virtual Container Hosts to Registries # +# Configure Registry Access # If you use vSphere Integrated Containers Registry, or if container developers need to access Docker images that are stored in other private registry servers, you must configure virtual container hosts (VCHs) to allow them to connect to these private registry servers when you deploy the VCHs. VCHs can connect to both secure and insecure private registry servers. You can also configure VCHs so that they can only access images from a whitelist of approved registries. diff --git a/docs/user_doc/vic_vsphere_admin/vch_security.md b/docs/user_doc/vic_vsphere_admin/vch_security.md index 76cf36aa64..5705c3cfbd 100644 --- a/docs/user_doc/vic_vsphere_admin/vch_security.md +++ b/docs/user_doc/vic_vsphere_admin/vch_security.md @@ -1,10 +1,88 @@ # Virtual Container Host Security # -VCHs authenticate Docker API client connections by using client certificates. This configuration is commonly referred to as `tlsverify` in documentation about containers and Docker. When you deploy a VCH, you must specify the level of security that applies to connections from Docker clients to the Docker API endpoint that is running in the VCH. The security options that `vic-machine create` provides allow for three broad categories of VCH client security: +By default, virtual container hosts (VCHs) authenticate connections from Docker API clients by using server and client TLS certificates. This configuration is commonly referred to as `tlsverify` in documentation about containers and Docker. -- [Restrict Access to the Docker API with Auto-Generated Certificates](tls_auto_certs.md) -- [Restrict Access to the Docker API with Custom Certificates](tls_custom_certs.md) -- [Unrestricted Access to the Docker API](tls_unrestricted.md) +- [About TLS Certificates](#about_tls) +- [Certificate Usage in Docker](#docker_certs) + - [`DOCKER_CERT_PATH`](#dockercertpath) +- [Virtual Container Host Security Options](#vch_tlsoptions) + - [Supported Configurations](#configs) -You must run all `vic-machine` commands with a vSphere administrator account. However, you can configure a VCH so that it uses an account with reduced privileges for post-deployment operation, instead of using the vSphere administrator account. For information about using a separate account for post-deployment operation, [Configure Operations User](set_up_ops_user.md). +## About TLS Certificates +A certificate is made up of two parts: + +- A public certificate part, that is distributed to anyone who needs it +- A private key part, that is kept secret + +Paired certificate and key files follow general naming conventions: + +- `cert.pem` and `key.pem` +- `.pem` and `-key.pem` +- `-cert.pem` and `-key.pem` + +For general information about TLS certificates, see https://en.wikipedia.org/wiki/Transport_Layer_Security. + +## Certificate Usage in Docker + +There are four certificates in use in a Docker `tlsverify` configuration: + +- **(1)** A client certificate, held by the Docker client. +- **(2)** A server certificate, held by the server, which in a VCH is the Docker API endpoint. +- **(3)** A certificate authority (CA), that signs the server certificate. +- **(4)** Another CA, that signs the client certificate and is held by the server. + +When using the Docker client, the client validates the server either by using CAs that are present in the root certificate bundle of the client system, or that container developers provide explicitly by using the `--tlscacert` option when they run Docker commands. As a part of this validation, the server certificate must match the name or address of the system from which the Docker client accesses the server. The server certificate must explicitly state at least one of the following: + +- The FQDN of the system from which the Docker client communicates with the server +- The IP address of the system from which the Docker client communicates with the server +- A wildcard domain that matches all of the FQDNs in a specific subdomain. + +If the server certificate includes a wildcard domain, all of the systems in that domain can connect to the server. For an example of a domain wildcard, see [https://en.wikipedia.org/wiki/Wildcard_certificate#Example](https://en.wikipedia.org/wiki/Wildcard_certificate#Example). + +### `DOCKER_CERT_PATH` + +Docker clients search for certificates in the `DOCKER_CERT_PATH` location on the system on which the Docker client is running. Docker requires certificate files to have the following names if they are to be consumed automatically from `DOCKER_CERT_PATH`: + +|**File Name**|**Description**| +|---|---| +|`cert.pem`, `key.pem`|Client certificate **(1)** and private key. client certificate.| +|`server-cert.pem`, `server-key.pem`|Server certificate **(2)**| +|`ca.pem`|Public portion of the certificate authority that signed the server certificate **(3)**. Allows the server to confirm that a client is authorized.| + +For information about how to provide certificates to Docker clients, see [Configure the Docker Client for Use with vSphere Integrated Containers](../vic_app_dev/configure_docker_client.md). + +## Virtual Container Host Security Options + +As a convenience, vSphere Integrated Containers Engine can optionally generate client **(1)** and server **(2)** certificates. It can also generate one CA that serves as both **(3)** and **(4)**. If you use an automatically generated CA, vSphere Integrated Containers Engine uses that CA to sign both of the client and server certificates. This means that you must provide to the Docker client both the client certificate and the public part of the CA, so that the client can trust the server. You must provide a client certificate and CA for every VCH that a Docker client connects to. + +Rather than using an automatically generated CA, in a production deployment you would normally use custom CAs. In this case: + +- **(3)** is usually signed by a company certificate that is rooted by a public or corporate trust authority, for example Verisign. +- **(4)** can be unique per client or group of clients. Using the same CA for a group of clients allows each client to have a unique certificate, but allows the group to be authorized as a whole. For example, you could use one CA per VCH, multiple CAs per VCH, or one CA per group of VCHs. + +When you deploy a VCH, you must specify the level of security that applies to connections from Docker clients to the Docker API endpoint in the VCH, and whether to use automatically generated or custom certificates. + +### Supported Configurations + +You can use all automatically generated certificates, all custom certificates, or a combination of both. + +**NOTE**: The Create Virtual Container Host wizard in the vSphere Client does not support automatically generated CA or client certificates. To use automatically generated CA and client certificates, you must use the `vic-machine` CLI utility. + +The following table provides a summary of the configurations that vSphere Integrated Containers Engine supports, and whether you can implement those configurations in the vSphere Client. + +|**Configuration**|**Available in vSphere Client?**| +|---|---| +|Auto-generated server certificate + custom CA + custom client certificate|Yes| +|Auto-generated server certificate + auto-generated client certificate + auto-generated CA|No| +|Auto-generated server certificate + no client verification|Yes| +|Custom server certificate + custom CA + custom client certificate|Yes| +|Custom server certificate + auto-generated client certificate + auto-generated CA|No| +|Custom server certificate + no client verification|Yes| +|No server or client certificate verification|Yes| + +The following topics describe how to achieve all of the configurations listed in the table above. + +- [Use Automatically Generated Server Certificates](tls_auto_certs.md) +- [Use Custom Server Certificates](tls_custom_certs.md) +- [Disable Certificate Authentication](tls_unrestricted.md) \ No newline at end of file