Added information about appliance certificates (#677)

* Added troubleshooting topic about browser cert errors

* Adding new topic on Chrome certs

* Informed users to validate cert before trusting

* Adding info about validating appliance certs

* Minor comment from Zach.

docs/user_doc/SUMMARY.md

@@ -71,6 +71,7 @@
      * [Access Log Bundles](vic_vsphere_admin/log_bundles.md)
      * [VCH Deployment Times Out](vic_vsphere_admin/ts_vch_deployment_timeout.md)
      * [Certificate Verification Error](vic_vsphere_admin/ts_thumbprint_error.md)
+     * [Browser Rejects Certificates](vic_vsphere_admin/ts_cert_error.md)
      * [Missing Common Name Error Even When TLS Options Are Specified Correctly](vic_vsphere_admin/ts_cli_argument_error.md)
      * [Firewall Validation Error](vic_vsphere_admin/ts_firewall_error.md)
      * [Certificate cname Mismatch](vic_vsphere_admin/ts_cname_mismatch.md)
@@ -82,13 +83,16 @@
      * [Deleting or Inspecting a VCH Fails](vic_vsphere_admin/ts_delete_inspect_error.md)
      * [Certificate Errors when Using Full TLS Authentication with Trusted Certificates](vic_vsphere_admin/ts_clock_skew.md)
      * [Appliance VM Password Refused](vic_vsphere_admin/ts_appliance_password_refused.md)
-  * [Security Reference](vic_vsphere_admin/security_reference.md)
-
+  * [Security](vic_vsphere_admin/security_reference.md)
+     * [Certificate Reference](vic_vsphere_admin/vic_cert_reference.md)
+     * [Obtain Appliance Certificates](vic_vsphere_admin/obtain_appliance_certs.md)
+
 
 ----
 
 * [Configure and Manage](vic_cloud_admin/README.md)
-   * [Logging In to the Management Portal](vic_cloud_admin/logging_in_mp.md)
+   * [Logging in to the Management Portal](vic_cloud_admin/logging_in_mp.md)
+      * [Verify and Trust Certificates](vic_cloud_admin/trust_vic_certs.md)
    * [Configure System Settings](vic_cloud_admin/configure_system.md)
    * [Add Cloud Administrators](vic_cloud_admin/add_cloud_admins.md)
    * [Add Viewers, Developers, or DevOps Administrators to Projects](vic_cloud_admin/add_users.md)

docs/user_doc/vic_cloud_admin/logging_in_MP.md

@@ -2,7 +2,11 @@
 
 You can access the Management Portal in a web browser by entering the vSphere Integrated Containers appliance IP address and the port that you specified for the portal during the deployment. By default the port number is *8282*.
 
-If you don't know the port number, you can access the portal by going to http://<i>vic_appliance_address</i> and following the **Go to the vSphere Integrated Containers Management Portal** link.
+If you do not know the port number, you can access the portal by going to http://<i>vic_appliance_address</i> and following the **Go to the vSphere Integrated Containers Management Portal** link.
+
+To remove security warnings when you connect to the Getting Started page or management portal, see [Obtain the Thumbprints and CA Files of the vSphere Integrated Containers Appliance Certificates](obtain_appliance_certs.md) and [Verify and Trust vSphere Integrated Containers Appliance Certificates](../vic_cloud_admin/trust_vic_certs.md).
+
+If you see a certificate error when you attempt to go to http://<i>vic_appliance_address</i>, see [Browser Rejects Certificates with `ERR_CERT_INVALID` Error](ts_cert_error.md).
 
 ## Default User Access to the Management Portal ##
 

docs/user_doc/vic_cloud_admin/trust_vic_certs.md

@@ -0,0 +1,26 @@
+# Verify and Trust vSphere Integrated Containers Appliance Certificates 
+
+You can verify the self-signed certificates and trust the certificate authority (CA) for the vSphere Integrated Containers Getting Started page and the vSphere Integrated Containers Management Portal. Trusting the CA  prevents browsers from giving security warnings and potentially locking you out of vSphere Integrated Containers for security reasons.
+
+**Prerequisites**
+
+To verify and trust the vSphere Integrated Containers appliance certificates, you must obtain the thumbprints and CA files either directly from the appliance, or from the vSphere administrator. For information about how to obtain certificate information, see [Obtain the Thumbprints and CA Files of the vSphere Integrated Containers Appliance Certificates](../vic_vsphere_admin/obtain_appliance_certs.md).
+
+**Procedure**
+
+1. In a browser, go to the Getting Started Page at http://<i>vic_appliance_address</i>.
+2. View the certificate details in the browser and locate the SHA-1 thumbprint.
+
+    How you view the certificate details depends on the type of browser that you use.
+
+5.  Compare the SHA-1 thumbprint in the browser to the thumbprint that you or the vSphere administrator obtained from the appliance.
+
+    The thumbprints should be the same.
+6.  Click the link to the vSphere Integrated Containers Management Portal in the Getting Started page, log in, and repeat the procedure to verify the certificate thumbprint for the management portal.
+7.  When you have verified both of the thumbprints, import the `ca.crt` files into the root certificate store on your local machine.
+
+    How you import a CA file into the root certificate store depends on the operating system of your local machine. 
+
+**Result**
+
+When you access the Getting Started page and vSphere Integrated Containers Management Portal, your browser shows that the connection is secure.

docs/user_doc/vic_vsphere_admin/access_vicadmin.md

@@ -17,3 +17,5 @@ After you log in, the VCH Admin portal displays information about the VCH and th
 - The system time of the VCH. This is useful to know because clock skews between VCHs and client systems can cause TLS authentication to fail. For information about clock skews, see [Connections Fail with Certificate Errors when Using Full TLS Authentication with Trusted Certificates](ts_clock_skew.md). 
 - The remaining capacity of the datastore that you designated as the image store. If the VCH is unable to connect to vSphere, the datastore information is not displayed.
 - Live logs and log bundles for different aspects of the VCH. For information about the logs, see [Access vSphere Integrated Containers Engine Log Bundles](log_bundles.md).
+
+If you see a certificate error when you attempt to log in to the VCH Administration Portal, see [Browser Rejects Certificates with `ERR_CERT_INVALID` Error](ts_cert_error.md).

docs/user_doc/vic_vsphere_admin/deploy_vic_appliance.md

@@ -83,7 +83,9 @@ You install vSphere Integrated Containers by deploying a virtual appliance. The
 
     **IMPORTANT**: The installation process requires the single sign-on credentials to register vSphere Integrated Containers Management Portal and Registry with the Platform Services Controller. The vSphere Integrated Containers Management Portal and Registry services cannot start if you do not complete this step.
 
-You can reconfigure the appliance after deployment by editing the settings of the appliance VM. For information about reconfiguring the appliance, see [Reconfigure the vSphere Integrated Containers Appliance](reconfigure_appliance.md).
+**Result**
+
+You see the vSphere Integrated Containers Getting Started page at http://<i>vic_appliance_address</i>. The Getting Started page includes links to the vSphere Integrated Containers Management Portal, the Demo VCH Installer Wizard, the download for the vSphere Integrated Containers Engine bundle, and to documentation.
 
 **What to Do Next**
 
@@ -97,7 +99,9 @@ Access the different vSphere Integrated Containers components from the  vSphere
    - Install the vSphere Client plug-ins for vSphere Integrated Containers. For information about installing the plug-ins, see [Installing the vSphere Client Plug-ins](install_vic_plugin.md).       
    - Use `vic-machine` to deploy production VCHs. For information about deploying VCHs with `vic-machine`, see [Deploy Virtual Container Hosts with `vic-machine`](deploy_vch.md).
 
-
+- To remove security warnings when you connect to the Getting Started page or management portal, see [Obtain the Thumbprints and CA Files of the vSphere Integrated Containers Appliance Certificates](obtain_appliance_certs.md) and [Verify and Trust vSphere Integrated Containers Appliance Certificates](../vic_cloud_admin/trust_vic_certs.md).
+- If you see a certificate error when you attempt to go to http://<i>vic_appliance_address</i>, see [Browser Rejects Certificates with `ERR_CERT_INVALID` Error](ts_cert_error.md).
+- If necessary, you can reconfigure the appliance after deployment by editing the settings of the appliance VM. For information about reconfiguring the appliance, see [Reconfigure the vSphere Integrated Containers Appliance](reconfigure_appliance.md).   
 
 
 

docs/user_doc/vic_vsphere_admin/obtain_appliance_certs.md

@@ -0,0 +1,33 @@
+# Obtain the Thumbprints and CA Files of the vSphere Integrated Containers Appliance Certificates
+
+If you do not provide custom certificates during deployment, the OVA installer generates certificates for the vSphere Integrated Containers Management Portal and the vSphere Integrated Containers file server. These certificates authenticate connections to the Getting Started page, vSphere Integrated Containers Management Portal, and the vSphere Integrated Containers Engine bundle and vSphere Client plug-in downloads. If you deploy the appliance with automatically generated certificates, the certificates are self-signed by an automatically generated Certificate Authority (CA).
+
+The vSphere administrator obtains the thumbprints and CA files and passes them to other users who need to access the Getting Started page or the vSphere Integrated Containers Management Portal. 
+
+**Procedure**
+
+1. Use SSH to connect to the vSphere Integrated Containers appliance as `root` user.<pre>$ ssh root@<i>vic_appliance_address</i></pre>
+2. Use `openssl` to view the certificate fingerprint of the file server. 
+
+    The file server certificate authenticates access to the Getting Started page, including the downloads for the vSphere Integrated Containers Engine bundle and the vSphere Client plug-in. 
+
+    <pre>openssl x509 -in  /opt/vmware/fileserver/cert/server.crt -noout -sha1 -fingerprint</pre>
+
+2. Use `openssl` to view the certificate fingerprint of the management portal. 
+
+    The management portal certificate authenticates access to the vSphere Integrated Containers Management Portal. 
+
+    <pre>openssl x509 -in  /data/admiral/cert/server.crt -noout -sha1 -fingerprint</pre>
+
+3. Take a note of the two thumbprints and close the SSH session.
+4. Use `scp` to copy the CA file for the file server to your local machine.
+
+    <pre>scp root@<i>vic_appliance_address</i>:/opt/vmware/fileserver/cert/ca.crt <i>/path/on/local_machine/folder1</i></pre>
+
+5. Use `scp` to copy the CA file for the management portal to your local machine.
+
+    <pre>scp root@<i>vic_appliance_address</i>:/data/admiral/cert/ca.crt <i>/path/on/local_machine/folder2</i></pre>
+
+     Be sure to copy the two files to different locations, as they are both named `ca.crt`.
+
+You can share the thumbprints and CA files with users who need to connect to the vSphere Integrated Containers Management Portal or downloads. For information about how to verify the thumbprints and trust  the CAs, see [Verify and Trust vSphere Integrated Containers Appliance Certificates](../vic_cloud_admin/trust_vic_certs.md).

docs/user_doc/vic_vsphere_admin/ts_cert_error.md

@@ -0,0 +1,29 @@
+# Browser Rejects Certificates with `ERR_CERT_INVALID` Error #
+
+Attempts to connect to vSphere Integrated Containers web interfaces fail with certificate errors in Google Chrome browsers.
+
+## Problem ##
+
+When you attempt to access the vSphere Integrated Containers Getting Started page, vSphere Integrated Containers Management Portal, or the administration portal for a virtual container host (VCH), Google Chrome rejects the connection with an `ERR_CERT_INVALID` error and a warning similar to the following:
+
+<pre><i>Web_address</i> normally uses encryption to protect your information. When Google Chrome tried to connect to <i>web_address</i> this time, the website sent back unusual and incorrect credentials...
+
+You cannot visit <i>web_address</i> right now because the website sent scrambled credentials that Google Chrome cannot process...</pre>
+
+This issue only affects Google Chrome. Other browsers do not report certificate errors.
+
+## Cause ##
+
+You have already accepted a client certificate or a generated Certificate Authority (CA) for a previous instance of the vSphere Integrated Containers appliance or for a VCH that had the same FQDN or IP address as the new instance.
+
+## Solution ##
+
+1. Search the keychain on the system where the browser is running for client certificates or CAs that are issued to the FQDN or IP address of the vSphere Integrated Containers appliance or VCH. 
+
+    Auto-generated vSphere Integrated Containers appliance and VCH certificates are issued by **Self-signed by VMware, Inc**.
+
+2. Delete any client certificates or CAs for older instances of vSphere Integrated Containers appliances or VCHs.
+3. Clear the browser history, close, and restart Chrome.
+4. Connect to the vSphere Integrated Containers Getting Started page, vSphere Integrated Containers Management Portal, or VCH Administration portal again, verify the certificate, and trust it if it is valid.
+
+For information about how to verify certificates for the vSphere Integrated Containers appliance, see [Verify and Trust vSphere Integrated Containers Appliance Certificates](../vic_cloud_admin/trust_vic_certs.md).

docs/user_doc/vic_vsphere_admin/vic_cert_reference.md

@@ -0,0 +1,17 @@
+# vSphere Integrated Containers Certificate Reference #
+
+vSphere Integrated Containers authenticates connections to its various components by using TLS certificates. In some cases, the certificates are always automatically generated and self-signed. In other cases, you have the option of providing custom certificates.
+
+This topic provides a reference of all of the certificates that vSphere Integrated Containers uses.
+
+
+|**Component**|**Certificate Type**|**Purpose**|**Used By**|
+|---|---|---|---|
+|vCenter Server or ESXi host|Self-signed or custom|Required for installation of the vSphere Client plug-ins and deployment and management of virtual container hosts (VCHs). See [Obtain the Certificate Thumbprint of vCenter Server or an ESXi Host](obtain_thumbprint.md).|vSphere administrator|
+|vSphere Integrated Containers Management Portal|Self-signed or custom|Authenticates connections from browsers to vSphere Integrated Containers Management Portal. See [Obtain the Thumbprints and CA Files of the vSphere Integrated Containers Appliance Certificates](obtain_appliance_certs.md) and [Verify and Trust vSphere Integrated Containers Appliance Certificates](../vic_cloud_admin/trust_vic_certs.md).|Cloud and DevOps admininistrators, developers|
+|vSphere Integrated Containers Registry|Self-signed|Authenticates connections to vSphere Integrated Containers Registry instances from Docker clients, replication of projects between registry instances, and registration of additional registry instances in the management portal. See [Configure System Settings](../vic_cloud_admin/configure_system.md).|Cloud and DevOps admininistrators, developers|
+|vSphere Integrated Containers file server|Self-signed or custom|Authenticates connections to the Getting Started page, downloads of vSphere Integrated Containers Engine binaries, and the installation of vSphere Client plug-ins. See [Obtain the Thumbprints and CA Files of the vSphere Integrated Containers Appliance Certificates](obtain_appliance_certs.md) and [Verify and Trust vSphere Integrated Containers Appliance Certificates](../vic_cloud_admin/trust_vic_certs.md).|vSphere administrator, Cloud and DevOps admininistrators, developers|
+|VCH|None, self-signed, or custom|Authenticates connections from Docker clients to VCHs. See [VCH Deployment Options](vch_installer_options.md#security).|vSphere administrator, Cloud and DevOps admininistrators, developers |
+|VCH Administration Portal|None, self-signed, or custom|Authenticates connections from browsers to the administration portals of individual VCHs. See [VCH Administration Portal](access_vicadmin.md).|vSphere administrator|
+
+