On Thu, Jul 11, 2019 at 08:19:33PM -0500, Michael Roth wrote:
> 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>

Thanks for adding this documentation.  Is there a PAPR extension
proposal which covers this, which we could cite as the source?

> ---
>  docs/specs/ppc-spapr-uv-hcalls.txt | 74 ++++++++++++++++++++++++++++++
>  1 file changed, 74 insertions(+)
>  create mode 100644 docs/specs/ppc-spapr-uv-hcalls.txt
> 
> diff --git a/docs/specs/ppc-spapr-uv-hcalls.txt b/docs/specs/ppc-spapr-uv-hcalls.txt
> new file mode 100644
> index 0000000000..0278f89190
> --- /dev/null
> +++ b/docs/specs/ppc-spapr-uv-hcalls.txt
> @@ -0,0 +1,74 @@
> +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. 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
> +         - 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   TPM is unavailable
> +    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.

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson