Managing CA-signed certificates for the vCenter Server Appliance is a complex task. In many organizations it is required to maintain proper security for regulatory requirements.
Note: The use of wildcard certificates are not supported with vCenter Server and its related services. Each service must have its own unique certificate.
These workflows are required for successful implementation:
These steps must be followed to ensure successful implementation of a custom certificate for vCenter Server Appliance. Before attempting these steps, ensure that:
Requirements for the certificates used by vCenter Server Appliance
- Key Length – The key length currently must be a maximum of 2048 bytes Before proceeding, confirm from key file (PEM encoded).
- Key File Format – Only PKCS1 is supported by all components. Make sure the base64 encoded key is in PKCS1 format. You may get RSA private keys in PKCS8 format when using some OpenSSL commands; the signal of the PKCS8 key is:
----- BEGIN PRIVATE KEY
For PKCS1, it is:
----- BEGIN RSA PRIVATE KEY
Open the key file to correct it. If it is in PKCS8 format, run this command to convert it to PKCS1:
openssl rsa -in pk8.key -out pk1.key
- Cert File Format – Only some components support the PEM format of cert file. Make sure your cert file can be loaded by all components. Remove everything before the
-----BEGIN CERTIFICATE to ensure that this is the first line of the file.
- Certificate content – The
commonName field in the Subject must be the hostname. The Subject Alternative Name subjectAltname must include the host FQDN and IP address. Otherwise, un-registering the Inventory service from SSO fails.
- Elliptic Curve Keys – These are not currently supported.
For each component of the vCenter Server Appliance, you must have a custom certificate that has a unique Subject Distinguished Name encoded within the certificate.
Note: A unique organizationUnitName (OU) is not essential, but it is recommend by VMware; the requirement for proper certificate requests and therefore certificate generation is for a unique Subject Distinguished Name. The OU is just a part of the distinguished name (DN), and having a unique OU is one way to achieve a unique DN, but it is not the only method.
This means that four different certificates are required for each vCenter Server Appliance:
- vCenter Server / vCenter Single Sign-On (SSO)
- vCenter Inventory Service
- VMware Log Browser
- vSphere AutoDeploy
Note: The vSphere Web Client and the Virtual Appliance Management Infrastructure (VAMI) use the same SSL certificate as vCenter Server. vSphere Auto Deploy does not register a solution user and does not require a unique certificate (the vCenter vServer certificate can be safely reused); however, the steps provided will install a unique certificate.
To simplify the process, this article provides the steps to create different
openssl.cfg files for each component.
This article uses
/ssl/service to store all of the files on the vCenter Server Appliance before the certificates are installed. This article also uses
C:\Certs to store all files on the system creating the certificate requests and certificate generation before uploading to the vCenter Server Appliance.
To generate the appropriate configuration files:
- On the system where you are generating the certificates, create a folder in which you can store the certificates for the different components. These steps use the C:\Certs folder.
- In the C:\Certs folder, create three other folders to organize your certificate requests. These steps use these four folders:
- vCenterSSO
- InventoryService
- LogBrowser
- AutoDeploy
- Open a text editor on the system where OpenSSL is installed.
- Create an OpenSSL configuration file for each service.
A sample configuration file appears similar to:
[ req ]
default_md = sha512
default_bits = 2048
default_keyfile = rui.key
distinguished_name = req_distinguished_name
encrypt_key = no
prompt = no
string_mask = nombstr
req_extensions = v3_req
input_password = testpassword
output_password = testpassword
[ v3_req ]
basicConstraints = CA:false
keyUsage = digitalSignature, keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = DNS:vcva55, IP: 10.0.0.10, IP:ServerIPv6Address, DNS: vcva55.vmware.com
[ req_distinguished_name ]
countryName = US
stateOrProvinceName = NY
localityName = New York
0.organizationName = VMware
organizationalUnitName = vCenterApplianceUniqueServer
commonName = vcva55.vmware.com
Paste this text into the file, replacing the information in red where appropriate.
Note: The country name is always the two-digit country code for the country.
Steps 4 to 9 discuss the changes that need to be made in each certificate file.
- Save the file as openssl_generic.cfg in c:\certs\ .
Note: If you are not using IPv6 in your environment, this can be omitted from the subjectAltName.
- For the VirtualCenter Server Service configuration file, modify the
organizationalUnitName to VMware vCenter Service Certificate and save the file as openssl_vpxd.cfg in c:\certs\vCenterSSO\.
[ req ]
default_md = sha512
default_bits = 2048
default_keyfile = rui.key
distinguished_name = req_distinguished_name
encrypt_key = no
prompt = no
string_mask = nombstr
req_extensions = v3_req
input_password = testpassword
output_password = testpassword
[ v3_req ]
basicConstraints = CA:false
keyUsage = digitalSignature, keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = DNS:server, IP:ServerIPv4Address, IP:ServerIPv6Address, DNS:server.domain.com
[ req_distinguished_name ]
countryName = Country
stateOrProvinceName = State
localityName = City
0.organizationName = Organization Name
organizationalUnitName = VMware vCenter Service Certificate
commonName = server.domain.com
- For the vCenter Inventory Service configuration file, modify the
organizationalUnitName to VMware Inventory Service Certificate and save the file as openssl_inventoryservice.cfg in c:\certs\InventoryService\.
[ req ]
default_md = sha512
default_bits = 2048
default_keyfile = rui.key
distinguished_name = req_distinguished_name
encrypt_key = no
prompt = no
string_mask = nombstr
req_extensions = v3_req
input_password = testpassword
output_password = testpassword
[ v3_req ]
basicConstraints = CA:false
keyUsage = digitalSignature, keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = DNS:server, IP:ServerIPv4Address, IP:ServerIPv6Address, DNS:server.domain.com
[ req_distinguished_name ]
countryName = Country
stateOrProvinceName = State
localityName = City
0.organizationName = Organization Name
organizationalUnitName = VMware Inventory Service Certificate
commonName = server.domain.com
- To create the VMware Log Browser configuration file, modify the
organizationalUnitName to VMware LogBrowser Service Certificate and save the file as openssl_logbrowser.cfg in c:\certs\LogBrowser\.
[ req ]
default_md = sha512
default_bits = 2048
default_keyfile = rui.key
distinguished_name = req_distinguished_name
encrypt_key = no
prompt = no
string_mask = nombstr
req_extensions = v3_req
input_password = testpassword
output_password = testpassword
[ v3_req ]
basicConstraints = CA:false
keyUsage = digitalSignature, keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = DNS:server, IP:ServerIPv4Address, IP:ServerIPv6Address, DNS:server.domain.com
[ req_distinguished_name ]
countryName = Country
stateOrProvinceName = State
localityName = City
0.organizationName = Organization Name
organizationalUnitName = VMware LogBrowser Service Certificate
commonName = server.domain.com
- To create the vSphere Auto Deploy configuration file, modify the
organizationalUnitName to VMware vSphere Autodeploy Service Certificate and save the file as openssl_autodeploy.cfg in c:\certs\AutoDeploy\.
[ req ]
default_md = sha512
default_bits = 2048
default_keyfile = rui.key
distinguished_name = req_distinguished_name
encrypt_key = no
prompt = no
string_mask = nombstr
req_extensions = v3_req
input_password = testpassword
output_password = testpassword
[ v3_req ]
basicConstraints = CA:false
keyUsage = digitalSignature, keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = DNS:server, IP:ServerIPv4Address, IP:ServerIPv6Address, DNS:server.domain.com
[ req_distinguished_name ]
countryName = Country
stateOrProvinceName = State
localityName = City
0.organizationName = Organization Name
organizationalUnitName = VMware vSphere Autodeploy Service Certificate
commonName = server.domain.com
When complete, there are three different configuration files each with a different
organizationalUnit Name. Next, generate the certificate request and corresponding key for each of the certificates.
To generate a certificate request:
- Launch a command prompt and navigate into the OpenSSL directory as previously configured in the Configuring OpenSSL article.
By default, the OpenSSL directory is located at:
C:\OpenSSL-Win32\bin
- Run this command to create the vCenter Server and vCenter Single Sign-On certificate request and export the private key:
openssl req -new -nodes -out c:\certs\vCenterSSO\rui_vpxd.csr -keyout c:\certs\vCenterSSO\rui_vpxd.key -config c:\certs\vCenterSSO\openssl_vpxd.cfg
- Run this command to create the vCenter Inventory Service certificate request and export the private key:
openssl req -new -nodes -out c:\certs\InventoryService\rui_inventoryservice.csr -keyout c:\certs\InventoryService\rui_inventoryservice.key -config c:\certs\InventoryService\openssl_inventoryservice.cfg
- Run this command to create the vSphere Log Browser certificate request and export the private key:
openssl req -new -nodes -out c:\certs\LogBrowser\rui_logbrowser.csr -keyout c:\certs\LogBrowser\rui_logbrowser.key -config c:\certs\LogBrowser\openssl_logbrowser.cfg
- Run this command to create the vSphere AutoDeploy certificate request and export the private key:
openssl req -new -nodes -out c:\certs\AutoDeploy\rui_autodeploy.csr -keyout c:\certs\AutoDeploy\rui_autodeploy.key -config c:\certs\AutoDeploy\openssl_autodeploy.cfg
After running these commands, you now have the
rui_service.csr and
rui_service.key files located in each respective directory.
When the certificate requests are created, proceed to the
Getting the certificates section.
Getting the certificates
After the certificate requests are generated, they must be given to the certificate authority for generation of the actual certificate. The authority responds with a signed certificate and, if appropriate, a copy of their root certificate. For the certificate chain to be trusted, the root certificate must be installed on the server which is requesting the certificate.
Follow the appropriate section for the certificate authority used.
If you are using commercial non-Microsoft CAs:
- Take each certificate signing request (
rui.csr, as generated above) and send them to the commercial certificate signing authority.
- The CA sends back the generated certificates and the certificate chain file (normally a
.PEM file) to ensure that the certificates are trusted.
- Proceed to the Installation and configuration of the certificates section of this article to complete the configuration of the custom certificates.
If you are using a Microsoft CA:
Note: Before proceeding, confirm that the three key usages are present on the .crt file by viewing its properties. This can be found by opening the rui.crt, clicking the Details tab, and locating the Key Usage row under Field. The default install of Windows Server 2008 with the CA role will not create *.crt files. You must first modify the digitalSignature, keyEncipherment, and dataEncipherment fields on the CA server's Web Server template before continuing.
- Log in to the Microsoft CA certificate authority web interface. By default, it is:
http://servername/CertSrv/
- Click the Request a certificate link.
- Click advanced certificate request.
- Click the Submit a certificate request by using a base-64-encoded CMC or PKCS #10 file, or submit a renewal request by using a base-64-encoded PKCS #7 file link.
- Open the certificate request (
rui_service.csr, as generated above for each component) in a plain text editor and paste this text into the Saved Request box:
-----BEGIN CERTIFICATE REQUEST----- to -----END CERTIFICATE REQUEST-----
- Select the Certificate Template as Web Server.
Note: VMware recommends that you create a copy of the Web Server Certificate and add the Subject Alternative Name field to it. This allows you to specify more than a single name to be valid on the certificate, such as vcenter.domain.com and vcenter. Users can connect to more than one name and communication will still be valid.
For more information on creating a Certificate Template, see Creating a Microsoft Certificate Authority Template for SSL certificate creation in vSphere 5.x (2062108).
- Click Submit to submit the request.
- Click Base 64 encoded on the Certificate issued screen.
- Click the Download Certificate link.
- Save the certificate as
rui_service.crt, in the appropriate c:\certs\<service>\ folder.
For example:
rui_vpxd.crt
Note:
- By default, Microsoft CA certificates are generated with the
.cer format. Either use Save As or change it to .crt before continuing with this procedure.
- Repeat Steps 2 to 10 for each of the additional service.
- Navigate back to the home page of the certificate server and click Download a CA certificate, certificate chain or CRL.
- Click the Base 64 option.
- Click the Download CA Certificate chain link.
- Save the certificate chain as
cachain.p7b in the c:\certs\ directory.
When complete, you have four certificates (
rui_service.crt) for each of the services and the either the
cachain.pem (for non-Microsoft CA providers) or the
cachain.p7b (if the certificates are generated using a Microsoft CA) file generated in their respective
c:\certs\<services> folders. Proceed to the
Installation and configuration of the certificates section to complete the configuration of the custom certificates.
Installation and configuration of the certificates for all the components
After the certificates are created, you must validate that the certificates are in the proper format. Edit the certificate with a tool such as
Notepador
vi and validate that the file begins with
-----BEGIN CERTIFICATE-----. Remove all text before the
-----BEGIN CERTIFICATE----- in the
rui.crt files.
To complete the installation and configuration of the certificates in the vCenter Server Appliance:
Note: Before proceeding, ensure you back up the existing
rui.crt,
rui.key, and
rui.pfx files.If you plan to skip the replacement of certificates for any of the components, such as vSphere Auto Deploy, you must restart the vCenter Server Appliance after the last certificate is replaced/services restarted
- Connect to the vCenter Server Appliance via SSH.
- Stop the VMware VirtualCenter Server service and the vCenter Single Sign-On service using these commands:
service vmware-stsd stop
service vmware-vpxd stop
- Create a directory using the
mkdir command to store the files. This article uses directories named /ssl/service on the vCenter Server Appliance for the file operations. Be sure to create the appropriate directories as you proceed through the article. Use these models as examples:
mkdir ssl
mkdir ssl/vpxd
mkdir ssl/inventoryservice
mkdir ssl/logbrowser
mkdir ssl/autodeploy
- Using WinSCP from the system you created all of the SSL certificates on, copy
rui_vpxd.crt, rui_vpxd.key, and cachain.p7b file from c:\certs\vCenterSSO to the /ssl/vpxd directory on the vCenter Server Appliance.
Note: In this step, ignore the cachain.p7b file if the certificate is obtained using a non-Microsoft CA..
- Rename
rui_vpxd.crt to rui.crt by running the command:
cp ssl/vpxd/rui_vpxd.crt ssl/vpxd/rui.crt
- Rename
rui_vpxd.key to rui.key by running the command:
cp ssl/vpxd/rui_vpxd.key ssl/vpxd/rui.key
- From the vCenter Server Appliance, run the following commands to convert the
cachain.p7b file to chain.pem:
cd ssl/vpxd/
openssl pkcs7 -print_certs -in cachain.p7b -out cachain.pem
Note: This step can be ignored if the certificate is obtained using a non-Microsoft CA..
- Open the cachain.pem file with VI editor. For more information, see Editing files on an ESX host using vi or nano (1020302).
- Using VI editor, remove any text before the first "
-----BEGIN CERTIFICATE-----" and after "-----END CERTIFICATE-----".
Note: This assumes there are no intermediate certificates in the Certificate Authority. If you are using two or more levels in the Certificate Authorities, remove any text in between the -----END CERTIFICATE----- of the intermediate thumbprint and -----BEGIN CERTIFICATE----- of the Root CA thumbprint. Before editing, review the chain.pem file to ensure all intermediates and the Root CA server thumbprints are present. If the file does not contain the authority certificate, obtain it from the Certification Authority and append it manually.
This should result in a concatenated file similar to the model below:
-----BEGIN CERTIFICATE-----
Thumbprint Intermediate(n) CA Server
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Thumbprint Intermediate(2) CA Server
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Thumbprint Intermediate(1) CA Server
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Thumbprint Root CA Server
-----END CERTIFICATE-----
- Create the chain.pem file for vCenter Server service by running the commands:
cat rui.crt cachain.pem > chain.pem
- Replace the SSL certs by running the command:
/usr/sbin/vpxd_servicecfg certificate change chain.pem rui.key
Wait until you receive this response:
VC_CFG_RESULT = 0
Note: The command prints the outcome code using this syntax:
VC_CFG_RESULT=CODE
Status code 0 means success. For details on all possible error conditions, see Decoding non-zero VC_CFG_RESULT for failed vpxd_servicecfg certificate changes (2057248).
- Ensure the vCenter Single Sign-On service is started before continuing by running the command:
service vmware-stsd start
- Unregister the vCenter Inventory Service from vCenter Single Sign-On by running the commands:
cd /etc/vmware-sso/register-hooks.d
./02-inventoryservice --mode uninstall --ls-server https://server.domain.com:7444/lookupservice/sdk
- Using WinSCP from the system you created all of the SSL certificates on, copy
rui_inventoryservice.crtand rui_inventoryservice.key from c:\certs\InventoryService to the /ssl/inventoryservice directory on the vCenter Server Appliance.
- Copy the edited cachain.pem file from Step 9 to the
/ssl/inventoryservice directory using the following command:
cd
cp ssl/vpxd/cachain.pem ssl/inventoryservice/
- Rename
rui_inventoryservice.crt to rui.crt by running the command:
cp ssl/inventoryservice/rui_inventoryservice.crt ssl/inventoryservice/rui.crt
- Rename
rui_inventoryservice.key to rui.key by running the command:
cp ssl/inventoryservice/rui_inventoryservice.key ssl/inventoryservice/rui.key
- Create the chain.pem file for vCenter Inventory Service by running the commands:
cd ssl/inventoryservice
cat rui.crt cachain.pem > chain.pem
- Create the
*.pfx file by running the command:
openssl pkcs12 -export -out rui.pfx -in chain.pem -inkey rui.key -name rui -passout pass:testpassword
- Copy the
rui.key, rui.crt, and rui.pfx files to the /usr/lib/vmware-vpx/inventoryservice/ssl directory:
cp rui.key /usr/lib/vmware-vpx/inventoryservice/ssl
cp rui.crt /usr/lib/vmware-vpx/inventoryservice/ssl
cp rui.pfx /usr/lib/vmware-vpx/inventoryservice/ssl
- Change the permissions on these files by running these commands:
cd /usr/lib/vmware-vpx/inventoryservice/ssl/
chmod 400 rui.key rui.pfx
chmod 644 rui.crt
- Run these commands to register the vCenter Inventory Service back to vCenter Single Sign-On:
cd /etc/vmware-sso/register-hooks.d
./02-inventoryservice --mode install --ls-server https://server.domain.com:7444/lookupservice/sdk --usersso_administrator --password sso_administrator_password
Note: If $ character is present in the password, add an / character in front of it:
For example, when use Pa$sw0rd as password:
./02-inventoryservice --mode install --ls-server https://server.domain.com:7444/lookupservice/sdk --user administrator@vsphere.local --password Pa/$sw0rd
Note: As there is a plain-text password on the above command, to avoid the history file showing the contents of the password because it is in plain text in the command above, run the unset HISTFILE command prior to executing step 22.
Note: The default SSO administrator username for vCenter Single Sign-On 5.5 is administrator@vSphere.local
After a successful registration, you see output similar to:
- To re-register the vCenter Inventory Service to vCenter Server the next time the service starts, run this command:
rm /var/vmware/vpxd/inventoryservice_registered
- Run these commands to restart and register the service:
service vmware-inventoryservice stop
service vmware-vpxd stop
service vmware-inventoryservice start
service vmware-vpxd start
- Unregister the VMware Log Browser service from vCenter Single Sign-On by running the commands:
cd /etc/vmware-sso/register-hooks.d
./09-vmware-logbrowser --mode uninstall --ls-server https://server.domain.com:7444/lookupservice/sdk
- Using WinSCP from the system you created all of the SSL certificates on, copy the
rui_logbrowser.crt,rui_logbrowser.key from c:\certs\LogBrowser to the /ssl/logbrowser directory on the vCenter Server Appliance
- Copy the edited cachain.pem file from Step 9 to the /ssl/logbrowser directory using the following commands:
cd
cp ssl/vpxd/cachain.pem ssl/logbrowser
- Rename
rui_logbrowser.crt to rui.crt by running the command:
cp ssl/logbrowser/rui_logbrowser.crt ssl/logbrowser/rui.crt
- Rename
rui_logbrowser.key to rui.key by running the command:
cp ssl/logbrowser/rui_logbrowser.key ssl/logbrowser/rui.key
- Create the chain.pem file for VMware Log Browser Service by running the commands:
cd ssl/logbrowser
cat rui.crt cachain.pem > chain.pem
- Create the
*.pfx file by running the command:
openssl pkcs12 -export -in rui.crt -inkey rui.key -name rui -passout pass:testpassword -out rui.pfx
- Copy
rui.key, rui.crt, and rui.pfx files to the /usr/lib/vmware-logbrowser/conf directory:
cp rui.key /usr/lib/vmware-logbrowser/conf
cp rui.crt /usr/lib/vmware-logbrowser/conf
cp rui.pfx /usr/lib/vmware-logbrowser/conf
- Change the permissions on the files by running these commands:
cd /usr/lib/vmware-logbrowser/conf
chmod 400 rui.key rui.pfx
chmod 644 rui.crt
- Run these commands to re-register the VMware Log Browser service to vCenter Single Sign-On:
cd /etc/vmware-sso/register-hooks.d
./09-vmware-logbrowser --mode install --ls-server https://server.domain.com:7444/lookupservice/sdk --usersso_administrator --password sso_administrator_password
Note: The default SSO administrator username for vCenter Single Sign-On 5.5 is administrator@vSphere.local
A successful registration will output the following:
- When complete, restart the Log Browser service by running the commands:
service vmware-logbrowser stop
service vmware-logbrowser start
Note: If you plan to skip the replacement of certificates for any of the components, such as vSphere Auto Deploy, you must restart the vCenter Server Appliance after the last certificate is replaced/services restarted. Proceed to step 40.
- Using WinSCP from the system you created all of the SSL certificates on, copy the
rui_autodeploy.crtand rui_autodeploy.key from c:\certs\AutoDeploy to the /ssl/autodeploy directory on the vCenter Server Appliance.
- Copy the
rui_autodeploy.crt and rui_autodeploy.key to the /etc/vmware-vpx/ssl/ directory:
cp ssl/autodeploy/rui_autodeploy.crt /etc/vmware-rbd/ssl/waiter.crt
cp ssl/autodeploy/rui_autodeploy.key /etc/vmware-rbd/ssl/waiter.key
- Change the permissions and ownership on the waiter files by running these commands:
cd /etc/vmware-rbd/ssl/
chmod 644 waiter.crt
chmod 400 waiter.key
chown deploy:deploy waiter.crt waiter.key
- Re-register the service to the vCenter Server with the commands:
service vmware-rbd-watchdog stop
rm /var/vmware/vpxd/autodeploy_registered
service vmware-vpxd restart
Note: autodeploy_registered may not exist.
- Restart the vCenter Server Appliance. For more information, see Stopping, starting, or restarting vCenter Server Appliance services (2054085).