From: bluhm Date: Mon, 16 Sep 2024 22:15:43 +0000 (+0000) Subject: Document ioctl(2) interface provided by psp(4) device. X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=29c9965db7fcbc1d35fb1220c7324c6e1a8a4db7;p=openbsd Document ioctl(2) interface provided by psp(4) device. from hshoexer@; OK mlarkin@ --- 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 .\" @@ -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