Deploying and using the SSL Certificate Automation Tool 5.5 (2057340)

Purpose

About the SSL Certificate Automation Tool 5.5

The SSL Certificate Automation Tool is a command-line utility that automates the Self- or CA-signed certificate renewal process for vSphere 5.5. The main purpose of the tool includes:

• Certificate Signing Request generation and Certificate update - Helps with certificate deployment and trust update. Note that the tool does not generate custom certificates for you. You are expected to generate these certificates offline following the instructions in this document.
• Update Steps Planner - Allows you to plan the sequence of certificate updates for the components. This prevents errors in the process that might otherwise occur.

Prior to the SSL Certificate Automation Tool, all certificate requests and certificates had to be created manually. As of version 1.0.1, the tool automates the creation of certificate requests. It does not automate the submission of the certificate requests to a CA. With the introduction of SSL Certificate Automation Tool 5.5, VMware introduces support for vSphere 5.5 components.

For instructions on generating supported certificate requests and certificates for the vCenter services, see Generating certificates for use with the VMware SSL Certificate Automation Tool (2044696).

Supported platforms

The SSL Certificate Automation Tool is available only to machines running Windows operating systems. The tool has been tested and verified on these Windows versions:

• Windows 2008 R2 SP1
• Windows 2012 Standard and Datacenter

Compatibility

The SSL Certificate Automation Tool 5.5 works with your vSphere 5.5 environment only. If you need to replace the certificates on a vSphere 5.1 environment, see Deploying and using the SSL Certificate Automation Tool (2041600).

• SSL Certificate Automation Tool 1.0 is supported with vSphere 5.1
• SSL Certificate Automation Tool 1.0.1 is supported with vSphere 5.1 Update 1 and later, excluding vSphere 5.5
• SSL Certificate Automation Tool 5.5 is supported with vSphere 5.5

Prerequisites

To run the SSL Automation Tool, you must meet these requirements:

• Administrative privileges on the server(s) on which you are running the tool. Although non-administrator users can download and launch the tool, all operations fail without the proper permissions.
• Access to each server that has vSphere components for which the SSL certificate should be updated.
• All vCenter Server components for which the certificates are to be updated are already installed and running.
• The new certificates and private keys already exist and you know the location of the new certificates. For increased security, generate each certificate and private key on the machine where it will be used.

Certificate Requirements

You can obtain the CA-signed certificates before you run the tool, or you can have the tool generate the certificate requests for you. Before you run the tool to replace certificates, ensure that the new SSL certificate for each vSphere component has a unique Subject Distinguished Name encoded within the certificate.

Note: A unique OU is not mandatory. The OU is only a part of the DN. Having a unique OU is one way to achieve unique DN, but is certainly not the only way.

The certificates and private keys must meet these requirements:

• Private key algorithm: RSA
• Private key length: >= 2048
• Private key standard: PKCS#1 or PKCS#8
• Private key storage: PEM

Recommended certificate signature algorithm are:

• sha256WithRSAEncryption 1.2.840.113549.1.1.11
• sha384WithRSAEncryption 1.2.840.113549.1.1.12
• sha512WithRSAEncryption 1.2.840.113549.1.1.13

The certificate chain format must meet these requirements:

• Single PEM file that contains a sequence of PEM (base64) encoded X.509 certificates ordered from the leaf certificate to and including the self-signed authority certificate.
• The file should not contain any comments, spaces and tabs, before, between and after certificates.
• Each certificate begins with -----BEGIN CERTIFICATE------ and ends with -----END CERTIFICATE------, each on a new line with no spaces before or after, respectfully.
• No extra certificates are in the file.
• The certificate chain is complete. That is, either the file contains all certificates forming the chain or the certificate chain is incomplete but can be completed using certificates from the Windows trust store.

The path or file name for certificates and keys does not contain any of these special characters:

• ^ (caret)
• % (percent)
• & (ampersand)
• ; (semicolon)
• ) (closing parenthesis)

Note: The tool exits or reports an error if it encounters any of these special characters.

Resolution

Before you begin

Before proceeding, ensure that you are aware of these points:

• If you are running the vCenter Server services in a virtual machine, take a snapshot of the virtual machine before starting the process to expedite recovery times in case of failure. Ensure to also remove the snapshot after the process completes successfully.
• Updating certificates for third-party components such as load balancers and on non-Window OS machines must be done manually.
• Any character input containing the ^ (caret) character are not allowed.
• If the path or file name of the tool or new certificates contain any of the special characters, such as ^ (caret), % (percent), & (ampersand), ; (semicolon), or ) (closing bracket), the tool fails and either exits, throws an exception, or reports that the certificate or key files are not found.
• You must shut down any dependent solutions that are running in the environment to prevent failures of these services. The solutions that are to be shut down while updating the certificates include:
  
  • VMware Site Recovery Manager
  • vSphere Data Recovery
  • vCloud Director
  • Any third-party solution which may be connecting to vCenter Server
• Ensure you review the Known Issues section of this article.

Installing or upgrading the SSL Certificate Automation Tool

You must install and deploy the SSL Certificate Automation Tool on each machine on which a vSphere component resides. However, you can use the tool on a single machine to do the initial planning.

There are three possible configurations for installing the SSL Certificate Automation Tool:

• Single machine (all services in one machine)
  
  All services are located on the same machine. In this case, the SSL Certificate Automation Tool must be deployed in one machine.
• Multiple machines (machine per service)
  
  Each service is located on a different machine. In this case, the SSL Certificate Automation Tool must be deployed on each machine running one of the seven services.
• Mixed mode (multiple services per machine)
  
  Some services are run on one machine, but others run on a different machine. In this case, the SSL Certificate Automation Tool must be deployed on all the machines which have services that are to be updated, and machines where there are deployed services communicating with the ones that are to be updated. Use the Update Steps Planner to determine the exact order of the steps for deployment.

Installing the SSL Certificate Automation Tool

To install the SSL Certificate Automation Tool:

Note: Ensure that the installation path for the SSL Certificate Automation tool does not contain any spaces.

1. Download the SSL Certificate Automation Tool from the VMware Download Center. This download is located in the Drivers and Tools section of the vSphere and vCloud Suite download pages.
2. Copy the tool to each machine on which a vSphere component resides.
3. Use an unzipping utility, unzip the file into any directory, preserving the directory structure.

Upgrading the SSL Certificate Automation Tool

Upgrading to a newer version of the SSL Certificate Automation Tool is simple because no installation is required. To upgrade the SSL Certificate Automation Tool from a previous version:

Note: Ensure that the installation path for the SSL Certificate Automation tool does not contain any spaces.

1. Download the SSL Certificate Automation Tool from the VMware Download Center. This download is located in the Drivers and Tools section of the vSphere and vCloud Suite download pages.
2. Copy the tool to each machine on which a vSphere component resides.
3. Use an unzipping utility to unzip the file into a different directory than the previous one that the tool was using, preserving the directory structure.

Note: VMware also recommends removing the older version of the tool to avoid confusion. To remove the older version, delete the folder where the older tool resides.

Using the SSL Certificate Automation Tool

After the tool is installed, you can use it to update certificates. Before beginning, however, it is possible to predefine default values to partially automate the process. Although it is not required, this can help avoid errors in the subsequent configuration steps. If you are not predefining the default values, proceed to the Running the Update Steps Planner section.

Predefining default values

Predefining the default values in the tool helps prevent typing errors and save time. This lets the tool automatically include specific information that you have defined as the default, instead of prompting you for it. For security reasons, only passwords cannot be saved when defining default values.

To predefine default values:

1. Open the ssl-environment.bat file in a text editor, such as Notepad. By default, this file is located in the root of the tool directory.
2. For each relevant component you want to update, enter the required parameters and the option parameters you want to change. For example, for vCenter Server you can edit the vc_cert_chain, vc_private_key and vc_username parameters.
   
   When you include the information in the ssl-environment.bat file, the SSL Certificate Automation Tool saves this information and uses it to automatically pre-fill required input during certificate updates, trust updates, and rollback operations.
3. After you have entered all the information, save and close the ssl-environment.bat file in the tools directory.
   
   Note: The values created by ssl-environment.bat file are read-only when the tool starts up. If you run the ssl-environment.batfile while the SSL Certificate Automation Tool is running, the values are not read.

Running the Update Steps Planner

The Update Steps Planner is an option that allows you to determine the order in which you should proceed to properly update the SSL configuration. VMware recommends that you follow the steps presented in the Update Steps Planner exactly as they are presented to ensure that the configuration is properly updated.

To run the Update Steps Planner:

1. Log in to any machine on which the SSL Certificate Automation Tool is installed.
2. From a command line, navigate to the location where you unzipped the tool.
3. Run this command:
   
   ssl-updater.bat
4. At the main menu, choose Plan your steps to update SSL certificates to determine the steps needed to update the SSL certificates.
5. Enter the numbers representing the services to update.
   
   To update more than one SSL certificate, separate the numbers with a comma. For example, to update the SSL certificates on Single Sign-On, vCenter Server, and the vSphere Web Client, type:
   
   1,3,4
   
   To update the certificate on all services that are supported by the tool, type 8. The menu selections show all of the supported services.
   
   Note: The vSphere Web Client and the Log Browser reside on the same machine.
6. The Update Steps Planner shows what you need to do and the order in which to do it. Perform the tasks in the order the Planner presents.
   
   Note: When using the Update Steps Planner, enter all of the services you update. If you enter the services separately, the Planner cannot correctly determine the order of the steps. Performing the steps in the incorrect order can cause the update process to fail. To ensure that you have the order correct, leave the console open to the full list of steps or save the list to a text file. This allows you to track your progress.
7. After making a copy of the output, type 9 to return to the main menu.

After completing these steps, proceed to the Updating SSL Certificates and trusts section, unless you need to generate Certificate Requests beforehand.

Generating Certificate Requests

The SSL Certificate Automation Tool provideds the functionality to create certificate requests. This functionality helps prevent common configuration issues when generating supported certificates for use with the vCenter Server services.

For instructions on using the new certificate request functionality and generating supported certificates for the vCenter Server services, see   Generating certificates for use with the VMware SSL Certificate Automation Tool (2044696).

Updating SSL Certificates and trusts

The Update Steps Planner shows the exact steps that must be followed (given the services selected) to ensure successful completion. To simplify the process, the services are listed individually in the main menu with the trust and certificate update options for each specific service.

For example, to update the Inventory Service configuration, choose Inventory Service from the menu. You are then prompted with the Update the Inventory Service Trust to Single Sign-On and Update the Inventory Service SSL Certificate options in this menu.

The workflow is simple and you must run these commands one after another.

Note: The Ctrl+C option to cancel the current command does not work while running the tool.

After you select an option, enter the information when prompted, such as the locations of the new SSL chain and private key and passwords. When complete, the operation proceeds and either a success message is presented or an error explaining the problem is reported. For more information on troubleshooting failures, see the Troubleshooting section of this article.

After a step is successful, proceed to the next step as described in the Update Steps Planner. You might need to navigate to a different machine to continue the process. If this is necessary, deploy and start the tool on the applicable machine.

Note: Keep the tool running on each machine to save time and to avoid re-entering input because the Update Steps Planner might require that you return to that machine for a later step.

After all the steps provided by the Update Steps Planner are complete, you have successfully updated your certificates. Proceed to the Exiting the SSL Certificate Automation Tool section.

Exiting the SSL Certificate Automation Tool

After you have completed your update plan, you can select the appropriate menu options to exit from the tool. Closing the command prompt window also aborts the current session and any incomplete or in-process actions are lost.

Note: The Ctrl+C option to cancel the current command does not work while running the tool. You must either close the window and launch the tool again or enter invalid data to force a failure.

Troubleshooting

If a specific update command fails, there are several options that you can use to troubleshoot.

Rollback

The SSL Certificate Automation Tool has a built-in rollback functionality. During the update operation, each action taken backs up the original state that the service configuration was in. If, for any reason, the update is not successful, you might need to roll back the failed step.

For each service, there is an option to rollback the configuration. Run this command to restore the state of the configuration that was in place before beginning the update process. The SSL Certificate Automation Tool automatically saves a copy of the existing certificate configuration in a backup folder, ensuring that you can roll back to the previously used certificate to keep the entire system up and running.

Note: After rolling back the vCenter Server certificate, you must update the vCenter Server trust to the VMware Update Manager again.

The SSL Certificate Automation Tool log

To determine the cause of a failure, updates and actions are logged for each command. By default, the logs are available in the /logdirectory within the directory to which the SSL Certificate Automation Tool has been extracted. If your corporate policy or environment requires it, you can change the log folder before starting the tool. Set the default log directory using the LOGS_FOLDER variable in the ssl-environment.bat file.

To review the log:

1. Open the SSL_Certificate_Automation_Tool_Directory/logs directory.
2. Locate the log for the action you want to verify. For example, the sso-update-ssl.log file. If there are multiple logs for the same action, use the log file date and time to determine the correct log file to use.
3. Open the log file with any text editor and search for the error during the execution.

After you have identified the issue by searching the log file, correct the problem and execute the failed step again.

For more information, see the Known Issues section.

Known Issues

This section lists known issues when using the SSL Certificate Automation Tool. Ensure that you review this list to determine if your environment may be affected:

• No error when you replace the certificate for a service with a certificate already in use by a service.
  
  If you are using the Certificate Automation Tool to replace certificates, and you respond to the prompts by replacing an existing certificate with a certificate already in use by a service, the tool does not display an error message. The tool proceeds with the replacement. Because each service must have a unique certificate in the vCenter Server installation on Windows, authentication does not work properly.
  
  Currently, there is no workaround.
• SSL Certificate Update fails if vCenter Single Sign-On Password contains spaces or special characters such as &, ^, %, <.
  
  If the vCenter Single Sign-On password has a space or any special characters, such as &, ^, %, or <, the configuration of the Inventory service fails.
  
  To work around this issue, change the vCenter Single Sign-On password so it does not contain a space or any of the special characters &, ^, %, < in it.
• If the certificate chain file for vCenter Single Sign-On is out-of-order, you see an error similar to:
  
  Certificate chain is incomplete: the root authority certificate is not present and could not be detected automatically. The presence of the root certificate is required so the other service can establish trust to this service. Try adding the authority certificate manually.
  
  To resolve this issue, ensure that the certificate chain file for vCenter Single Sign-On is created in the correct order. For more information, see Generating certificates for use with the VMware SSL Certificate Automation Tool (2044696).
• vCenter Server to vCenter Single Sign-On Trust operation fails causing the tool to exit abruptly.
  
  If there are spaces in the path used for the certificates, the vCenter Server to Single Sign-On Trust update operation fails, causing the tool to abruptly exit.
  
  To work around this issue, remove spaces in the path to the SSL certificates.
• CSR Generation fails if the SSL certificate Automation Tool folder name contains spaces.
  
  Ensure that the name of the directory in which the SSL Certificate Automation Tool is extracted and the specified CSR directory above do not have spaces. If not, the CSR Generation fails.
• If the path to the certificate chains is incorrect, you see the error:
  
  Exception in thread "main" java.io.FileNotFoundException: C:\certs\wrongfile\rui.crt (The system cannot find the file specified)
   at java.io.FileInputStream.open(Native Method)
   at java.io.FileInputStream.<init>(Unknown Source)
  
  This is an expected behavior.
  
  To resolve this issue, correct the path to the chain file and run the step again.
• When connecting to the VMware Inventory service in Linked Mode Configurations, you see the error:
  
  Client Not authenticated
  
  When updating all certificates while running in a Linked mode configuration, you may not be able to log in to the inventory service for 10 minutes after the certificates have been updated. After this time, authentication is successful and functionality is restored.
• SSL Certificate Automation Tool may fail if custom ports are used for components.
  
  If custom ports are used for the installation of vCenter Server services, configuration of certificates with the SSL Certificate Automation Tool may fail. This is a known issue.
  
  To work around this issue, use the default ports.

Source:-
http://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=2057340

&src=vmw_so_vex_ragga_1012