VMware VM Encryption Powershell scripts

With the release of vSphere 6.5, there is a cool new feature with which I have worked extensively – VM Encryption. VM Encryption is pretty awesome, in my honest opinion, due to the granularity of control you have over which entities to encrypt. Other encryption methodologies for data at rest, such as native device encryption on the array and even vSAN Encryption can only protect data that has already traversed the storage fabric and is encrypted only when being written to disk. With VM encryption, the data is encrypted even before it reaches the storage stack, by use of IO Filters (https://blogs.vmware.com/virtualblocks/2015/02/05/vsphere-apis-for-io-filtering/), so even as it traverses the fabric, it is already encrypted. Pretty cool! What this means is that encryption can be applied regardless of GuestOS. The encryption is applied simply by using a Storage Policy that is assigned to the VM, so management is really simple too. For more details, see https://blogs.vmware.com/vsphere/2016/10/whats-new-in-vsphere-6-5-security.html and https://docs.vmware.com/en/VMware-vSphere/6.5/com.vmware.vsphere.security.doc/GUID-E6C5CE29-CD1D-4555-859C-A0492E7CB45D.html

While VM Encryption is very simple to set up and implement, I felt that there were some gaps in the ongoing management capabilities, once the Encrypted VMs were up and running. For instance, for security compliance, you may need to rekey VMs periodically, or check which key is required to actually manage a VM.

In December 2016, a Powershell Module for VM Encryption was released that will assist in performing some of these critical tasks that are only possible through APIs, such as the rekeying of VMs and hosts. Details of this module can be found here: https://blogs.vmware.com/vsphere/2016/12/powercli-for-vm-encryption.html

This module contains cmdlets that allow the administrator to perform a number of tasks that would not otherwise be possible through the UI. Here is a summary of the available cmdlets:

PS C:\Windows\system32> get-Command -Module VMware.VMEncryption

CommandType Name Version Source 
----------- ---- ------- ------ 
Function Disable-VMDiskEncryption 0.0 VMware.VMEncryption 
Function Disable-VMEncryption 0.0 VMware.VMEncryption 
Function Enable-VMDiskEncryption 0.0 VMware.VMEncryption 
Function Enable-VMEncryption 0.0 VMware.VMEncryption 
Function Enable-VMHostCryptoSafe 0.0 VMware.VMEncryption 
Function Get-DefaultKMSCluster 0.0 VMware.VMEncryption 
Function Get-EntityByCryptoKey 0.0 VMware.VMEncryption 
Function Get-InstallPath 0.0 VMware.VMEncryption 
Function Get-KMSCluster 0.0 VMware.VMEncryption 
Function Get-KMSClusterInfo 0.0 VMware.VMEncryption 
Function Get-KMServerInfo 0.0 VMware.VMEncryption 
Function Get-KMServerStatus 0.0 VMware.VMEncryption 
Function Get-PSVersion 0.0 VMware.VMEncryption 
Function Get-VMEncryptionInfo 0.0 VMware.VMEncryption 
Function New-KMServer 0.0 VMware.VMEncryption 
Function Remove-KMServer 0.0 VMware.VMEncryption 
Function Set-DefaultKMSCluster 0.0 VMware.VMEncryption 
Function Set-VMDiskEncryptionKey 0.0 VMware.VMEncryption 
Function Set-VMEncryptionKey 0.0 VMware.VMEncryption 
Function Set-VMHostCryptoKey 0.0 VMware.VMEncryption

The functions that are of most interest to me are the ‘Set-‘ commands, as these allow you to perform the rekey operations I spoke of earlier.

So, when might you need to perform a rekey operation?

1. When you are upgrading from a virtual appliance to a hardware appliance (like HyTrust to Thales) due to encountering a key limit, or something similar.
2. You have experienced a critical failure on a KMS due to negligence or some physical failure which would require deploying a new KMS and generating new keys.
3. When you are moving VMs from Dev to Production where a different/more secure KMS is used.
4. When the security of the key server has been compromised, requiring a new deployment.
5. When a core dump (containing private keys used for encryption) has been provided to VMware out of necessity. Our best practice would require that all VMs in that cluster be rekeyed.
6. For security compliance, periodic rotation of keys are required.

To make the task simpler, I have created a Powershell Script that I am happy to share. I would love to hear your suggestions for improvement, as I am a relative newbie to Powershell.

FindAndReplaceKMSKeys Script

The first script I have created allows you to search through your inventory for VMs and hosts that use keys provided by a given KMS Cluster, and then you have the option to select which discovered hosts and VMs you want to rekey. It is a relatively simple script and can be downloaded here: https://github.com/jameseydoyle/VMware-VM-Encryption-Powershell-scripts/blob/master/FindAndReplaceKMSKeys-1.0.2.ps1

Usage

When you run the script, it will check that you have the correct VMware.VMEncryption module imported and if not, the URL from which you can download it is provided.

You will then be prompted for the details of the vCenter you wish to connect to:

Enter your credentials in the pop-up dialog box:

Next, you will be asked if the keys you are replacing are provided by a KMS Cluster that is currently connected to vCenter or not. I have included this option so that, if you have lost access to your KMS, you can still manually specify the KMS Cluster name. If the KMS cluster is still connected to vCenter, you can specify [Y] and the script will discover currently available KMS Clusters.

If you choose [N] here, you will need to know the exact name of the KMS Cluster as it appeared in vCenter previously. The reason for this is that all Key Identifiers include the name of the cluster from which the key was retrieved. If you do not specify the correct cluster name, it will not match the key identifiers.

For this example, let’s assume we said [Y]. You will be prompted in pop-up box to choose a discovered KMS Cluster by highlighting and selecting the relevant one from the list:

Once you have confirmed that the correct KMS Cluster has been chosen, the script will go and discover any hosts whose HostKeys are provided by the specified KMS Cluster. Again a pop-up box will prompt you to choose which hosts you want to rekey. (You can choose multiple hosts by using the Ctrl or Shift keys):

You will be prompted to confirm your choice and then the script will proceed to request a new key from the default KMS Cluster for each host.

Now, it’s time to search for VMs that are encrypted with keys provided by the selected KMS Cluster. Once again you be prompted to choose from a list of discovered VMs and, again, you can make multiple selections if required.

For this script, I have included the option to ‘Shallow Rekey’, which means only the Key Encryption Key (KEK) will be replaced. This is a relatively minor operation which will not require a complete re-encryption of the data, but rather simply replaces the KMS-provided key which protects the Data Encryption Key (DEK) stored with the VM.

You will be prompted to confirm that you want both the VM Configuration files and the VMs disks rekeyed, and once confirmed, the rekey operation will be requested. Then the script will finally complete and disconnect from vCenter.

Hopefully, you will find this script useful.