aboutsummaryrefslogtreecommitdiff
path: root/docs/specs
diff options
context:
space:
mode:
authorMichael Roth <mdroth@linux.vnet.ibm.com>2019-07-17 15:58:41 -0500
committerDavid Gibson <david@gibson.dropbear.id.au>2019-08-21 17:17:12 +1000
commit1daba4d1b296d23907b73735615b12588da670fb (patch)
tree65cc31e23d2d7f7a21ab18cfe991adf418505645 /docs/specs
parent107413142bf34aecdea2398a3e976739f1256c64 (diff)
docs/specs: initial spec summary for Ultravisor-related hcalls
For now this only covers hcalls relating to TPM communication since it's the only one particularly important from a QEMU perspective atm, but others can be added here where it makes sense. The full specification for all hcalls/ucalls will eventually be made available in the public/OpenPower version of the PAPR specification. Signed-off-by: Michael Roth <mdroth@linux.vnet.ibm.com> Message-Id: <20190717205842.17827-2-mdroth@linux.vnet.ibm.com> Signed-off-by: David Gibson <david@gibson.dropbear.id.au>
Diffstat (limited to 'docs/specs')
-rw-r--r--docs/specs/ppc-spapr-uv-hcalls.txt76
1 files changed, 76 insertions, 0 deletions
diff --git a/docs/specs/ppc-spapr-uv-hcalls.txt b/docs/specs/ppc-spapr-uv-hcalls.txt
new file mode 100644
index 0000000000..389c2740d7
--- /dev/null
+++ b/docs/specs/ppc-spapr-uv-hcalls.txt
@@ -0,0 +1,76 @@
+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.
+
+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.
+
+== hypercalls needed by the ultravisor ==
+
+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.
+
+- H_TPM_COMM (0xef10)
+
+ 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.
+
+ For TPM_COMM_OP_CLOSE_SESSION operation:
+ Close the existing TPM session, if any.
+
+ Arguments:
+
+ 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.
+
+ Return values:
+
+ 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.
+
+ Use-case/notes:
+
+ 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.
+
+ 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.