rSTify ppc-spapr-uv-hcalls.txt.
Signed-off-by: Leonardo Garcia <lagarcia@br.ibm.com> Reviewed-by: Daniel Henrique Barboza <danielhb413@gmail.com> Message-Id: <243a714d3861f7539d29b02a899ffc376757d668.1642446876.git.lagarcia@br.ibm.com> Signed-off-by: Cédric Le Goater <clg@kaod.org>
This commit is contained in:
Leonardo Garcia
Cédric Le Goater
parent
22beb38b78
commit
2084b44d7a
@ -1,76 +1,89 @@
|
||||
On PPC64 systems supporting Protected Execution Facility (PEF), system
|
||||
memory can be placed in a secured region where only an "ultravisor"
|
||||
running in firmware can provide to access it. pseries guests on such
|
||||
systems can communicate with the ultravisor (via ultracalls) to switch to a
|
||||
secure VM mode (SVM) where the guest's memory is relocated to this secured
|
||||
region, making its memory inaccessible to normal processes/guests running on
|
||||
the host.
|
||||
===================================
|
||||
Hypervisor calls and the Ultravisor
|
||||
===================================
|
||||
|
||||
The various ultracalls/hypercalls relating to SVM mode are currently
|
||||
only documented internally, but are planned for direct inclusion into the
|
||||
public OpenPOWER version of the PAPR specification (LoPAPR/LoPAR). An internal
|
||||
ACR has been filed to reserve a hypercall number range specific to this
|
||||
use-case to avoid any future conflicts with the internally-maintained PAPR
|
||||
specification. This document summarizes some of these details as they relate
|
||||
to QEMU.
|
||||
On PPC64 systems supporting Protected Execution Facility (PEF), system memory
|
||||
can be placed in a secured region where only an ultravisor running in firmware
|
||||
can provide access to. pSeries guests on such systems can communicate with
|
||||
the ultravisor (via ultracalls) to switch to a secure virtual machine (SVM) mode
|
||||
where the guest's memory is relocated to this secured region, making its memory
|
||||
inaccessible to normal processes/guests running on the host.
|
||||
|
||||
== hypercalls needed by the ultravisor ==
|
||||
The various ultracalls/hypercalls relating to SVM mode are currently only
|
||||
documented internally, but are planned for direct inclusion into the Linux on
|
||||
Power Architecture Reference document ([LoPAR]_). An internal ACR has been filed
|
||||
to reserve a hypercall number range specific to this use case to avoid any
|
||||
future conflicts with the IBM internally maintained Power Architecture Platform
|
||||
Reference (PAPR+) documentation specification. This document summarizes some of
|
||||
these details as they relate to QEMU.
|
||||
|
||||
Switching to SVM mode involves a number of hcalls issued by the ultravisor
|
||||
to the hypervisor to orchestrate the movement of guest memory to secure
|
||||
memory and various other aspects SVM mode. Numbers are assigned for these
|
||||
hcalls within the reserved range 0xEF00-0xEF80. The below documents the
|
||||
hcalls relevant to QEMU.
|
||||
Hypercalls needed by the ultravisor
|
||||
===================================
|
||||
|
||||
- H_TPM_COMM (0xef10)
|
||||
Switching to SVM mode involves a number of hcalls issued by the ultravisor to
|
||||
the hypervisor to orchestrate the movement of guest memory to secure memory and
|
||||
various other aspects of the SVM mode. Numbers are assigned for these hcalls
|
||||
within the reserved range ``0xEF00-0xEF80``. The below documents the hcalls
|
||||
relevant to QEMU.
|
||||
|
||||
For TPM_COMM_OP_EXECUTE operation:
|
||||
Send a request to a TPM and receive a response, opening a new TPM session
|
||||
if one has not already been opened.
|
||||
``H_TPM_COMM`` (``0xef10``)
|
||||
---------------------------
|
||||
|
||||
For TPM_COMM_OP_CLOSE_SESSION operation:
|
||||
Close the existing TPM session, if any.
|
||||
SVM file systems are encrypted using a symmetric key. This key is then
|
||||
wrapped/encrypted using the public key of a trusted system which has the private
|
||||
key stored in the system's TPM. An Ultravisor will use this hcall to
|
||||
unwrap/unseal the symmetric key using the system's TPM device or a TPM Resource
|
||||
Manager associated with the device.
|
||||
|
||||
Arguments:
|
||||
The Ultravisor sets up a separate session key with the TPM in advance during
|
||||
host system boot. All sensitive in and out values will be encrypted using the
|
||||
session key. Though the hypervisor will see the in and out buffers in raw form,
|
||||
any sensitive contents will generally be encrypted using this session key.
|
||||
|
||||
r3 : H_TPM_COMM (0xef10)
|
||||
r4 : TPM operation, one of:
|
||||
TPM_COMM_OP_EXECUTE (0x1)
|
||||
TPM_COMM_OP_CLOSE_SESSION (0x2)
|
||||
r5 : in_buffer, guest physical address of buffer containing the request
|
||||
- Caller may use the same address for both request and response
|
||||
r6 : in_size, size of the in buffer
|
||||
- Must be less than or equal to 4KB
|
||||
r7 : out_buffer, guest physical address of buffer to store the response
|
||||
- Caller may use the same address for both request and response
|
||||
r8 : out_size, size of the out buffer
|
||||
- Must be at least 4KB, as this is the maximum request/response size
|
||||
supported by most TPM implementations, including the TPM Resource
|
||||
Manager in the linux kernel.
|
||||
Arguments:
|
||||
|
||||
Return values:
|
||||
``r3``: ``H_TPM_COMM`` (``0xef10``)
|
||||
|
||||
r3 : H_Success request processed successfully
|
||||
H_PARAMETER invalid TPM operation
|
||||
H_P2 in_buffer is invalid
|
||||
H_P3 in_size is invalid
|
||||
H_P4 out_buffer is invalid
|
||||
H_P5 out_size is invalid
|
||||
H_RESOURCE problem communicating with TPM
|
||||
H_FUNCTION TPM access is not currently allowed/configured
|
||||
r4 : For TPM_COMM_OP_EXECUTE, the size of the response will be stored here
|
||||
upon success.
|
||||
``r4``: ``TPM`` operation, one of:
|
||||
|
||||
Use-case/notes:
|
||||
``TPM_COMM_OP_EXECUTE`` (``0x1``): send a request to a TPM and receive a
|
||||
response, opening a new TPM session if one has not already been opened.
|
||||
|
||||
SVM filesystems are encrypted using a symmetric key. This key is then
|
||||
wrapped/encrypted using the public key of a trusted system which has the
|
||||
private key stored in the system's TPM. An Ultravisor will use this
|
||||
hcall to unwrap/unseal the symmetric key using the system's TPM device
|
||||
or a TPM Resource Manager associated with the device.
|
||||
``TPM_COMM_OP_CLOSE_SESSION`` (``0x2``): close the existing TPM session, if
|
||||
any.
|
||||
|
||||
The Ultravisor sets up a separate session key with the TPM in advance
|
||||
during host system boot. All sensitive in and out values will be
|
||||
encrypted using the session key. Though the hypervisor will see the 'in'
|
||||
and 'out' buffers in raw form, any sensitive contents will generally be
|
||||
encrypted using this session key.
|
||||
``r5``: ``in_buffer``, guest physical address of buffer containing the
|
||||
request. Caller may use the same address for both request and response.
|
||||
|
||||
``r6``: ``in_size``, size of the in buffer. Must be less than or equal to
|
||||
4 KB.
|
||||
|
||||
``r7``: ``out_buffer``, guest physical address of buffer to store the
|
||||
response. Caller may use the same address for both request and response.
|
||||
|
||||
``r8``: ``out_size``, size of the out buffer. Must be at least 4 KB, as this
|
||||
is the maximum request/response size supported by most TPM implementations,
|
||||
including the TPM Resource Manager in the linux kernel.
|
||||
|
||||
Return values:
|
||||
|
||||
``r3``: one of the following values:
|
||||
|
||||
``H_Success``: request processed successfully.
|
||||
|
||||
``H_PARAMETER``: invalid TPM operation.
|
||||
|
||||
``H_P2``: ``in_buffer`` is invalid.
|
||||
|
||||
``H_P3``: ``in_size`` is invalid.
|
||||
|
||||
``H_P4``: ``out_buffer`` is invalid.
|
||||
|
||||
``H_P5``: ``out_size`` is invalid.
|
||||
|
||||
``H_RESOURCE``: problem communicating with TPM.
|
||||
|
||||
``H_FUNCTION``: TPM access is not currently allowed/configured.
|
||||
|
||||
``r4``: For ``TPM_COMM_OP_EXECUTE``, the size of the response will be stored
|
||||
here upon success.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user