VMware vSphere SDKs and Tools 8.0

8.0 7.0 6.7 6.5

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.

Content feedback and comments