Your company's security policy might require that you replace the default ESXi SSL certificate with a third-party CA-signed certificate on each host.

By default, vSphere components use the VMCA-signed certificate and key that are created during installation. If you accidentally delete the VMCA-signed certificate, remove the host from its vCenter Server system, and add it back. When you add the host, vCenter Server requests a new certificate from VMCA and provisions the host with it.

Replace VMCA-signed certificates with certificates from a trusted CA, either a commercial CA or an organizational CA, if your company policy requires it.

You can replace the default certificates with trusted certificates in various ways.

Note: You can also use the vim.CertificateManager and vim.host.CertificateManager managed objects in the vSphere Web Services SDK. See the vSphere Web Services SDK documentation.

Before you replace the certificate, you have to update the TRUSTED_ROOTS store in VECS on the vCenter Server system that manages the host to ensure that the vCenter Server and the ESXi host have a trust relationship.

For detailed instructions about using CA-signed certificates for ESXi hosts, see ESXi Certificate Mode Switch Workflows.

Note: If you are replacing SSL certificates on an ESXi host that is part of a vSAN cluster, follow the steps that are in the VMware knowledge base article at https://kb.vmware.com/s/article/56441.

Requirements for ESXi Certificate Signing Requests

If you want to use an enterprise or third-party CA-signed certificate, or a subordinate CA-signed certificate, you have to send a Certificate Signing Request (CSR) to the CA.

Use a CSR with these characteristics:

  • Key size: 2048 bits (minimum) to 16384 bits (maximum) (PEM encoded). As of vSphere 8.0 Update 2b, the maximum key size supported is 8192 bits.
  • PEM format. VMware supports PKCS8 and PKCS1 (RSA keys). When keys are added to VECS, they are converted to PKCS8.
  • x509 version 3
  • For root certificates, the CA extension must be set to true, and the cert sign must be in the list of requirements.
  • SubjectAltName must contain DNS Name=<machine_FQDN>.
  • CRT format
  • Contains the following Key Usages: Digital Signature, Key Encipherment
  • Start time of one day before the current time.
  • CN (and SubjectAltName) set to the host name (or IP address) that the ESXi host has in the vCenter Server inventory.
Note: vSphere's FIPS certificate only validates RSA key sizes of 2048 and 3072. See Considerations When Using FIPS.
vSphere does not support the following certificates.
  • Certificates with wildcards.
  • The algorithms md2WithRSAEncryption, md5WithRSAEncryption, RSASSA-PSS, dsaWithSHA1, ecdsa_with_SHA1, and sha1WithRSAEncryption are not supported.

For information about generating the CSR, see the VMware knowledge base article at https://kb.vmware.com/s/article/2113926.

Replace the Default Certificate and Key from the ESXi Shell

You can replace the default VMCA-signed ESXi certificates from the ESXi Shell.

Prerequisites

  • If you want to use third-party CA-signed certificates, generate the certificate request, send it to the certificate authority, and store the certificates on each ESXi host.
  • If necessary, enable the ESXi Shell or enable SSH traffic from the vSphere Client.
  • All file transfers and other communications occur over a secure HTTPS session. The user who is used to authenticate the session must have the privilege Host.Config.AdvancedConfig on the host.
Note: Before you replace the certificates, update the vCenter Server TRUSTED_ROOTS store. See Update the vCenter Server TRUSTED_ROOTS Store (Custom Certificates).

Procedure

  1. Log in to the ESXi Shell, either directly from the DCUI or from an SSH client, as a user with administrator privileges.
  2. In the directory /etc/vmware/ssl, rename the existing certificates using the following commands.
    mv rui.crt orig.rui.crt
    mv rui.key orig.rui.key
  3. Copy the certificates that you want to use to /etc/vmware/ssl.
  4. Rename the new certificate and key to rui.crt and rui.key.
  5. Restart the host after you install the new certificate.
    Alternatively, you can put the host into maintenance mode, install the new certificate, use the Direct Console User Interface (DCUI) to restart the management agents, and set the host to exit maintenance mode.

Replace a Default Certificate Using HTTPS PUT

You can use third-party applications to upload certificates and key. Applications that support HTTPS PUT operations work with the HTTPS interface that is included with ESXi.

Prerequisites

  • If you want to use third-party CA-signed certificates, generate the certificate request, send it to the certificate authority, and store the certificates on each ESXi host.
  • If necessary, enable the ESXi Shell or enable SSH traffic from the vSphere Client.
  • All file transfers and other communications occur over a secure HTTPS session. The user who is used to authenticate the session must have the privilege Host.Config.AdvancedConfig on the host.
Note: Before you replace the certificates, update the vCenter Server TRUSTED_ROOTS store. See Update the vCenter Server TRUSTED_ROOTS Store (Custom Certificates).

Procedure

  1. Back up the existing certificates.
  2. Set up basic access authentication, in which you supply a Base64 encoded username and password, separated with a single colon (:). For more information, see https://en.wikipedia.org/wiki/Basic_access_authentication.
  3. In your upload application, process each file as follows:
    1. Open the file.
    2. Publish the file to one of these locations.
      Option Description
      Certificates https://hostname/host/ssl_cert
      Keys https://hostname/host/ssl_key
    The /host/ssl_cert and the host/ssl_key locations link to the certificate files in /etc/vmware/ssl.
  4. Restart the host.
    Alternatively, you can put the host into maintenance mode, install the new certificate, use the Direct Console User Interface (DCUI) to restart the management agents, and set the host to exit maintenance mode.

Update the vCenter Server TRUSTED_ROOTS Store (Custom Certificates)

If you set up your ESXi hosts to use custom certificates, you must update the TRUSTED_ROOTS store on the vCenter Server system that manages the hosts.

Prerequisites

Replace the certificates on each host with custom certificates.

Note: This step is not required if the vCenter Server system is also running with custom certificates issued by the same CA as those installed on the ESXi hosts.

Procedure

  1. To update the vCenter Server TRUSTED_ROOTS store using vSphere Client, see Add a Trusted Root Certificate to the Certificate Store Using the vSphere Client.
  2. To update the vCenter Server TRUSTED_ROOTS store using using command line interface, log in to the vCenter Server shell of the vCenter Server system that manages the ESXi hosts.
  3. To add the new certificates to the TRUSTED_ROOTS store, run dir-cli, for example:
    /usr/lib/vmware-vmafd/bin/dir-cli trustedcert publish --cert path_to_RootCA
  4. When prompted, provide the Single Sign-On Administrator credentials.
  5. If your custom certificates are issued by an intermediate CA, you must also add the intermediate CA to the TRUSTED_ROOTS store on the vCenter Server, for example:
    /usr/lib/vmware-vmafd/bin/dir-cli trustedcert publish --cert path_to_intermediateCA

What to do next

Set certificate mode to Custom. If the certificate mode is VMCA, the default, and you perform a certificate refresh, your custom certificates are replaced with VMCA-signed certificates. See Change the ESXi Certificate Mode.