Document ioctl(2) interface provided by psp(4) device.
authorbluhm <bluhm@openbsd.org>
Mon, 16 Sep 2024 22:15:43 +0000 (22:15 +0000)
committerbluhm <bluhm@openbsd.org>
Mon, 16 Sep 2024 22:15:43 +0000 (22:15 +0000)
from hshoexer@; OK mlarkin@

share/man/man4/psp.4

index dbe20f3..7157b81 100644 (file)
@@ -1,4 +1,4 @@
-.\"    $OpenBSD: psp.4,v 1.2 2024/09/04 14:24:10 jsg Exp $
+.\"    $OpenBSD: psp.4,v 1.3 2024/09/16 22:15:43 bluhm Exp $
 .\"
 .\" Copyright (c) 2024 Jonathan Gray <jsg@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: September 4 2024 $
+.Dd $Mdocdate: September 16 2024 $
 .Dt PSP 4
 .Os
 .Sh NAME
 The
 .Nm
 driver provides an interface to the AMD Platform Security Processor.
+The interface can be accessed through the
+.Xr ioctl 2
+interface exposed by
+.Pa /dev/psp .
+.Pp
+.Xr vmd 8
+uses
+.Nm
+to configure and launch SEV-enabled guests.
+.Sh IOCTL INTERFACE
+The
+.Xr ioctl 2
+command codes below are defined in
+.In dev/ic/pspvar.h .
+.Bl -tag -width xxxxxx
+.It Dv PSP_IOC_GET_PSTATUS  Fa "struct psp_platform_status *pspst"
+Collect the current status of the platform.
+.Bd -literal
+struct psp_platform_status {
+       /* Output parameters from PSP_CMD_PLATFORMSTATUS */
+       uint8_t                 api_major;
+       uint8_t                 api_minor;
+       uint8_t                 state;
+       uint8_t                 owner;
+       uint32_t                cfges_build;
+       uint32_t                guest_count;
+} __packed;
+.Ed
+.Pp
+.Va api_major
+and
+.Va api_minor
+indicate the PSP firmware version.
+.Pp
+The current platform state is indicated by
+.Va state .
+The following values are defined:
+.Bl -tag -width PSP_PSTATE_WORKING -compact
+.It PSP_PSTATE_UNINIT
+The platform is uninitialized.
+.It PSP_PSTATE_INIT
+The platform is initialized but not managing any guests.
+.It PSP_PSTATE_WORKING
+The platform is initialized and currently managing guests.
+.El
+.Pp
+.Va owner
+indicates whether the platform is self-owned or externally owned.
+.Pp
+Bit 0 of
+.Va cfgs_build
+indicates whether SEV-ES is configured on the platform or not.
+Bits 31:24 indicate the firmware build ID.
+.Pp
+.Va guest_count
+indicates the number of valid guests currently maintained by the
+firmware.
+.It Dv PSP_IOC_DF_FLUSH
+This command flushes all write buffers of the CPU's data fabric.
+It must be invoked after deactivating one or more guests with
+.Dv PSP_IOC_DEACTIVATE .
+.It Dv PSP_IOC_DECOMMISSION Fa "struct psp_decommission *pspdec"
+Deletes all guest context of the guest identified by
+.Va handle .
+.Bd -literal
+struct psp_decommission {
+       /* Input parameter for PSP_CMD_DECOMMISSION */
+       uint32_t                handle;
+} __packed;
+.Ed
+.It Dv PSP_IOC_GET_GSTATUS
+Retrieves status information about an SEV-enabled guest identified by
+.Va handle .
+.Bd -literal
+struct psp_guest_status {
+       /* Input parameter for PSP_CMD_GUESTSTATUS */
+       uint32_t                handle;
+
+       /* Output parameters from PSP_CMD_GUESTSTATUS */
+       uint32_t                policy;
+       uint32_t                asid;
+       uint8_t                 state;
+} __packed;
+.Ed
+.Pp
+.Va policy
+indicates the policy used for this guest.
+.Va asid
+indicates the guest's address space identifier (ASID).
+.Pp
+The state of the guest is inidcated by
+.Va state .
+The following values are defined:
+.Bl -tag -width PSP_GSTATE_RUNNING -compact
+.It PSP_GSTATE_UNINIT
+The guest is unitialized.
+.It PSP_GSTATE_LUPDATE
+The guest is currently being launched and plaintext data is imported.
+.It PSP_GSTATE_LSECRET
+The guest is currently being launched and ciphertext data is imported.
+.It PSP_GSTATE_RUNNING
+The guest is fully launched.
+.It PSP_GSTATE_SUPDATE
+The guest is migrated to another machine.
+.It PSP_GSTATE_RUPDATE
+The guest is migrated from another machine.
+.It PSP_GSTATE_SENT
+Thee guest has bin migrated to another machine.
+.El
+.It Dv PSP_IOC_LAUNCH_START
+This command encrypts a guest's memory.
+.Bd -literal
+struct psp_launch_start {
+       /* Input/Output parameter for PSP_CMD_LAUNCH_START */
+       uint32_t                handle;
+
+       /* Input parameters for PSP_CMD_LAUNCH_START */
+       uint32_t                policy;
+
+       /* The following input parameters are not used yet */
+       uint64_t                dh_cert_paddr;
+       uint32_t                dh_cert_len;
+       uint32_t                reserved;
+       uint64_t                session_paddr;
+       uint32_t                session_len;
+} __packed;
+.Ed
+.Pp
+If
+.Va handle
+is zero, a new key is created.
+A unique handle is assigned to the guest and returned in
+.Va handle .
+.Pp
+.Va policy
+specifies the policy used for that guest.
+.Pp
+.Va dh_cert_paddr ,
+.Va dh_cert len ,
+.Va session_paddr
+and
+.Va session_len
+are currently not used.
+.It Dv PSP_IOC_LAUNCH_UPDATE_DATA
+This command encrypts data of the guest identified by
+.Va handle .
+.Bd -literal
+struct psp_launch_update_data {
+       /* Input parameters for PSP_CMD_LAUNCH_UPDATE_DATA */
+       uint32_t                handle;
+       uint32_t                reserved;
+       uint64_t                paddr;
+       uint32_t                length;
+} __packed;
+.Ed
+.Pp
+.Va paddr
+and
+.Va length
+specify the address and length of the data to be encrypted.
+Both values must be a multiple of 16 bytes.
+.It Dv PSP_IOC_LAUNCH_MEASURE
+This commands generates a measurement of the guest's memory.
+The guest is identified by
+.Va handle .
+.Bd -literal
+struct psp_measure {
+       /* Output buffer for PSP_CMD_LAUNCH_MEASURE */
+       uint8_t                 measure[32];
+       uint8_t                 measure_nonce[16];
+} __packed;
+
+struct psp_launch_measure {
+       /* Input parameters for PSP_CMD_LAUNCH_MEASURE */
+       uint32_t                handle;
+       uint32_t                reserved;
+       uint64_t                measure_paddr;
+
+       /* Input/output parameter for PSP_CMD_LAUNCH_MEASURE */
+       uint32_t                measure_len;
+       uint32_t                padding;
+
+       /* Output buffer from PSP_CMD_LAUNCH_MEASURE */
+       struct psp_measure      psp_measure;    /* 64bit aligned */
+#define measure                psp_measure.measure
+#define measure_nonce  psp_measure.measure_nonce
+} __packed;
+.Ed
+.Pp
+.Va measure_paddr
+is currently not used and
+.Va measure_len
+must always be
+.Li sizeof(struct psp_measure) .
+.Pp
+.Va psp_measure
+contains the buffers
+.Va measure
+and
+.Va measure_nonce .
+These contain the measurment and nonce generated by the PSP.
+.It Dv PSP_IOC_LAUNCH_FINISH
+This command finalizes the launch of the guest identified by
+.Va handle .
+.Bd -literal
+struct psp_launch_finish {
+       /* Input parameter for PSP_CMD_LAUNCH_FINISH */
+       uint32_t                handle;
+} __packed;
+.Ed
+.It Dv PSP_IOC_ATTESTATION
+This command generates an attestation report signed by the PSP with
+a platform specific key.
+.Bd -literal
+struct psp_report {
+       /* Output buffer for PSP_CMD_ATTESTATION */
+       uint8_t                 report_nonce[16];
+       uint8_t                 report_launch_digest[32];
+       uint32_t                report_policy;
+       uint32_t                report_sig_usage;
+       uint32_t                report_sig_algo;
+       uint32_t                reserved2;
+       uint8_t                 report_sig1[144];
+} __packed;
+
+struct psp_attestation {
+       /* Input parameters for PSP_CMD_ATTESTATION */
+       uint32_t                handle;
+       uint32_t                reserved;
+       uint64_t                attest_paddr;
+       uint8_t                 attest_nonce[16];
+
+       /* Input/output parameter from PSP_CMD_ATTESTATION */
+       uint32_t                attest_len;
+       uint32_t                padding;
+
+       /* Output parameter from PSP_CMD_ATTESTATION */
+       struct psp_report       psp_report;     /* 64bit aligned */
+#define report_nonce           psp_report.report_nonce
+#define report_launch_digest   psp_report.report_launch_digest
+#define report_policy          psp_report.report_policy
+#define report_sig_usage       psp_report.report_sig_usage;
+#define report_report_sig_alg  psp_report.report_sig_algo;
+#define report_report_sig1     psp_report.report_sig1;
+} __packed;
+.Ed
+.Pp
+.Va handle
+identifies the guest.
+.Va attest_paddr
+is currently not used.
+.Va attest_nonce
+is the nonce returned by a previous
+.Dv PSP_IOC_LAUNCH_MEASURE
+command.
+.Va attest_len
+must always be
+.Li sizeof(struct psp_report) .
+.Pp
+The attestation report is returned in
+.Va psp_report .
+The format of the report is defined by
+.Li struct psp_report .
+.It Dv PSP_IOC_ACTIVATE
+This commands associates the context of the guest identified by
+.Va handle
+with the address space identifier provided in
+.Va asid .
+.Bd -literal
+struct psp_activate {
+       /* Input parameters for PSP_CMD_ACTIVATE */
+       uint32_t                handle;
+       uint32_t                asid;
+} __packed;
+.Ed
+.It Dv PSP_IOC_DEACTIVATE
+This command dissociates the context of the guest identified by
+.Va handle
+from its current the address space identifier.
+.Bd -literal
+struct psp_deactivate {
+       /* Input parameter for PSP_CMD_DEACTIVATE */
+       uint32_t                handle;
+} __packed;
+.Ed
+.It Dv PSP_IOC_SNP_GET_PSTATUS
+This command returns the state of a SEV-SNP enabled platform.
+.Bd -literal
+struct psp_snp_platform_status {
+       uint8_t                 api_major;
+       uint8_t                 api_minor;
+       uint8_t                 state;
+       uint8_t                 is_rmp_init;
+       uint32_t                build;
+       uint32_t                features;
+       uint32_t                guest_count;
+       uint64_t                current_tcb;
+       uint64_t                reported_tcb;
+} __packed;
+.Ed
+.It Dv PSP_IOC_GUEST_SHUTDOWN
+This command shuts down a guest identified by
+.Va handle .
+.Bd -literal
+struct psp_guest_shutdown {
+       /* Input parameter for PSP_CMD_GUEST_SHUTDOWN */
+       uint32_t                handle;
+} __packed;
+.Ed
+.Pp
+The command combines
+.Dv PSP_IOC_DEACTIVATE
+and
+.Dv PSP_IOC_DECOMMISSION
+in a single
+.Xr ioctl 2
+call.
+.El
 .Sh FILES
 .Bl -tag -width /dev/psp
 .It Pa /dev/psp
 .El
 .Sh SEE ALSO
+.Xr ioctl 2 ,
 .Xr ccp 4 ,
 .Xr vmd 8
 .Rs