Make VMCA Into an Intermediate Certificate Authority Using the CLI

You can use the CLI to replace the VMCA root certificate with a third-party CA-signed certificate that includes VMCA in the certificate chain. Going forward, all certificates that VMCA generates include the full chain. You can replace existing certificates with newly generated certificates.

If you use VMCA as an intermediate CA, or use custom certificates, you might encounter significant complexity and the potential for a negative impact to your security, and an unnecessary increase in your operational risk. For more information about managing certificates within a vSphere environment, see the blog post titled New Product Walkthrough - Hybrid vSphere SSL Certificate Replacement at http://vmware.com/go/hybridvmca.

Replace the Root Certificate (Intermediate CA) Using the CLI

The first step in replacing the VMCA certificates with custom certificates is generating a CSR, and sending the CSR to be signed. You then use the CLI to add the signed certificate to VMCA as a root certificate.

You can use the Certificate Manager utility or other tool to generate the CSR. The CSR must meet the following requirements:

Key size: 2048 bits (minimum) to 8192 bits (maximum) (PEM encoded)
PEM format. VMware supports PKCS8 and PKCS1 (RSA keys). When keys are added to VECS, they are converted to PKCS8.
x509 version 3
The CA extension must be set to true for root certificates, and cert sign must be in the list of requirements. For example:
```
basicConstraints        = critical,CA:true
keyUsage                = critical,digitalSignature,keyCertSign
```
CRL signing must be enabled.
Extended Key Usage can be either empty or contain Server Authentication.
No explicit limit to the length of the certificate chain. VMCA uses the OpenSSL default, which is 10 certificates.
Certificates with wildcards or with more than one DNS name are not supported.
You cannot create subsidiary CAs of VMCA.
See the VMware knowledge base article at https://kb.vmware.com/s/article/2112009, Creating a Microsoft Certificate Authority Template for SSL certificate creation in vSphere 6.x, for an example using Microsoft Certificate Authority.

Note: vSphere's FIPS certificate only validates RSA key sizes of 2048 bits and 3072 bits.

VMCA validates the following certificate attributes when you replace the root certificate:

Key size: 2048 bits (minimum) to 8192 bits (maximum).
Key Usage: Cert Sign
Basic Constraint: Subject Type CA

Procedure

Generate a CSR and send it to your CA.
Follow your CA's instructions.
Prepare a certificate file that includes the signed VMCA certificate and the full CA chain of your third-party CA or enterprise CA. Save the file, for example as rootca1.crt.
You can accomplish this step by copying all CA certificates in PEM format into a single file. You start with the VMCA root certificate and end up with the root CA PEM certificate. For example:
```
-----BEGIN CERTIFICATE-----
<Certificate of VMCA>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Certificate of intermediary CA>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Certificate of Root CA>
-----END CERTIFICATE-----
```

Stop all services and start the services that handle certificate creation, propagation, and storage.

service-control --stop --all
service-control --start vmafdd
service-control --start vmdird
service-control --start vmcad

Replace the existing VMCA root CA.
```
certool --rootca --cert=rootca1.crt --privkey=root1.key
```
When you run this command, it:
- Adds the new custom root certificate to the certificate location in the file system.
- Appends the custom root certificate to the TRUSTED_ROOTS store in VECS (after a delay).
- Adds the custom root certificate to vmdir (after a delay).
(Optional) To propagate the change to all instances of vmdir (VMware Directory Service), publish the new root certificate to vmdir, supplying the full file path for each file.
For example, if the certificate has only one certificate in the chain:
```
dir-cli trustedcert publish --cert rootca1.crt
```
If the certificate has more than one certificate in the chain:
```
dir-cli trustedcert publish --cert rootcal.crt --chain
```
Replication between vmdir nodes happens every 30 seconds. You do not have to add the root certificate to VECS explicitly because VECS polls vmdir for new root certificate files every 5 minutes.
(Optional) If necessary, you can force a refresh of VECS.
```
vecs-cli force-refresh
```
Restart all services.
```
service-control --start --all
```

Example: Replacing the Root Certificate

Replace the VMCA root certificate with the custom CA root certificate using the certool command with the --rootca option.

/usr/lib/vmware-vmca/bin/certool --rootca --cert=<path>/root.pem -–privkey=<path>/root.key

When you run this command, it:

Adds the new custom root certificate to the certificate location in the file system.
Appends the custom root certificate to the TRUSTED_ROOTS store in VECS.
Adds the custom root certificate to vmdir.

What to do next

You can remove the original VMCA root certificate from the certificate store if your company policy requires it. If you do, you have to replace the vCenter Single Sign-On Signing certificate. See Replace a vCenter Server STS Certificate Using the Command Line.

Replace Machine SSL Certificates (Intermediate CA) Using the CLI

After you have received the signed certificate from the CA, you can use the CLI to make it the VMCA root certificate and replace all machine SSL certificates.

These steps are essentially the same as the steps for replacing with a certificate that uses VMCA as the certificate authority. However, in this case, VMCA signs all certificates with the full chain.

Each machine must have a machine SSL certificate for secure communication with other services. When multiple vCenter Server instances are connected in Enhanced Linked Mode configuration, you must run the Machine SSL certificate generation commands on each node.

Prerequisites

For each machine SSL certificate, the SubjectAltName must contain DNS Name=<Machine FQDN>.

Procedure

Make one copy of certool.cfg for each machine that needs a new certificate.
The certool.cfg file is located in the /usr/lib/vmware-vmca/share/config/ directory.
Edit the custom configuration file for each machine to include that machine's FQDN.
Run NSLookup against the machine’s IP address to see the DNS listing of the name, and use that name for the Hostname field in the file.

Generate a public/private key file pair and a certificate for each machine, passing in the configuration file that you just customized.

For example:

certool --genkey --privkey=machine1.priv --pubkey=machine1.pub
certool --gencert --privkey=machine1.priv --cert machine42.crt --Name=Machine42_Cert --config machine1.cfg

Stop all services and start the services that handle certificate creation, propagation, and storage.

service-control --stop --all
service-control --start vmafdd
service-control --start vmdird
service-control --start vmcad

Add the new certificate to VECS.
All machines need the new certificate in the local certificate store to communicate over SSL. You first delete the existing entry, then add the new entry.
```
vecs-cli entry delete --store MACHINE_SSL_CERT --alias __MACHINE_CERT  
vecs-cli entry create --store MACHINE_SSL_CERT --alias __MACHINE_CERT --cert machine1.cert
--key machine1.priv
```
Restart all services.
```
service-control --start --all
```

Example: Replacing Machine SSL Certificates (VMCA Is Intermediate CA)

Create a configuration file for the SSL certificate and save it as ssl-config.cfg in the current directory.

Country = US
Name = vmca-<FQDN-example>
Organization = VMware
OrgUnit = VMware Engineering
State = California 
Locality = Palo Alto
Hostname = <FQDN>

Generate a key pair for the machine SSL certificate. In a deployment of multiple vCenter Server instances connected in Enhanced Linked Mode configuration, run this command on each vCenter Server node.
```
/usr/lib/vmware-vmca/bin/certool --genkey --privkey=ssl-key.priv --pubkey=ssl-key.pub
```
The ssl-key.priv and ssl-key.pub files are created in the current directory.
Generate the new machine SSL certificate. This certificate is signed by VMCA. If you replaced the VMCA root certificate with custom certificate, VMCA signs all certificates with the full chain.
```
/usr/lib/vmware-vmca/bin/certool --gencert --cert=new-vmca-ssl.crt --privkey=ssl-key.priv --config=ssl-config.cfg
```
The new-vmca-ssl.crt file is created in the current directory.

(Optional) List the content of VECS.

/usr/lib/vmware-vmafd/bin/vecs-cli store list

Sample output on vCenter Server:

output (on vCenter):
MACHINE_SSL_CERT
TRUSTED_ROOTS
TRUSTED_ROOT_CRLS
machine
vsphere-webclient
vpxd
vpxd-extension
hvc
data-encipherment
APPLMGMT_PASSWORD
SMS
wcp
KMS_ENCRYPTION

Replace the Machine SSL certificate in VECS with the new Machine SSL certificate. The --store and --alias values have to exactly match with the default names.
- On each vCenter Server, run the following commands to update the Machine SSL certificate in the MACHINE_SSL_CERT store. You must update the certificate for each machine separately because each has a different FQDN.
```
/usr/lib/vmware-vmafd/bin/vecs-cli entry delete --store MACHINE_SSL_CERT --alias __MACHINE_CERT
/usr/lib/vmware-vmafd/bin/vecs-cli entry create --store MACHINE_SSL_CERT --alias __MACHINE_CERT --cert new-vmca-ssl.crt --key ssl-key.priv
```

Replace Solution User Certificates (Intermediate CA) Using the CLI

After you replace the machine SSL certificates, you can use the CLI to replace the solution user certificates.

Many VMware customers do not replace solution user certificates. They replace only the machine SSL certificates with custom certificates. This hybrid approach satisfies the requirements of their security teams.

Certificates either sit behind a proxy, or they are custom certificates.
No intermediate CAs are used.

You replace the machine solution user certificate and the solution user certificate on each vCenter Server system.

Note: When you list solution user certificates in large deployments, the output of /usr/lib/vmware-vmafd/bin/dir-cli list includes all solution users from all nodes. Run /usr/lib/vmware-vmafd/bin/vmafd-cli get-machine-id --server-name localhost to find the local machine ID for each host. Each solution user name includes the machine ID.

Prerequisites

Each solution user certificate must have a different Subject. Consider, for example, including the solution user name (such as vpxd) or other unique identifier.

Procedure

Make one copy of certool.cfg, remove the Name, IP address, DNS name, and email fields, and rename the file, for example, to sol_usr.cfg.
You can name the certificates from the command line as part of generation. The other information is not needed for solution users. If you leave the default information, the certificates that are generated are potentially confusing.
Generate a public/private key file pair and a certificate for each solution user, passing in the configuration file that you just customized.
For example:
```
certool --genkey --privkey=vpxd.priv --pubkey=vpxd.pub
certool --gencert --privkey=vpxd.priv --cert vpxd.crt --Name=VPXD_1 --config sol_usr.cfg
```
Find the name for each solution user.
```
/usr/lib/vmware-vmafd/bin/dir-cli service list 
```
You can use the unique ID that is returned when you replace the certificates. The input and output might look as follows.
```
/usr/lib/vmware-vmafd/bin/dir-cli service list
Enter password for administrator@vsphere.local:
1. machine-623bef28-0311-436e-b21f-6e0d39aa5179
2. vsphere-webclient-623bef28-0311-436e-b21f-6e0d39aa5179
3. vpxd-623bef28-0311-436e-b21f-6e0d39aa5179
4. vpxd-extension-623bef28-0311-436e-b21f-6e0d39aa5179
5. hvc-623bef28-0311-436e-b21f-6e0d39aa5179
6. wcp-1cbe0a40-e4ce-4378-b5e7-9460e2b8200e
```
In a deployment of multiple vCenter Server instances connected in Enhanced Linked Mode configuration, the output of /usr/lib/vmware-vmafd/bin/dir-cli service list includes all solution users from all nodes. Run /usr/lib/vmware-vmafd/bin/vmafd-cli get-machine-id --server-name localhost to find the local machine ID for each host. Each solution user name includes the machine ID.

Stop all services and start the services that handle certificate creation, propagation, and storage.

service-control --stop --all
service-control --start vmafdd
service-control --start vmdird
service-control --start vmcad

Replace the existing certificate in vmdir and then in VECS.
For solution users, you must add the certificates in that order. For example:
```
dir-cli service update --name <vpxd-xxxx-xxx-7c7b769cd9f4> --cert ./vpxd.crt
vecs-cli entry delete --store vpxd --alias vpxd
vecs-cli entry create --store vpxd --alias vpxd --cert vpxd.crt --key vpxd.priv
```
Note: Solution users cannot log in to vCenter Single Sign-On if you do not replace the certificate in vmdir.
Restart all services.
```
service-control --start --all
```

Example: Replacing Solution User Certificates (Intermediate CA)

Generate a public/private key pair for each solution user on each vCenter Server node in an Enhanced Linked Mode configuration. That includes a pair for the machine solution and a pair for each additional solution user (vpxd, vpxd-extension, vsphere-webclient, wcp).
1. Generate a key pair for the machine solution user.
```
/usr/lib/vmware-vmca/bin/certool --genkey --privkey=machine-key.priv --pubkey=machine-key.pub
```
2. Generate a key pair for the vpxd solution user on each node.
```
/usr/lib/vmware-vmca/bin/certool --genkey --privkey=vpxd-key.priv --pubkey=vpxd-key.pub
```
3. Generate a key pair for the vpxd-extension solution user on each node.
```
/usr/lib/vmware-vmca/bin/certool --genkey --privkey=vpxd-extension-key.priv --pubkey=vpxd-extension-key.pub
```
4. Generate a key pair for the vsphere-webclient solution user on each node.
```
/usr/lib/vmware-vmca/bin/certool --genkey --privkey=vsphere-webclient-key.priv --pubkey=vsphere-webclient-key.pub
```
5. Generate a key pair for the wcp solution user on each node.
```
/usr/lib/vmware-vmca/bin/certool --genkey --privkey=wcp-key.priv --pubkey=wcp-key.pub
```
Generate solution user certificates that are signed by the new VMCA root certificate for the machine solution user and for each additional solution user (vpxd, vpxd-extension, vsphere-webclient, wcp) on each vCenter Server node.
Note: The --Name parameter has to be unique. Including the name of the solution user store name makes it easy to see which certificate maps to which solution user. The example includes the name, for example vpxd or vpxd-extension in each case.
1. Make one copy of the /usr/lib/vmware-vmca/share/config/certool.cfg file, then modify or remove the Name, IP address, DNS name, and email fields as required, and rename the file, for example, to sol_usr.cfg.
2. Generate a certificate for the machine solution user on each node.
```
/usr/lib/vmware-vmca/bin/certool --gencert --cert=new-machine.crt --privkey=machine-key.priv --Name=machine --config sol_usr.cfg
```
3. Generate a certificate for the vpxd solution user on each node.
```
/usr/lib/vmware-vmca/bin/certool --gencert --cert=new-vpxd.crt --privkey=vpxd-key.priv --Name=vpxd --config sol_usr.cfg
```
4. Generate a certificate for the vpxd-extensions solution user on each node.
```
/usr/lib/vmware-vmca/bin/certool --gencert --cert=new-vpxd-extension.crt --privkey=vpxd-extension-key.priv --Name=vpxd-extension --config sol_usr.cfg
```
5. Generate a certificate for the vsphere-webclient solution user on each node by running the following command.
```
/usr/lib/vmware-vmca/bin/certool --gencert --cert=new-vsphere-webclient.crt --privkey=vsphere-webclient-key.priv --Name=vsphere-webclient --config sol_usr.cfg
```
6. Generate a certificate for the wcp solution user on each node by running the following command.
```
/usr/lib/vmware-vmca/bin/certool --gencert --cert=new-wcp.crt --privkey=wcp-key.priv --Name=wcp --config sol_usr.cfg
```

Replace the solution user certificates in VECS with the new solution user certificates.

Note: The --store and --alias parameters have to exactly match the default names for services.

Replace the machine solution user certificate on each node:

/usr/lib/vmware-vmafd/bin/vecs-cli entry delete --store machine --alias machine
/usr/lib/vmware-vmafd/bin/vecs-cli entry create --store machine --alias machine --cert new-machine.crt --key machine-key.priv

Replace the vpxd solution user certificate on each node.

/usr/lib/vmware-vmafd/bin/vecs-cli entry delete --store vpxd --alias vpxd
/usr/lib/vmware-vmafd/bin/vecs-cli entry create --store vpxd --alias vpxd --cert new-vpxd.crt --key vpxd-key.priv

Replace the vpxd-extension solution user certificate on each node.

/usr/lib/vmware-vmafd/bin/vecs-cli entry delete --store vpxd-extension --alias vpxd-extension
/usr/lib/vmware-vmafd/bin/vecs-cli entry create --store vpxd-extension --alias vpxd-extension --cert new-vpxd-extension.crt --key vpxd-extension-key.priv

Replace the vsphere-webclient solution user certificate on each node.

/usr/lib/vmware-vmafd/bin/vecs-cli entry delete --store vsphere-webclient --alias vsphere-webclient
/usr/lib/vmware-vmafd/bin/vecs-cli entry create --store vsphere-webclient --alias vsphere-webclient --cert new-vsphere-webclient.crt --key vsphere-webclient-key.priv

Replace the wcp solution user certificate on each node.

/usr/lib/vmware-vmafd/bin/vecs-cli entry delete --store wcp --alias wcp
/usr/lib/vmware-vmafd/bin/vecs-cli entry create --store wcp --alias wcp --cert new-wcp.crt --key wcp-key.priv

Update VMware Directory Service (vmdir) with the new solution user certificates. You are prompted for a vCenter Single Sign-On administrator password.
1. Run /usr/lib/vmware-vmafd/bin/dir-cli service list to get the unique service ID suffix for each solution user. You run this command on a vCenter Server system.
```
/usr/lib/vmware-vmafd/bin/dir-cli service list
output:
1. machine-623bef28-0311-436e-b21f-6e0d39aa5179
2. vsphere-webclient-623bef28-0311-436e-b21f-6e0d39aa5179
3. vpxd-623bef28-0311-436e-b21f-6e0d39aa5179
4. vpxd-extension-623bef28-0311-436e-b21f-6e0d39aa5179
5. hvc-623bef28-0311-436e-b21f-6e0d39aa5179
6. wcp-1cbe0a40-e4ce-4378-b5e7-9460e2b8200e
```
  Note: When you list solution user certificates in large deployments, the output of /usr/lib/vmware-vmafd/bin/dir-cli list includes all solution users from all nodes. Run /usr/lib/vmware-vmafd/bin/vmafd-cli get-machine-id --server-name localhost to find the local machine ID for each host. Each solution user name includes the machine ID.
2. Replace the machine certificate in vmdir on each vCenter Server node. For example, if machine-6fd7f140-60a9-11e4-9e28-005056895a69 is the machine solution user on the vCenter Server, run this command:
```
/usr/lib/vmware-vmafd/bin/dir-cli service update --name machine-6fd7f140-60a9-11e4-9e28-005056895a69 --cert new-machine.crt
```
3. Replace the vpxd solution user certificate in vmdir on each node. For example, if vpxd-6fd7f140-60a9-11e4-9e28-005056895a69 is the vpxd solution user ID, run this command:
```
/usr/lib/vmware-vmafd/bin/dir-cli service update --name vpxd-6fd7f140-60a9-11e4-9e28-005056895a69 --cert new-vpxd.crt
```
4. Replace the vpxd-extension solution user certificate in vmdir on each node. For example, if vpxd-extension-6fd7f140-60a9-11e4-9e28-005056895a69 is the vpxd-extension solution user ID, run this command:
```
/usr/lib/vmware-vmafd/bin/dir-cli service update --name vpxd-extension-6fd7f140-60a9-11e4-9e28-005056895a69 --cert new-vpxd-extension.crt
```
5. Replace the vsphere-webclient solution user certificate on each node. For example, if vsphere-webclient-6fd7f140-60a9-11e4-9e28-005056895a69 is the vsphere-webclient solution user ID, run this command:
```
/usr/lib/vmware-vmafd/bin/dir-cli service update --name vsphere-webclient-6fd7f140-60a9-11e4-9e28-005056895a69 --cert new-vsphere-webclient.crt
```
6. Replace the wcp solution user certificate on each node. For example, if wcp-1cbe0a40-e4ce-4378-b5e7-9460e2b8200e is the wcp solution user ID, run this command:
```
/usr/lib/vmware-vmafd/bin/dir-cli service update --name wcp-1cbe0a40-e4ce-4378-b5e7-9460e2b8200e --cert new-wcp.crt
```