1.\" $OpenBSD: psp.4,v 1.4 2024/09/17 04:12:57 jsg Exp $ 2.\" 3.\" Copyright (c) 2024 Jonathan Gray <jsg@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: September 17 2024 $ 18.Dt PSP 4 19.Os 20.Sh NAME 21.Nm psp 22.Nd AMD Platform Security Processor 23.Sh SYNOPSIS 24.Cd "psp* at ccp?" 25.Sh DESCRIPTION 26The 27.Nm 28driver provides an interface to the AMD Platform Security Processor. 29The interface can be accessed through the 30.Xr ioctl 2 31interface exposed by 32.Pa /dev/psp . 33.Pp 34.Xr vmd 8 35uses 36.Nm 37to configure and launch SEV-enabled guests. 38.Sh IOCTL INTERFACE 39The 40.Xr ioctl 2 41command codes below are defined in 42.In dev/ic/pspvar.h . 43.Bl -tag -width xxxxxx 44.It Dv PSP_IOC_GET_PSTATUS Fa "struct psp_platform_status *pspst" 45Collect the current status of the platform. 46.Bd -literal 47struct psp_platform_status { 48 /* Output parameters from PSP_CMD_PLATFORMSTATUS */ 49 uint8_t api_major; 50 uint8_t api_minor; 51 uint8_t state; 52 uint8_t owner; 53 uint32_t cfges_build; 54 uint32_t guest_count; 55} __packed; 56.Ed 57.Pp 58.Va api_major 59and 60.Va api_minor 61indicate the PSP firmware version. 62.Pp 63The current platform state is indicated by 64.Va state . 65The following values are defined: 66.Bl -tag -width PSP_PSTATE_WORKING -compact 67.It PSP_PSTATE_UNINIT 68The platform is uninitialized. 69.It PSP_PSTATE_INIT 70The platform is initialized but not managing any guests. 71.It PSP_PSTATE_WORKING 72The platform is initialized and currently managing guests. 73.El 74.Pp 75.Va owner 76indicates whether the platform is self-owned or externally owned. 77.Pp 78Bit 0 of 79.Va cfgs_build 80indicates whether SEV-ES is configured on the platform or not. 81Bits 31:24 indicate the firmware build ID. 82.Pp 83.Va guest_count 84indicates the number of valid guests currently maintained by the 85firmware. 86.It Dv PSP_IOC_DF_FLUSH 87This command flushes all write buffers of the CPU's data fabric. 88It must be invoked after deactivating one or more guests with 89.Dv PSP_IOC_DEACTIVATE . 90.It Dv PSP_IOC_DECOMMISSION Fa "struct psp_decommission *pspdec" 91Deletes all guest context of the guest identified by 92.Va handle . 93.Bd -literal 94struct psp_decommission { 95 /* Input parameter for PSP_CMD_DECOMMISSION */ 96 uint32_t handle; 97} __packed; 98.Ed 99.It Dv PSP_IOC_GET_GSTATUS 100Retrieves status information about an SEV-enabled guest identified by 101.Va handle . 102.Bd -literal 103struct psp_guest_status { 104 /* Input parameter for PSP_CMD_GUESTSTATUS */ 105 uint32_t handle; 106 107 /* Output parameters from PSP_CMD_GUESTSTATUS */ 108 uint32_t policy; 109 uint32_t asid; 110 uint8_t state; 111} __packed; 112.Ed 113.Pp 114.Va policy 115indicates the policy used for this guest. 116.Va asid 117indicates the guest's address space identifier (ASID). 118.Pp 119The state of the guest is indicated by 120.Va state . 121The following values are defined: 122.Bl -tag -width PSP_GSTATE_RUNNING -compact 123.It PSP_GSTATE_UNINIT 124The guest is uninitialized. 125.It PSP_GSTATE_LUPDATE 126The guest is currently being launched and plaintext data is imported. 127.It PSP_GSTATE_LSECRET 128The guest is currently being launched and ciphertext data is imported. 129.It PSP_GSTATE_RUNNING 130The guest is fully launched. 131.It PSP_GSTATE_SUPDATE 132The guest is migrated to another machine. 133.It PSP_GSTATE_RUPDATE 134The guest is migrated from another machine. 135.It PSP_GSTATE_SENT 136Thee guest has bin migrated to another machine. 137.El 138.It Dv PSP_IOC_LAUNCH_START 139This command encrypts a guest's memory. 140.Bd -literal 141struct psp_launch_start { 142 /* Input/Output parameter for PSP_CMD_LAUNCH_START */ 143 uint32_t handle; 144 145 /* Input parameters for PSP_CMD_LAUNCH_START */ 146 uint32_t policy; 147 148 /* The following input parameters are not used yet */ 149 uint64_t dh_cert_paddr; 150 uint32_t dh_cert_len; 151 uint32_t reserved; 152 uint64_t session_paddr; 153 uint32_t session_len; 154} __packed; 155.Ed 156.Pp 157If 158.Va handle 159is zero, a new key is created. 160A unique handle is assigned to the guest and returned in 161.Va handle . 162.Pp 163.Va policy 164specifies the policy used for that guest. 165.Pp 166.Va dh_cert_paddr , 167.Va dh_cert len , 168.Va session_paddr 169and 170.Va session_len 171are currently not used. 172.It Dv PSP_IOC_LAUNCH_UPDATE_DATA 173This command encrypts data of the guest identified by 174.Va handle . 175.Bd -literal 176struct psp_launch_update_data { 177 /* Input parameters for PSP_CMD_LAUNCH_UPDATE_DATA */ 178 uint32_t handle; 179 uint32_t reserved; 180 uint64_t paddr; 181 uint32_t length; 182} __packed; 183.Ed 184.Pp 185.Va paddr 186and 187.Va length 188specify the address and length of the data to be encrypted. 189Both values must be a multiple of 16 bytes. 190.It Dv PSP_IOC_LAUNCH_MEASURE 191This commands generates a measurement of the guest's memory. 192The guest is identified by 193.Va handle . 194.Bd -literal 195struct psp_measure { 196 /* Output buffer for PSP_CMD_LAUNCH_MEASURE */ 197 uint8_t measure[32]; 198 uint8_t measure_nonce[16]; 199} __packed; 200 201struct psp_launch_measure { 202 /* Input parameters for PSP_CMD_LAUNCH_MEASURE */ 203 uint32_t handle; 204 uint32_t reserved; 205 uint64_t measure_paddr; 206 207 /* Input/output parameter for PSP_CMD_LAUNCH_MEASURE */ 208 uint32_t measure_len; 209 uint32_t padding; 210 211 /* Output buffer from PSP_CMD_LAUNCH_MEASURE */ 212 struct psp_measure psp_measure; /* 64bit aligned */ 213#define measure psp_measure.measure 214#define measure_nonce psp_measure.measure_nonce 215} __packed; 216.Ed 217.Pp 218.Va measure_paddr 219is currently not used and 220.Va measure_len 221must always be 222.Li sizeof(struct psp_measure) . 223.Pp 224.Va psp_measure 225contains the buffers 226.Va measure 227and 228.Va measure_nonce . 229These contain the measurement and nonce generated by the PSP. 230.It Dv PSP_IOC_LAUNCH_FINISH 231This command finalizes the launch of the guest identified by 232.Va handle . 233.Bd -literal 234struct psp_launch_finish { 235 /* Input parameter for PSP_CMD_LAUNCH_FINISH */ 236 uint32_t handle; 237} __packed; 238.Ed 239.It Dv PSP_IOC_ATTESTATION 240This command generates an attestation report signed by the PSP with 241a platform specific key. 242.Bd -literal 243struct psp_report { 244 /* Output buffer for PSP_CMD_ATTESTATION */ 245 uint8_t report_nonce[16]; 246 uint8_t report_launch_digest[32]; 247 uint32_t report_policy; 248 uint32_t report_sig_usage; 249 uint32_t report_sig_algo; 250 uint32_t reserved2; 251 uint8_t report_sig1[144]; 252} __packed; 253 254struct psp_attestation { 255 /* Input parameters for PSP_CMD_ATTESTATION */ 256 uint32_t handle; 257 uint32_t reserved; 258 uint64_t attest_paddr; 259 uint8_t attest_nonce[16]; 260 261 /* Input/output parameter from PSP_CMD_ATTESTATION */ 262 uint32_t attest_len; 263 uint32_t padding; 264 265 /* Output parameter from PSP_CMD_ATTESTATION */ 266 struct psp_report psp_report; /* 64bit aligned */ 267#define report_nonce psp_report.report_nonce 268#define report_launch_digest psp_report.report_launch_digest 269#define report_policy psp_report.report_policy 270#define report_sig_usage psp_report.report_sig_usage; 271#define report_report_sig_alg psp_report.report_sig_algo; 272#define report_report_sig1 psp_report.report_sig1; 273} __packed; 274.Ed 275.Pp 276.Va handle 277identifies the guest. 278.Va attest_paddr 279is currently not used. 280.Va attest_nonce 281is the nonce returned by a previous 282.Dv PSP_IOC_LAUNCH_MEASURE 283command. 284.Va attest_len 285must always be 286.Li sizeof(struct psp_report) . 287.Pp 288The attestation report is returned in 289.Va psp_report . 290The format of the report is defined by 291.Li struct psp_report . 292.It Dv PSP_IOC_ACTIVATE 293This commands associates the context of the guest identified by 294.Va handle 295with the address space identifier provided in 296.Va asid . 297.Bd -literal 298struct psp_activate { 299 /* Input parameters for PSP_CMD_ACTIVATE */ 300 uint32_t handle; 301 uint32_t asid; 302} __packed; 303.Ed 304.It Dv PSP_IOC_DEACTIVATE 305This command dissociates the context of the guest identified by 306.Va handle 307from its current the address space identifier. 308.Bd -literal 309struct psp_deactivate { 310 /* Input parameter for PSP_CMD_DEACTIVATE */ 311 uint32_t handle; 312} __packed; 313.Ed 314.It Dv PSP_IOC_SNP_GET_PSTATUS 315This command returns the state of a SEV-SNP enabled platform. 316.Bd -literal 317struct psp_snp_platform_status { 318 uint8_t api_major; 319 uint8_t api_minor; 320 uint8_t state; 321 uint8_t is_rmp_init; 322 uint32_t build; 323 uint32_t features; 324 uint32_t guest_count; 325 uint64_t current_tcb; 326 uint64_t reported_tcb; 327} __packed; 328.Ed 329.It Dv PSP_IOC_GUEST_SHUTDOWN 330This command shuts down a guest identified by 331.Va handle . 332.Bd -literal 333struct psp_guest_shutdown { 334 /* Input parameter for PSP_CMD_GUEST_SHUTDOWN */ 335 uint32_t handle; 336} __packed; 337.Ed 338.Pp 339The command combines 340.Dv PSP_IOC_DEACTIVATE 341and 342.Dv PSP_IOC_DECOMMISSION 343in a single 344.Xr ioctl 2 345call. 346.El 347.Sh FILES 348.Bl -tag -width /dev/psp 349.It Pa /dev/psp 350.El 351.Sh SEE ALSO 352.Xr ioctl 2 , 353.Xr ccp 4 , 354.Xr vmd 8 355.Rs 356.%T Secure Encrypted Virtualization API 357.%O Publication #55766 358.Re 359.Rs 360.%T SEV Secure Nested Paging Firmware ABI Specification 361.%O Publication #56860 362.Re 363.Sh HISTORY 364The 365.Nm 366device driver first appeared in 367.Ox 7.6 . 368.Sh AUTHORS 369.An -nosplit 370The 371.Nm 372driver was written by 373.An Hans-Joerg Hoexer Aq Mt hshoexer@genua.de . 374