Document ioctl(2) interface provided by psp(4) device.

from hshoexer@; OK mlarkin@

1 files changed, 321 insertions, 2 deletions

diff --git a/share/man/man4/psp.4 b/share/man/man4/psp.4
index dbe20f3f7ad..7157b81ee34 100644
--- a/share/man/man4/psp.4
+++ b/share/man/man4/psp.4
@@ -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
@@ -26,11 +26,330 @@
 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