1.. SPDX-License-Identifier: GPL-2.0 2 3Introduction 4============ 5 6The Intel Silicon Security Engine (Intel SSE) is an isolated and 7protected computing resource (Co-processor) residing inside 8Intel client chipsets released in 2024 (Lunar Lake) or later. 9The Intel SSE provide security support and platform boot orchestration. 10The actual feature set depends on the Intel chipset SKU. 11 12The Intel Silicon Security Engine Interface (Intel SSEI) 13is the interface between the Host and Intel SSE. 14This interface is exposed to the host as one or more PCI devices. 15The Intel SSEI Driver is in charge of the communication channel between 16a host application and the Intel SSE features. 17 18Each Intel SSE feature, or Intel SSE Client is addressed by a unique UUID and 19each client has its own protocol. The protocol is message-based with a 20header and payload up to maximal number of bytes advertised by the client, 21upon connection. 22 23Intel SSEI Driver 24================= 25 26The driver exposes a character device with device nodes /dev/isseiX. 27 28An application maintains communication with an Intel SSE feature while 29/dev/isseiX is open. The binding to a specific feature is performed by calling 30:c:macro:`IOCTL_ISSEI_CONNECT_CLIENT`, which passes the desired UUID. 31The number of instances of an Intel SSE feature that can be opened 32at the same time is limited to single instance. 33 34The driver is transparent to data that are passed between firmware feature 35and host application. 36 37Because some of the Intel SSE features can change the system 38configuration, the driver by default allows only a privileged 39user to access it. 40 41The connection termination is performed by calling 42:c:macro:`IOCTL_ISSEI_DISCONNECT_CLIENT`. 43 44The session is terminated calling :c:expr:`close(fd)`. 45 46A code snippet for an application communicating with SPDM client: 47 48.. code-block:: C 49 50 struct issei_connect_client_data data = {.in_client_uuid = 51 {0xe8, 0x51, 0x49, 0xdf, 0x94, 0x47, 0x4C, 52 0x9A, 0x83, 0x67, 0xC4, 0xE3, 0x34, 0x64, 0xF1, 0xB4}}; 53 __u8 req_data[] = {0x10, 0x84, 0x00, 0x00}; /* SPDM Get Version */ 54 size_t req_data_len = sizeof(req_data); 55 __u8 res_data[256]; 56 size_t res_data_len = sizeof(res_data); 57 int fd = open("/dev/issei0", O_RDWR); 58 59 ioctl(fd, IOCTL_ISSEI_CONNECT_CLIENT, &data); 60 61 printf("Ver=%d, MaxLen=%u, Flags=0x%08X\n", 62 data.out_client_properties.protocol_version, 63 data.out_client_properties.max_msg_length, 64 data.out_client_properties.flags); 65 66 [...] 67 68 write(fd, req_data, req_data_len); 69 70 [...] 71 72 read(fd, res_data, res_data_len); 73 74 printf("SPDM version count %u, version[0]=%02X%02X\n", 75 res_data[5], res_data[6], res_data[7]); 76 77 [...] 78 79 ioctl(fd, IOCTL_ISSEI_DISCONNECT_CLIENT, &data); 80 81 [...] 82 83 close(fd); 84 85 86User space API ioctl 87==================== 88 89The Intel SSEI Driver supports the following ioctl commands: 90 91IOCTL_ISSEI_CONNECT_CLIENT 92-------------------------- 93Connect to firmware Feature/Client. 94 95.. code-block:: none 96 97 Usage: 98 99 struct issei_connect_client_data client_data; 100 101 ioctl(fd, IOCTL_ISSEI_CONNECT_CLIENT, &client_data); 102 103 struct issei_connect_client_data - contain the following 104 Inputs: 105 in_client_uuid - UUID of the FW Feature that needs to connect to. 106 Outputs: 107 out_client_properties - Client Properties: MTU, Protocol Version and Flags. 108 109 Error returns: 110 ENOTTY No such client (i.e. wrong UUID) or connection is not allowed. 111 EINVAL Wrong IOCTL Number 112 ENODEV Device or Connection is not initialized or ready. 113 ENOMEM Unable to allocate memory to client internal data. 114 EFAULT Fatal Error (e.g. Unable to access user input data) 115 EBUSY Connection Already Open 116 117:Note: 118 max_msg_length (MTU) in client properties describes the maximum 119 data that can be sent or received. (e.g. with MTU=2K, can send 120 requests up to bytes 2k and received responses up to 2k bytes). 121 122IOCTL_ISSEI_DISCONNECT_CLIENT 123----------------------------- 124Disconnect from firmware Feature/Client. 125 126.. code-block:: none 127 128 Usage: 129 130 ioctl(fd, IOCTL_ISSEI_DISCONNECT_CLIENT, NULL); 131 132 Error returns: 133 EINVAL Wrong IOCTL Number 134 ENODEV Device or Connection is not initialized or ready. 135 ENOTCONN Feature/Client is not connected. 136