path: root/share/man/man4/psp.4

.\"	$OpenBSD: psp.4,v 1.3 2024/09/16 22:15:43 bluhm Exp $
.\"
.\" Copyright (c) 2024 Jonathan Gray <jsg@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" 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 16 2024 $
.Dt PSP 4
.Os
.Sh NAME
.Nm psp
.Nd AMD Platform Security Processor
.Sh SYNOPSIS
.Cd "psp* at ccp?"
.Sh DESCRIPTION
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
.%T Secure Encrypted Virtualization API
.%O Publication #55766
.Re
.Rs
.%T SEV Secure Nested Paging Firmware ABI Specification
.%O Publication #56860
.Re
.Sh HISTORY
The
.Nm
device driver first appeared in
.Ox 7.6 .
.Sh AUTHORS
.An -nosplit
The
.Nm
driver was written by
.An Hans-Joerg Hoexer Aq Mt hshoexer@genua.de .