Search the VMware Knowledge Base (KB)
View by Article ID

Deploying and using the SSL Certificate Automation Tool 1.0.x (2041600)

  • 90 Ratings

Details

About the SSL Certificate Automation Tool

With the underlying architectural changes in vCenter Server 5.1, multiple certificates are needed for various components to securely interact with one another. For those customers who need to install custom certificates, this has meant spending additional time generating and installing certificates for each component.

Note: This article is not applicable if you are using the vRealize Orchestrator Appliance, formerly known as VMware vCenter Orchestrator Appliance .

The SSL Certificate Automation Tool is a command-line utility that automates the Self- or CA-signed certificate renewal process. Of particular significance is the Update Steps Planner, which allows you to plan the sequence of certificate updates for the components. This prevents errors in the process that might otherwise occur. 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. Afterward, the rest of the document describes the certificate tool functions and features.

Prior to the SSL Certificate Automation Tool, version 1.0.1, 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. 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 only available to machines running Windows operating systems. The tool has been tested and verified on these Windows versions:
  • Windows 2003 R2 SP2
  • Windows 2008 R2 SP1
  • Windows 2012 Standard
  • Windows 2012 Datacenter

Compatibility

The SSL Certificate Automation Tool 1.0 and 1.0.1 works with your vSphere 5.1 environment only.
  • 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

If you need to replace the certificates on a vSphere 5.5 environment, see Deploying and using the SSL Certificate Automation Tool 5.5 (2057340) .

Prerequisites

To run the SSL Certificate Automation Tool, you must have:
  • Administrative privileges on the server(s) you are running the tool on. Although non-administrator users can download and launch the tool, all operations will fail without the proper permissions.
  • Access to each server that has vSphere components for which the SSL certificate will be updated.
  • All vCenter Server components which will have their certificates updated have already been installed and are running.
  • The new certificates 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. The new SSL certificate for each vSphere component must have a unique base distinguished name (DN).

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 organizational unit (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: >= 1024
  • 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.

Solution

Before you begin

Consider this information before beginning your certificate updates:
  • 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. Be sure to also remove the snapshot once the process is successful.
  • 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 ^ (caret), % (percent), & (ampersand), ; (semicolon), or ) (closing bracket), the tool will fail and either exit, throw an exception, or report that certificate or key files are not found.
  • Shut down any dependent solutions which are running in the environment to prevent failures of these services. The solutions which must be shut down while updating the certificates are:
    • VMware Site Recovery Manager
    • vSphere Data Recovery
    • vCloud Director
    • Any third-party solution which may be connecting to vCenter Server
  • Be sure to 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 virtual machine (all services in one machine): All services are located on the same virtual machine. In this case, the SSL Certificate Automation Tool must be deployed on one virtual machine.

  • Multiple virtual machines (machine per service): Each service is located on a different virtual machine. In this case, the SSL Certificate Automation Tool must be deployed on each virtual machine running one of the seven services.

  • Mixed mode (multiple services per machine): Some services are run on one virtual machine but others run on a different virtual 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 which are communicating with the ones that are to be updated. Use the Update Steps Planner to determine the exact order of the steps for deployment.

To install the SSL Certificate Automation Tool:

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

  1. Download the SSL Certificate Automation Tool from VMware Downloads. 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 any directory, preserving the directory structure.
To upgrade the SSL Certificate Automation Tool from a previous version:

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

  1. Download the SSL Certificate Automation Tool from VMware Downloads. 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 version of the tool was using, preserving the directory structure.

    Note: Upgrading to a newer version of the SSL Certificate Automation Tool is simple because no installation is required. VMware also recommends removing the older version of the tool to avoid confusion. To remove the older version, simply delete the folder where the older tool resides.

Using the SSL Certificate Automation Tool

After the tool is installed, it is ready to start the process of updating 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 below.

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.
  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.
  4. To apply the default values, run the ssl-environment.bat file from the command line.

    Note: The values created by ssl-environment.bat file are read only when the tool starts up. If you run the ssl-environment.bat file while the SSL Certificate Automation Tool is running, the values are not read.
After completing these steps, proceed to the Running the Update Steps Planner section.

Running the Update Steps Planner

The Update Steps Planner is an option which 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 into any machine on which the SSL Certificate Automation Tool is installed.
  2. From a command line, navigate to the location into which you unzipped the tool and run the command:

    ssl-updater.bat

  3. At the main menu, choose 1. Plan your steps to update SSL certificates to determine the steps needed to update the SSL certificates.
  4. 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.

  5. 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.

    Important: When using the Update Steps Planner, enter all of the services you will 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.

    This image shows an example session when using the Update Steps Planner:



  6. After making a copy of the output , press 9 to return to the main menu.
After completing these steps, proceed to the Updating SSL certificates and trusts section.

Generating Certificate Requests

Version 1.0.1 of the SSL Certificate Automation Tool introduces new functionality to help in the creation of 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 which must be followed (given the services selected) to ensure successful completion. To simplify the process as much as possible, 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 to Update the Inventory Service Trust to Single Sign-On, and Update the Inventory Service SSL Certificate options in this menu.

In general, you must run these commands one after another, and as such the workflow is as simple as possible given the steps required to ensure a successful certificate implementation.

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

After you select an option, type the information requested at the appropriate prompts, such as the locations of the new SSL chain and private key, passwords, and so on. When complete, the operation proceeds and either a success message is presented or an error explaining the problem which occurred. 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 of 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 will also abort the current session, and any incomplete or in-process actions will be 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 which you can use to troubleshoot. You can also refer to the Known issues section of this article.

Rollback

The SSL Certificate Automation Tool has 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.

The SSL Certificate Automation Tool log

To determine the cause of a failure, updates and actions are logged for each command, which makes it simple to verify what has been done. By default, the logs are kept in the /log directory in the directory that the SSL Certificate Automation Tool has been installed into. 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 /log 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.

Known issues

This section lists known issues when using the SSL Certificate Automation Tool. Ensure that you review this list of known issues to determine if your environment may be affected:
  • vCenter Single Sign-On Password cannot contain spaces

    If the Single Sign-On password has a space in it, the configuration of the Inventory service will fail. The only workaround for this issue is to use a Single Sign-On password without a space in it.

    Note: A previously known issue with the Single Sign-On password and special characters may present itself when replacing vSphere certificates. For more information about the special characters, see vSphere 5.1 Single Sign On (SSO) installation fails with error: Error 29133. Administrator login error. (2035820).

  • Registering vSphere Update Manager fails if using a Fully Qualified Domain Name (FQDN)

    Registering vSphere Update Manager to vCenter Server with the Fully Qualified Domain Name in vCenter Server 5.1 EP1/P01 is not supported. To prevent failures, use the IP address to register to vCenter Server instead. This issue is resolved in vCenter Server 5.1 Update 1.

  • vRealize Orchestrator may fail to connect when using multiple vCenter Servers

    When updating certificates, be sure to update the vRealize Orchestrator to vCenter Trust for each vCenter Server which is used with vRealize Orchestrator.

  • vCenter Server to Single Sign-On Trust operation fails causing the tool to exit abruptly

    In this release, if there are spaces in the path used for the certificates, the vCenter Server to Single Sign-On Trust update operation will fail causing the tool to abruptly exit. To work around this issue, ensure that the path does not contain spaces.

  • Rollback may fail if the backup directory is changed

    If the backup directory used for previous SSL certificate update operations is changed in the ssl-environment.bat file, rollback will fail unless the original directory is reset before attempting rollback.

  • vCenter Server will not start if an incorrect database password is entered

    When updating the vCenter Server certificate, the database password is requested so that it can be encrypted with the new certificate. Enter the password carefully because the SSL Certificate Automation Tool does not check the validity of the password.

    If the password is entered incorrectly, vCenter Server will not start. To resolve this issue, navigate to the vCenter Server installation directory and run this command from the command line to reset the password:

    vpxd.exe -p

  • Log Browser may fail after vCenter Single Sign-On certificate is updated

    After installing and updating the certificate for vCenter Single Sign-On, the Log Browser may fail with an Unauthorized Access message. To resolve this issue, run the Update Log Browser trust to Single Sign-On command. This only occurs if updating the certificates one service at a time, in a one-by-one replacement procedure.

  • Updating the vCenter Server Certificate may fail with an error if multiple service IDs exist for the lookup service

    When updating the certificate for vCenter Server using the SSL Certificate Automation Tool, the step may fail with the error:

    The certificates that's provided as input may not be a unique certificate

    This may be caused by vpxd having multiple service IDs for the Lookup service in the vpxd.cfg file.

  • Previously upgraded vCenter Server installations which have replaced certificates may need manual intervention

    If your installation of vCenter Server has been upgraded from a previous release, you may need to perform some steps prior to running the SSL Certificate Automation Tool. For more information, see Validating and correcting errors for an upgraded vCenter Server using the SSL Certificate Automation Tool (2048202).

  • vSphere Web Client reports the error: Failed to verify the SSL certificate

    After running the SSL Certificate Automation Tool, the vSphere Web Client may report the error:

    Failed to verify the SSL certificate for one or more vCenter Server Systems

    To resolve this issue, see vSphere 5.1 Web Client reports this SSL warning after an installation or upgrade: Failed to verify the SSL certificate for one or more vCenter Server Systems (2036505).

  • Error reported when the path to the certificate chains is incorrect

    When 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 expected behavior. Correct the path to the chain file and run the step again.

  • One-by-One Installation of inventory service fails when using 4096-bit certificates

    If you are performing a one-by-one service installation with 4096-bit certificates, installation of the Inventory Service freezes. To use 4096-bit certificates, do not use a one-by-one installation. Install all components and then update the certificates for the components. This is a known issue.

  • Client Not authenticated error when connecting to VMware Inventory service in Linked Mode Configurations

    When updating all certificates while running in a Linked mode configuration, logins may fail 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.

  • After replacing the vCenter Server certificate, collection from vRealize Operations Manager no longer works.

    When updating certificates, this will break the trust with vRealize Operations Manager and will prevent data collection. To resolve this issue, see Accessing VMware vRealize Operations Manager 5.x fails with the error: Not Authorized (2041162).

  • If the Managed Object Browser of the vCenter Server has been disabled per the VMWare vSphere Hardening Guide, this causes the vCenter Server SSL Certificate Update process to fail.

    While upgrading, the Automation Tool reports the error:

    [Tue 01/28/2014 - 11:07:13.83]: Validating the input parameters...
    STATE : 4 RUNNING
    HTTPError: Unable to open or read page.
    HTTP Error 503: Service Unavailable
    [Tue 01/28/2014 - 11:07:14.77]: "Cannot log in to vCenter."
    [Tue 01/28/2014 - 11:07:14.78]: The vCenter certificate update failed.


    To resolve this issue, see vCenter Server Managed Object Browser (MOB) reports a 503 Service Unavailable error (2042554).

Additional Information

For translated versions of this article, see:

Keywords

SSL, certificate update, trust, automation tool

Request a Product Feature

To request a new product feature or to provide feedback on a VMware product, please visit the Request a Product Feature page.

Feedback

  • 90 Ratings

Did this article help you?
This article resolved my issue.
This article did not resolve my issue.
This article helped but additional information was required to resolve my issue.

What can we do to improve this information? (4000 or fewer characters)




Please enter the Captcha code before clicking Submit.
  • 90 Ratings
Actions
KB: