-.\" $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>
.\"
.\" 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
projects / openbsd / commitdiff