You can use the vSphere Automation API to feed external entropy data to an ESXi host in your inventory. You can also query the current entropy levels on the host and add external entropy data when needed.
Entropy is a measure of the randomness or diversity of a data-generating function. In releases prior to vSphere 8.0 Update 1, ESXi supported only CPU-based entropy data generated from interrupts or manufacturer provided interfaces, such as RDSEED and RDRAND. High-quality entropy is important for the proper functioning of security-related operations such as generating encryption keys for secure communication over the network. Starting with vSphere 8.0 Update 1, you can add external entropy sources to an ESXi host and in this way ensure the high quality of the entropy data on that host. You provide external entropy data by using devices such as hardware security modules (HSMs) which are FIPS 140-3 and EAL4 certified.
You can configure the ESXi entropy sources by using the VMkernel boot options. To use external entropy sources, set the entropySources value to more than or equal to 8. For more information about how to set the desired entropy sources by using the VMkernel boot options, see Controlling ESXi Entropy in the vSphere Security documentation.
You can also configure external entropy sources in the kickstart file for the ESXi scripted installation. See Configuring External Entropy Sources During Scripted Installation.
If a host is configured to use only external entropy sources, that is, entropySources is set to 8, you must keep supplying the external entropy data through the vSphere Automation API. In case the entropy in the host gets exhausted, the host becomes unresponsive and might require a hard reboot or re-installation to recover the host from this situation.
Querying Entropy Data on a Host
To retrieve details about the external entropy available on an ESXi host, use the ExternalPool service. You must have the Host.Entropy.Read privilege.
You can check whether an external entropy source is added to a host by using the GET https://<vcenter_ip_address_or_fqdn>/api/vcenter/host/<host_id>/entropy/external-pool HTTP request and passing the host ID as a path parameter. The operation returns an ExternalPool.Info JSON object in the response body that contains detailed information about the external entropy data on the host.
| Property | Description |
|---|---|
| status | Indicates whether an external entropy source is added for a host. |
| capacity | Shows the maximum capacity of external entropy data in bytes that a host can store in the VMkernel entropy pool. When you feed the host with additional external entropy data, make sure that you do not exceed this maximum capacity. Otherwise, all extra entropy data is discarded. |
| currently_available | Indicates the current amount of entropy data in bytes available in the VMkernel entropy pool on the host. |
| inactive_source_timeout | Indicates the amount of time in seconds that can elapse without any activity between the host and the external entropy source. Your application must check periodically the levels of entropy data on the host and send entropy data from the external source when required. When this timeout exceeds an esx.audit.entropy.external.source.disconnected VMkernel Observation (VOB) is logged. This system event suggests possible loss of connection to the external entropy source. For the full list of available entropy VOBs in vSphere 8.0, see the VMware knowledge base article at https://kb.vmware.com/s/article/89074. |
| low_watermark | Indicates the threshold in bits sufficient for the in-memory cache to operate successfully. When the in-memory entropy cache is running low and the threshold is reached, an esx.audit.entropy.available.low VOB is logged. For more information about the entropy VOBs, see the VMware knowledge base article at https://kb.vmware.com/s/article/89074. |
Adding External Entropy Data to a Host
To add entropy data from an external entropy source to a host, you must have the Host.Entropy.Write privilege. Use the ExternalPool service and send the POST https://<vcenter_ip_address_or_fqdn>/api/vcenter/host/<host_id>/entropy/external-pool?action=add request. Pass the host ID as a path parameter and an ExternalPool.AddSpec data structure in the request body. The ExternalPool.AddSpec JSON object contains the Base64 encoded external entropy data. You must convert the binary data coming from the external entropy source to Base64 format so that the host can consume it. The request returns an ExternalPool.AddResult JSON object in the response body, if the request succeeds.
When the external entropy data reaches the host, the entropy daemon stores it first in the in-memory cache and the storage cache. Then the external entropy data is pushed to the VMkernel entropy pool from which it is fed to the applications in need.
The entropy data in the storage cache persists on the host disk and is only consumed during the ESXi booting. The default storage file size is 4MiB and can be configured through the ESXCLI commands. See the ESXCLI Command Reference documentation.
