NAME

psp — AMD Platform Security Processor

SYNOPSIS

psp* at ccp?

DESCRIPTION

The psp driver provides an interface to the AMD Platform Security Processor. The interface can be accessed through the ioctl(2) interface exposed by /dev/psp.

vmd(8) uses psp to configure and launch SEV-enabled guests.

IOCTL INTERFACE

The ioctl(2) command codes below are defined in <dev/ic/pspvar.h>.

PSP_IOC_GET_PSTATUS struct psp_platform_status *pspst

Collect the current status of the platform.

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;

api_major and api_minor indicate the PSP firmware version.

The current platform state is indicated by state. The following values are defined:

PSP_PSTATE_UNINIT

The platform is uninitialized.

PSP_PSTATE_INIT

The platform is initialized but not managing any guests.

PSP_PSTATE_WORKING

The platform is initialized and currently managing guests.

owner indicates whether the platform is self-owned or externally owned.

Bit 0 of cfgs_build indicates whether SEV-ES is configured on the platform or not. Bits 31:24 indicate the firmware build ID.

guest_count indicates the number of valid guests currently maintained by the firmware.

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 PSP_IOC_DEACTIVATE.

PSP_IOC_DECOMMISSION struct psp_decommission *pspdec

Deletes all guest context of the guest identified by handle.

struct psp_decommission {
	/* Input parameter for PSP_CMD_DECOMMISSION */
	uint32_t		handle;
} __packed;

PSP_IOC_GET_GSTATUS

Retrieves status information about an SEV-enabled guest identified by handle.

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;

policy indicates the policy used for this guest. asid indicates the guest's address space identifier (ASID).

The state of the guest is indicated by state. The following values are defined:

PSP_GSTATE_UNINIT

The guest is uninitialized.

PSP_GSTATE_LUPDATE

The guest is currently being launched and plaintext data is imported.

PSP_GSTATE_LSECRET

The guest is currently being launched and ciphertext data is imported.

PSP_GSTATE_RUNNING

The guest is fully launched.

PSP_GSTATE_SUPDATE

The guest is migrated to another machine.

PSP_GSTATE_RUPDATE

The guest is migrated from another machine.

PSP_GSTATE_SENT

Thee guest has bin migrated to another machine.

PSP_IOC_LAUNCH_START

This command encrypts a guest's memory.

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;

If handle is zero, a new key is created. A unique handle is assigned to the guest and returned in handle.

policy specifies the policy used for that guest.

dh_cert_paddr, dh_cert len, session_paddr and session_len are currently not used.

PSP_IOC_LAUNCH_UPDATE_DATA

This command encrypts data of the guest identified by handle.

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;

paddr and length specify the address and length of the data to be encrypted. Both values must be a multiple of 16 bytes.

PSP_IOC_LAUNCH_MEASURE

This commands generates a measurement of the guest's memory. The guest is identified by handle.

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;

measure_paddr is currently not used and measure_len must always be sizeof(struct psp_measure).

psp_measure contains the buffers measure and measure_nonce. These contain the measurement and nonce generated by the PSP.

PSP_IOC_LAUNCH_FINISH

This command finalizes the launch of the guest identified by handle.

struct psp_launch_finish {
	/* Input parameter for PSP_CMD_LAUNCH_FINISH */
	uint32_t		handle;
} __packed;

PSP_IOC_ATTESTATION

This command generates an attestation report signed by the PSP with a platform specific key.

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;

handle identifies the guest. attest_paddr is currently not used. attest_nonce is the nonce returned by a previous PSP_IOC_LAUNCH_MEASURE command. attest_len must always be sizeof(struct psp_report).

The attestation report is returned in psp_report. The format of the report is defined by struct psp_report.

PSP_IOC_ACTIVATE

This commands associates the context of the guest identified by handle with the address space identifier provided in asid.

struct psp_activate {
	/* Input parameters for PSP_CMD_ACTIVATE */
	uint32_t		handle;
	uint32_t		asid;
} __packed;

PSP_IOC_DEACTIVATE

This command dissociates the context of the guest identified by handle from its current the address space identifier.

struct psp_deactivate {
	/* Input parameter for PSP_CMD_DEACTIVATE */
	uint32_t		handle;
} __packed;

PSP_IOC_SNP_GET_PSTATUS

This command returns the state of a SEV-SNP enabled platform.

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;

PSP_IOC_GUEST_SHUTDOWN

This command shuts down a guest identified by handle.

struct psp_guest_shutdown {
	/* Input parameter for PSP_CMD_GUEST_SHUTDOWN */
	uint32_t		handle;
} __packed;

The command combines PSP_IOC_DEACTIVATE and PSP_IOC_DECOMMISSION in a single ioctl(2) call.

FILES

/dev/psp

 

SEE ALSO

ioctl(2), ccp(4), vmd(8)

Secure Encrypted Virtualization API, Publication #55766.

SEV Secure Nested Paging Firmware ABI Specification, Publication #56860.

HISTORY

The psp device driver first appeared in OpenBSD 7.6.

AUTHORS

The psp driver was written by Hans-Joerg Hoexer <hshoexer@genua.de>.