From: Mike Larkin Subject: Re: psp.4: document ioctl To: Hans-Jörg Höxer Cc: tech@openbsd.org Date: Mon, 16 Sep 2024 04:36:49 -0700 On Mon, Sep 16, 2024 at 09:20:25AM +0200, Hans-Jörg Höxer wrote: > Hi, > > this diff documents ioctls provided by psp(4). > > Take care, > Hans-Joerg > ok mlarkin > ------------------------------------------------------------------------- > commit ffba4fa588177fb1bec52588d84ab87a2d8b9c4a > Author: Hans-Joerg Hoexer > Date: Thu Sep 12 16:08:35 2024 +0200 > > Document ioctls provided by psp(4) > > diff --git a/share/man/man4/psp.4 b/share/man/man4/psp.4 > index dbe20f3f7ad..a5d1f082635 100644 > --- a/share/man/man4/psp.4 > +++ b/share/man/man4/psp.4 > @@ -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. > +.Pp > +.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. > .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