Query Crypto Key In-Use Status

Sometimes it is useful to determine key status, for example whether a key is available on vCenter Server, which virtual machines and ESXi hosts are using it, and if third party applications reference it.

As of vSphere 6.7 Update 2, the queryCryptoKeyStatus method is available to check use of a KMS key, such as if vCenter Server can access the key, if the key is being used by some virtual machines, or as a host key. The first parameter is a key ID or an array of key IDs to query. The second parameter is a bitmap defining items to check:

  • 0x01 - ask if key data is available to vCenter Server
  • 0x02 - query which virtual machines use this key
  • 0x04 - check the ESXi hosts using this as a host key
  • 0x08 - check third party programs using this key.

Key status results are returned in a CryptoManagerKmip::CryptoKeyStatus data object, called keyStatusArray in the code below. If your program queried multiple keys, an array of results is returned.

The queryCryptoKeyStatus method and its returned data object are new in vSphere 6.7 U2, so it does not work in earlier releases.

The following Java code checks all items above by passing 15, a bitwise OR of the settings above. 
CryptoManagerKmipCryptoKeyStatus[] keyStatusArray =
   vimPort.queryCryptoKeyStatus(cryptoManager,
   [vmKeyId, diskKeyId, srcHostkey, dstHostkey], 15);
for (CryptoManagerKmipCryptoKeyStatus keyStatus : keyStatusArray[]) {
   System.out.println("keyId: " + keyStatus.getKeyId);
   System.out.println("keyAccessible: " + keyStatus.getKeyAvailable)
   System.out.println("reason: " + keyStatus.getReason)
   System.out.println("encryptedVMs: " + keyStatus.getEncryptedVMs)
   System.out.println("affectedHosts: " + keyStatus.getAffectedHosts)
   System.out.println("referencedByTags: " + keyStatus.getReferencedByTags)
}

The keyAccessible means the key is available on vCenter Server. The reason is either valid, or indicates why the key is not available. The encryptedVMs is an array of virtual machine MoRefs, and affectedHosts is an array of MoRefs to ESXi hosts. The referencedByTags field gives names of third party applications using the key.