API Methods for vSphere Virtual Machine Encryption

Methods for managing vSphere virtual machine encryption are in the vSphere API, part of the Web Services SDK. In addition, you need a few Storage Policy APIs to create and assign encryption storage policies.

vSphere API Methods for KMS Management

Cryptographic key management interfaces are defined in the following hierarchy.

■	CryptoManager – managed object, parent of CryptoManagerKmip.

CryptoManager defines methods that are covered in vSphere API Methods for Cryptographic Operations.

■	CryptoManagerKmip – managed object for handing the cryptographic keys.

■	CertificateInfo – basic information of a certificate.

■	ClusterStatus – status of a KMS cluster.

■	ServerCertInfo – information about the KMS certificate.

■	ServerStatus – status of a KMS.

CryptoManagerKmip defines the following methods:

■	String generateClientCsr(cluster) – generate a certificate signing request with its private key.

■	String generateSelfSignedClientCert(cluster) – generate self-signed client certificate with its private key.

■	KmipClusterInfo[] kmipServers() – get a list of registered KMS, grouped by clusters.

■	KmipClusterInfo[] listKmipServers(limit) – get a list of registered KMS.

■	void markDefault(clusterId) – set the default KMS cluster.

■	void registerKmipServer(server) – register a KMS.

■	void removeKmipServer(clusterId, serverName) – remove a KMS, even if in use.

■	String retrieveClientCert(cluster) – get the client certificate of the KMS cluster.

■	String retrieveClientCsr(cluster) – get the generated client certificate signing request.

■	ServerCertInfo retrieveKmipServerCert(keyProvider, server) – get the server certificate.

■	ClusterStatus[] retrieveKmipServersStatus(clusters[]) – get status of the KMS instances.

■	String retrieveSelfSignedClientCert(cluster) – get generated self signed client certificate.

■	void updateKmipServer(server) – update a KMS.

■	void updateKmsSignedCsrClientCert(cluster, certificate) – Set KMS signed certificate as the client certificate for a KMS cluster.

■	void updateSelfSignedClientCert(cluster, certificate) – set a self-signed certificate as the client certificate for the KMS cluster.

■	void uploadClientCert(cluster, certificate, privateKey) – set a client certificate with private key for the KMS cluster.

■	void uploadKmipServerCert(cluster, certificate) – upload a server certificate.

■	CryptoKeyResult generateKey(keyProvider) – generate a new encryption key.

The generateKey method is out of alphabetic order because it is called after the others.

API Methods to Prepare an ESXi Host

Encryption interfaces for ESXi hosts are additions to a previously existing managed object, HostSystem.

■	HostSystem – managed object providing access to the ESXi host, including these additions:

■	HostCryptoState – enumeration indicating whether the ESXi host is incapable of, prepared for encryption mode, or cryptography safe with its host key already set. Safe means that the ESXi host can encrypt virtual machines and will not leak keys.

■	ConfigureCryptoKey – vCenter Server calls this method to set or change the key used for core dump encryption, and to place the host in safe mode. It is like calling PrepareCrypto and EnableCrypto in quick succession. Not supported if called on an ESXi host.

■	PrepareCrypto – this method puts the ESXi host in prepared mode so it can receive sensitive data.

■	EnableCrypto – this method sets or changes the key for core dump encryption and puts the ESXi host in safe mode. It must be called in sequence after PrepareCrypto.

The following data objects are used by ConfigureCryptoKey and EnableCrypto methods above, and by five CryptoManager methods below in vSphere API Methods for Cryptographic Operations.

■	CryptoKeyPlain – data object representing a plain text cryptographic key.

■	CryptoKeyId – data object representing a cryptographic key.

■	CryptoKeyResult – data object representing the result of a cryptographic key operation.

vSphere API Methods for Cryptographic Operations

Cryptographic operations are defined in the following hierarchy.

■	CryptoManager – managed object for handling cryptographic keys.

CryptoManager defines the following methods:

■	void addKey(CryptoKeyPlain key) – add plain key to the vCenter Server.

■	CryptoKeyResult[] addKeys(CryptoKeyPlain[] keys) – add multiple plain keys to vCenter.

■	boolean enabled() – indicate if the encryption feature is enabled.

■	CryptoKeyId[] listKeys(int limit) – list keys.

■	void removeKey(CryptoKeyId key, boolean force) – remove a key (only its ID is needed).

■	CryptoKeyResult[] removeKeys(CryptoKeyId[] keys, boolean force) – multiple keys.

■

VirtualMachineConfigSpec – previously existing data object passed as parameter to CreateVM_Task and ReconfigVM_Task. One of its newly added properties is crypto, a CryptoSpec with one of the following options, which is inherited by all virtual disks and virtual machine configuration files (VM home).

■	CryptoSpecEncrypt – indicates that the virtual machine should be encrypted.

■	CryptoSpecDecrypt – indicates that the virtual machine should be decrypted.

■	CryptoSpecDeepRecrypt – indicates that all KEKs and DEKs should be replaced.

■	CryptoSpecShallowRecrypt – indicates that only KEKs should be replaced.

■	CryptoSpecNoOp – indicates that encryption settings should not be changed.

■

CryptoSpecRegister – indicates that the operation should send keys but should not modify the encryption settings of the virtual machine or virtual disk. When an encrypted disk is hot attached, the program must pass CryptoSpecRegister with the key ID that encrypted the disk. The key can be obtained from the Datastore Browser.

These data objects are informational properties of VMConfigFileInfo and VMDiskFileInfo, respectively. They can be used to check whether the VM home and its virtual disks are encrypted.

■	VmConfigFileEncryptionInfo – the encryption information of a virtual machine configuration.

■	VmDiskFileEncryptionInfo – the encryption information of a virtual disk.

The enumeration EncryptedVMotionModes controls whether encrypted VMotion is disabled, required, or opportunistic (fall back to unencrypted VMotion if necessary, the default option).

More information about the encryption interfaces is available in vSphere Management SDK Documentation under vSphere Web Services SDK, in the vSphere API Reference.

SPBM API Methods for Encryption

The managed object PbmProfileProfileManager (pbm.profile.ProfileManager) provides methods to set encryption related storage policies, including create and update.

■	PbmCreate(createSpec) – create a capability-based storage profile defining storage requirements.

■	PbmUpdate(profileId, createSpec) – update a storage profile with new capability requirements.