PSP(4)

💅 PSP(4) — AMD Platform Security Processor 💅

okay bestie, welcome to the PSP(4) page from the Kernel Interfaces Manual. it's literally the AMD Platform Security Processor driver, and we're gonna make it make sense. facts stay exactly where they are, vibe is turned all the way up. 🦋

✨ 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. main character energy fr fr. 👑

🔥 IOCTL INTERFACE 🔥

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

---

💅 PSP_IOC_GET_PSTATUS — struct psp_platform_status *pspst

Collects the current status of the platform. it's giving platform vibe check. ✨

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. no skipping this one, bestie. 🧼

💅 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 — The guest has been 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 command 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 command 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 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

okay so like, here's the friend group these docs run with — go say hi bestie 💖

• ioctl(2) — the syscall energy behind all the ioctl stuff up there 🎀
• ccp(4) — sibling driver, same vibes
• vmd(8) — the hypervisor that's out here living its best life

and the literal source material, the receipts, the 📚 if you wanna go deeper:

• Secure Encrypted Virtualization API, Publication #55766.
• SEV Secure Nested Paging Firmware ABI Specification, Publication #56860.

ngl those publication numbers matter — copy them exactly if you're citing, they're the whole point 💅

---

👑 HISTORY

The psp device driver first appeared in OpenBSD 7.6. that's it, that's the origin story — it's giving newcomer-but-make-it-iconic ✨🦋

---

🫶 AUTHORS

The psp driver was written by Hans-Joerg Hoexer <hshoexer@genua.de>. icon behavior, we stan 🙌💜

---

and that's a wrap on the whole page, bestie 🎀 this one came from Debian, dated September 17, 2024, and it's PSP(4) — go forth and ioctl responsibly 💅✨🌸