The vecs-cli command set allows you to manage instances of VMware Certificate Store (VECS). Use these commands together with dir-cli and certool to manage your certificate infrastructure and other Platform Services Controller services.

vecs-cli store create

Creates a certificate store.

Option Description
--name <name> Name of the certificate store.

--server <server-name>

Used to specify a server name if you connect to a remote VECS instance.

--upn <user-name>

User Principle Name that is used to log in to the server instance specified by --server <server-name> . When you create a store, it is created in the context of the current user. Therefore, the owner of the store is the current user context and not always the root user.

Example:
vecs-cli store create --name <store>

vecs-cli store delete

Deletes a certificate store. You cannot delete the MACHINE_SSL_CERT, TRUSTED_ROOTS and TRUSTED_ROOT_CRLS system stores. Users with required privileges can delete solution user stores.

Option Description
--name <name> Name of the certificate store to delete.

--server <server-name>

Used to specify a server name if you connect to a remote VECS instance.

--upn <user-name>

User Principle Name that is used to log in to the server instance specified by --server <server-name> . When you create a store, it is created in the context of the current user. Therefore, the owner of the store is the current user context and not always the root user.

Example:
vecs-cli store delete --name <store>

vecs-cli store list

List certificate stores.

Option Description

--server <server-name>

Used to specify a server name if you connect to a remote VECS instance.

--upn <user-name>

User Principle Name that is used to log in to the server instance specified by --server <server-name> . When you create a store, it is created in the context of the current user. Therefore, the owner of the store is the current user context and not always the root user.

VECS includes the following stores.
Table 1. Stores in VECS
Store Description
Machine SSL store (MACHINE_SSL_CERT)
  • Used by the reverse proxy service on every vSphere node.
  • Used by the VMware Directory Service (vmdir) on embedded deployments and on each Platform Services Controller node.

All services in vSphere 6.0 and later communicate through a reverse proxy, which uses the machine SSL certificate. For backward compatibility, the 5.x services still use specific ports. As a result, some services such as vpxd still have their own port open.

Trusted root store (TRUSTED_ROOTS) Contains all trusted root certificates.
Solution user stores
  • machine
  • vpxd
  • vpxd-extension
  • vsphere-webclient
VECS includes one store for each solution user. The subject of each solution user certificate must be unique, for example, the machine certificate cannot have the same subject as the vpxd certificate.

Solution user certificates are used for authentication with vCenter Single Sign-On. vCenter Single Sign-On checks that the certificate is valid, but does not check other certificate attributes. In an embedded deployment, all solution user certificates are on the same system.

The following solution user certificate stores are included in VECS on each management node and each embedded deployment:

  • machine: Used by the license server and the logging service.
    Note: The machine solution user certificate has nothing to do with the machine SSL certificate. The machine solution user certificate is used for the SAML token exchange. The machine SSL certificate is used for secure SSL connections for a machine.
  • vpxd: vCenter service daemon (vpxd) store on management nodes and embedded deployments. vpxd uses the solution user certificate that is stored in this store to authenticate to vCenter Single Sign-On.
  • vpxd-extension: vCenter extensions store. Includes the Auto Deploy service, inventory service, and other services that are not part of other solution users.
  • vsphere-webclient: vSphere Web Client store. Also includes some additional services such as the performance chart service.

Each Platform Services Controller node includes a machine certificate.

vSphere Certificate Manager Utility backup store (BACKUP_STORE) Used by VMCA (VMware Certificate Manager) to support certificate revert. Only the most recent state is stored as a backup, you cannot go back more than one step.
Other stores Other stores might be added by solutions. For example, the Virtual Volumes solution adds an SMS store. Do not modify the certificates in those stores unless VMware documentation or a VMware Knowledge Base article instructs you to do so.
Note: Deleting the TRUSTED_ROOTS_CRLS store can damage your certificate infrastructure. Do not delete or modify the TRUSTED_ROOTS_CRLS store.
Example:
vecs-cli store list

vecs-cli store permissions

Grants or revokes permissions to the store. Use either the --grant or the --revoke option.

The owner of the store can perform all operations, including granting and revoking permissions. The administrator of the local vCenter Single Sign-On domain, [email protected] by default, has all privileges on all stores, including granting and revoking permissions.

You can use vecs-cli get-permissions --name <store-name> to retrieve the current settings for the store.

Option Description
--name <name> Name of the certificate store.
--user <username> Unique name of the user who is granted permissions.
--grant [read|write] Permission to grant, either read or write.
--revoke [read|write] Permission to revoke, either read or write. Not currently supported.

vecs-cli store get-permissions

Retrieves the current permission settings for the store.

Option Description
--name <name> Name of the certificate store.

--server <server-name>

Used to specify a server name if you connect to a remote VECS instance.

--upn <user-name>

User Principle Name that is used to log in to the server instance specified by --server <server-name> . When you create a store, it is created in the context of the current user. Therefore, the owner of the store is the current user context and not always the root user.

vecs-cli entry create

Creates an entry in VECS. Use this command to add a private key or certificate to a store.

Option Description

--store <NameOfStore>

Name of the certificate store.

--alias <Alias> Optional alias for the certificate. This option is ignored for the trusted root store.
--cert <certificate_file_path> Full path of the certificate file.
--key <key-file-path>

Full path of the key that corresponds to the certificate.

Optional.
--password <password> Optional password for encrypting the private key.

--server <server-name>

Used to specify a server name if you connect to a remote VECS instance.

--upn <user-name>

User Principle Name that is used to log in to the server instance specified by --server <server-name> . When you create a store, it is created in the context of the current user. Therefore, the owner of the store is the current user context and not always the root user.

vecs-cli entry list

Lists all entries in a specified store.

Option Description
--store <NameOfStore>

Name of the certificate store.

vecs-cli entry getcert

Retrieves a certificate from VECS. You can send the certificate to an output file or display it as human-readable text.

Option Description
--store <NameOfStore>

Name of the certificate store.

--alias <Alias> Alias of the certificate.
--output <output_file_path> File to write the certificate to.
--text Displays a human-readable version of the certificate.

--server <server-name>

Used to specify a server name if you connect to a remote VECS instance.

--upn <user-name>

User Principle Name that is used to log in to the server instance specified by --server <server-name> . When you create a store, it is created in the context of the current user. Therefore, the owner of the store is the current user context and not always the root user.

vecs-cli entry getkey

Retrieves a key that is stored in VECS. You can send the key to an output file or display it as human-readable text.

Option Description
--store <NameOfStore>

Name of the certificate store.

--alias <Alias> Alias for the key.
--output <output_file_path> Output file to write the key to.
--text Displays a human-readable version of the key.

--server <server-name>

Used to specify a server name if you connect to a remote VECS instance.

--upn <user-name>

User Principle Name that is used to log in to the server instance specified by --server <server-name> . When you create a store, it is created in the context of the current user. Therefore, the owner of the store is the current user context and not always the root user.

vecs-cli entry delete

Deletes an entry in a certificate store. If you delete an entry in VECS, you permanently remove it from VECS. The only exception is the current root certificate. VECS polls vmdir for a root certificate.

Option Description
--store <NameOfStore>

Name of the certificate store.

--alias <Alias> Alias for the entry you want to delete.

--server <server-name>

Used to specify a server name if you connect to a remote VECS instance.

--upn <user-name>

User Principle Name that is used to log in to the server instance specified by --server <server-name> . When you create a store, it is created in the context of the current user. Therefore, the owner of the store is the current user context and not always the root user.

-y Suppresses the confirmation prompt. For advanced users only.

vecs-cli force-refresh

Forces a refresh of VECS. By default, VECS polls vmdir for new root certificate files every 5 minutes. Use this command for an immediate update of VECS from vmdir.

Option Description

--server <server-name>

Used to specify a server name if you connect to a remote VECS instance.

--upn <user-name>

User Principle Name that is used to log in to the server instance specified by --server <server-name> . When you create a store, it is created in the context of the current user. Therefore, the owner of the store is the current user context and not always the root user.