Procedures

Prerequisites

Before you integrate the Entrust KeyControl KMIP Vault KMS with VMware encryption solutions, complete the following tasks:

Entrust KeyControl KMIP Vault is deployed and configured.
VMware vSphere is deployed and configured using vCenter.
You have administrator rights to manage the KMS configuration in vCenter.

Create a KMIP Vault in the KeyControl Vault Server

The KeyControl Vault appliance supports different type of vaults that can be used by all type of applications. This section describes how to create a KMIP Vault in the KeyControl Vault Server.

Refer to the Creating a Vault section of the admin guide for more details about it.

Log into the KeyControl Vault Server web user interface:
1. Use your browser to access the IP address of the server.
2. Sign in using the secroot credentials.
If not in the Vault Management interface, select SWITCH TO: Manage Vaults in the Menu Header.

This action will take you to the KeyControl Vault Management interface.
In the KeyControl Vault Management interface, select Create Vault.
KeyControl Vault supports the following types of vaults:
- Cloud Keys - Vault for cloud keys such as BYOK and HYOK.
- KMIP - Vault for KMIP Objects.
- Secrets - Vault for objects such as passwords, files, SSH keys, and so on.
- Database - Vault for database keys.
- Application Security - Vault for application security policies.
- VM Encryption - Vault for policy agent VM encryption.

In the Create Vault page, create a KMIP Vault:

For Type, select KMIP.
For Name, enter the name of the Vault.
For Description, enter the description of the Vault.
For Admin Name, enter the name of the administrator of the Vault.

For Admin Email, enter a valid email for the administrator.

vault create

A temporary password will be emailed to the administrator’s email address. This is the password that will be used to sign in for the first time to the KMIP Vaults space in KeyControl. In a closed gap environment where email is not available, the password for the user is displayed when you first create the vault. That can be copied and sent to the user.

Select Create Vault.
Select Close when the Vault creation completes.
The newly-created Vault is added to the Vault dashboard.
After the Vault has been created, the KMIP server settings on the appliance are enabled.

KMIP server settings

The KMIP server settings are set at the KeyControl appliance level and apply to all the KMIP Vaults in the appliance. After a KMIP Vault is created, they are automatically set to ENABLED.

To use external key management and configure the KeyControl Vault KMIP settings, refer to the KeyControl Vault for KMIP section of the admin guide.

When using external key management, as is the case in this solution, the KeyControl server is the KMIP server and the VMware vCenter server is the KMIP client.

Select the Settings icon on the top right to view/change the KMIP settings.
1. The defaults settings are appropriate for most applications.
2. Make any changes necessary.
Select Apply.

View details for the Vault

To view the details on the Vault, select View Details when you hover over the Vault.

vault details

Edit a vault

To edit the details of the Vault, select Edit when you hover over the Vault.

vault edit

Managing the Vault

After the Vault has been created, look for the email that was sent with the Vault’s URL and the login information for the Vault. For example:

Go to the URL and sign in with the credentials given. When you sign in for the first time, the system will ask the user to change the password.

In a closed gap environment where email is not available, the password for the user is displayed when you first create the vault. That can be copied and sent to the user.

Setup other Administrators

It is important to have other administrators set up on the Vault for recovery purposes. Add one or more admins to the Vault.

Select Security > Users.
In the Manage Users dashboard:
1. Select the + icon to add one or more users.
2. Add the user by providing the information requested in the Add User dialog.
3. Select Add.

Establishing trust between the KeyControl KMIP Vault and the VMware vCenter

Certificates are required to facilitate the KMIP communications from the KeyControl KMIP ault and the vCenter application and conversely. The built-in capabilities in the KeyControl KMIP Vault are used to create and publish the certificates.

For more information on how to create a certificate bundle, refer to Establishing a Trusted Connection with a KeyControl Vault-Generated CSR.

The process below will show how to integrate VMware vSphere encryption or VSAN encryption with KeyControl KMIP Vault.

Sign in to the KMIP Vault created earlier. Use the login URL and credentials provided to the administrator of the Vault.
Select Security, then Client Certificates.
In the Manage Client Certificate page, select the + icon on the right to create a new certificate.
1. There is the option of creating two types of certificates that can be used by vCenter:
  - A certificate with no authentication.
  - A certificate with authentication.
2. Create the certificate that best fits your environment needs.
In the Create Client Certificate dialog box:
1. Enter a name in the Certificate Name field.
2. Set the date on which you want the certificate to expire in the Certificate Expiration field.
3. If creating a certificate with authentication:
  1. Select Add Authentication for Certificate.
  2. Enter the User Name
  3. Enter the Password
  4. These settings will be used later when the certificates are used in vCenter if authentication is used.
4. Select Create.
  
  The new certificates are added to the Manage Client Certificate pane.
Select the certificate and select the Download icon to download the certificate.

The webGUI downloads certname_datetimestamp.zip, which contains a user certification/key file called certname.pem and a server certification file called cacert.pem.
Unzip the file so that you have the certname.pem file available to upload.
The download zip file contains the following:
- A certname.pem file that includes both the client certificate and private key. In this example, this file is called vCenterKMS.pem.
  
  The client certificate section of the certname.pem file includes the lines “-----BEGIN CERTIFICATE-----" and “-----END CERTIFICATE-----" and all text between them.
  
  The private key section of the certname.pem file includes the lines “-----BEGIN PRIVATE KEY-----" and “-----END PRIVATE KEY-----" and all text in between them.
- A cacert.pem file which is the root certificate for the KMS cluster. It is always named cacert.pem.
These files will be used in the vCenter KMS cluster configuration later.

Create the KMS cluster in vCenter

For more detail on how to do this, see Adding a KMS Cluster in vSphere in the Entrust online documentation.

Launch the vSphere Web Client and log into the vCenter server that you want to add to Entrust KeyControl.
Select the required vCenter Server in the Global Inventory Lists.
Select the Configure tab.
In the left-hand pane, select Security > Key Providers.
Select Add Standard Key Provider.

In the Add Standard Key Provider dialog, set the following configuration options:

For Name, enter the name of the cluster.

For each node in the KeyControl cluster, enter the KMS (node name), IP Address and Port. The default port is 5696.

Make sure that the KMIP server resides on a device that is not encrypted using the KeyControl Vault server cluster. The KMIP server must be available to provide the keys for the encrypted devices before the encrypted devices can be accessed.

To add an extra node line, select Add KMS.

vcenter addkms

Open and set Proxy Configuration if you are using a proxy.
Password protection is optional. Provide the information if the certificate created in the KeyControl KMIP Vault was created with authentication.

Select Add Key Provider.

In the Make vCenter Trust Key Provider dialog, confirm the details for each node and then select Trust. For example:

vcenter trustkms

This adds the KMS cluster to vCenter, but the connection status will be KMS not connected with Certificate issues. For example:

vcenter kmsnotconnected

If you get a message stating that it "Cannot retrieve the requested certificate", it maybe related to the TLS Configuration in the KeyControl Appliances. This issue is related to using earlier versions of vCenter where TLS Extended Master Secret is not supported. Suggested fixes are upgrading to the latest version of vCenter or change KeyControl to NOT enforce EMS in the TLS configuraton. Please refer to TLS Configuration settings in the KeyControl Administration Guide.

Establish a trusted connection between the KMS cluster and the Entrust KeyControl KMIP Vault

To establish a trusted connection between the KMS cluster and the Entrust KeyControl KMIP Vault:

Continuing from the previous section, select the KeyControl KMS cluster in the list, then scroll down to where the nodes are listed.
Select one of the nodes, then select on Establish Trust > Make KMS trust vCenter. For example:
In the Choose method pane of the Make KMS Trust vCenter dialog, select KMS certificate and private key.
Select Next.
In the Upload KMS Credentials pane of the Make KMS Trust vCenter dialog, you must upload the certname.pem file created during the certificate creation process earlier. This file must be uploaded for the KMS certificate and then uploaded again for the private key. To do this:
1. For KMS certificate, select Upload file. Then select the certname.pem file and select Open.
2. For Private key, select Upload file. Then select the certname.pem file again and select Open.
3. Select Establish Trust.
Wait until vCenter reports that the connection status for the KMS cluster has changed to Connected. For example:

Enable Encryption for virtual machines

Enable encryption using VMware Storage Policies:

Launch the vSphere Web Client and log into the vCenter server.
Locate a VM that you would like to encrypt.
Make sure the Power state of the VM is Powered Off.
Right-click the VM for which you would like to enable encryption and select VM Policies > Edit VM Storage Policies.
Select the storage policy VM Encryption Policy and select OK.

This will trigger a reconfiguration of the VM. For example:

After the reconfiguration is complete, the disks are encrypted and the keys are managed by the configured KMS (KeyControl).

Check encryption at the VM level

To check encryption at the VM level:

Launch the vSphere Web Client and log into the vCenter server.
Locate a VM and select it.
In VM View, select the Summary tab.
Under Virtual Machine Details > Encryption, the status should be:
```
Encrypted with standard key provider
```

Check encryption by looking for the Keys in the Entrust KeyControl KMIP Vault

To check encryption by looking for keys:

Log into the KMIP Vault using the login URL.
Select the Objects tab to view a list of KMIP Objects. This will include the newly-created keys. For example:
Select one of the keys to display its KMIP Object Details. For example:
Select the Custom Attributes tab to make sure it is the key used by VMware vSphere.
In the main screen, select the Audit Logs tab to view the log records related to the key creation process. For example:

For more information on this topic, refer to Virtual Machine Encryption on the VMware documentation site.

Enable Data-At-Rest encryption on an existing vSAN cluster

To enable Data-At-Rest encryption on an existing vSAN cluster, refer to Using Encryption in a vSAN Cluster on the VMware documentation site.