| Message ID | 243a714d3861f7539d29b02a899ffc376757d668.1642446876.git.lagarcia@br.ibm.com |
|---|---|
| State | New |
| Headers | show |
| Series | rSTify ppc-spapr-uv-hcalls.txt. | expand |
On 1/17/22 16:19, lagarcia@linux.ibm.com wrote: > From: Leonardo Garcia <lagarcia@br.ibm.com> > > Signed-off-by: Leonardo Garcia <lagarcia@br.ibm.com> > --- Reviewed-by: Daniel Henrique Barboza <danielhb413@gmail.com> > docs/specs/ppc-spapr-uv-hcalls.txt | 165 ++++++++++++++++------------- > 1 file changed, 89 insertions(+), 76 deletions(-) > > diff --git a/docs/specs/ppc-spapr-uv-hcalls.txt b/docs/specs/ppc-spapr-uv-hcalls.txt > index 389c2740d7..a00288deb3 100644 > --- a/docs/specs/ppc-spapr-uv-hcalls.txt > +++ b/docs/specs/ppc-spapr-uv-hcalls.txt > @@ -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. > - > -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. > +=================================== > +Hypervisor calls and the Ultravisor > +=================================== > + > +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. > + > +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. > + > +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 of the 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``) > +--------------------------- > + > +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. > + > +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. > + > +Arguments: > + > + ``r3``: ``H_TPM_COMM`` (``0xef10``) > + > + ``r4``: ``TPM`` operation, one of: > + > + ``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. > + > + ``TPM_COMM_OP_CLOSE_SESSION`` (``0x2``): close the existing TPM session, if > + any. > + > + ``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.
diff --git a/docs/specs/ppc-spapr-uv-hcalls.txt b/docs/specs/ppc-spapr-uv-hcalls.txt index 389c2740d7..a00288deb3 100644 --- a/docs/specs/ppc-spapr-uv-hcalls.txt +++ b/docs/specs/ppc-spapr-uv-hcalls.txt @@ -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. - -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. +=================================== +Hypervisor calls and the Ultravisor +=================================== + +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. + +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. + +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 of the 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``) +--------------------------- + +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. + +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. + +Arguments: + + ``r3``: ``H_TPM_COMM`` (``0xef10``) + + ``r4``: ``TPM`` operation, one of: + + ``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. + + ``TPM_COMM_OP_CLOSE_SESSION`` (``0x2``): close the existing TPM session, if + any. + + ``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.