]>
Commit | Line | Data |
---|---|---|
aa4db5b1 JY |
1 | /** @file\r |
2 | Device Security Protocol definition.\r | |
3 | \r | |
4 | It is used to authenticate a device based upon the platform policy.\r | |
5 | It is similar to the EFI_SECURITY_ARCH_PROTOCOL, which is used to verify a image.\r | |
6 | \r | |
7 | Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>\r | |
8 | SPDX-License-Identifier: BSD-2-Clause-Patent\r | |
9 | \r | |
10 | **/\r | |
11 | \r | |
12 | \r | |
13 | #ifndef __DEVICE_SECURITY_H__\r | |
14 | #define __DEVICE_SECURITY_H__\r | |
15 | \r | |
16 | //\r | |
17 | // Device Security Protocol GUID value\r | |
18 | //\r | |
19 | #define EDKII_DEVICE_SECURITY_PROTOCOL_GUID \\r | |
20 | { \\r | |
21 | 0x5d6b38c8, 0x5510, 0x4458, { 0xb4, 0x8d, 0x95, 0x81, 0xcf, 0xa7, 0xb0, 0xd } \\r | |
22 | }\r | |
23 | \r | |
24 | //\r | |
25 | // Forward reference for pure ANSI compatability\r | |
26 | //\r | |
27 | typedef struct _EDKII_DEVICE_SECURITY_PROTOCOL EDKII_DEVICE_SECURITY_PROTOCOL;\r | |
28 | \r | |
29 | //\r | |
30 | // Revision The revision to which the DEVICE_SECURITY interface adheres.\r | |
31 | // All future revisions must be backwards compatible.\r | |
32 | // If a future version is not back wards compatible it is not the same GUID.\r | |
33 | //\r | |
34 | #define EDKII_DEVICE_SECURITY_PROTOCOL_REVISION 0x00010000\r | |
35 | \r | |
36 | //\r | |
37 | // The device identifier.\r | |
38 | //\r | |
39 | typedef struct {\r | |
40 | ///\r | |
41 | /// Version of this data structure.\r | |
42 | ///\r | |
43 | UINT32 Version;\r | |
44 | ///\r | |
45 | /// Type of the device.\r | |
46 | /// This field is also served as a device Access protocol GUID.\r | |
47 | /// The device access protocol is installed on the DeviceHandle.\r | |
48 | /// The device access protocol is device specific.\r | |
49 | /// EDKII_DEVICE_IDENTIFIER_TYPE_PCI_GUID means the device access protocol is PciIo.\r | |
50 | /// EDKII_DEVICE_IDENTIFIER_TYPE_USB_GUID means the device access protocol is UsbIo.\r | |
51 | ///\r | |
52 | EFI_GUID DeviceType;\r | |
53 | ///\r | |
54 | /// The handle created for this device.\r | |
55 | /// NOTE: This might be a temporary handle.\r | |
56 | /// If the device is not authenticated, this handle shall be uninstalled.\r | |
57 | ///\r | |
58 | /// As minimal requirement, there should be 2 protocols installed on the device handle.\r | |
59 | /// 1) An EFI_DEVICE_PATH_PROTOCOL with EFI_DEVICE_PATH_PROTOCOL_GUID.\r | |
60 | /// 2) A device access protocol with EDKII_DEVICE_IDENTIFIER_TYPE_xxx_GUID.\r | |
61 | /// If the device is PCI device, the EFI_PCI_IO_PROTOCOL is installed with\r | |
62 | /// EDKII_DEVICE_IDENTIFIER_TYPE_PCI_GUID.\r | |
63 | /// If the device is USB device, the EFI_USB_IO_PROTOCOL is installed with\r | |
64 | /// EDKII_DEVICE_IDENTIFIER_TYPE_USB_GUID.\r | |
65 | ///\r | |
66 | /// The device access protocol is required, because the verifier need have a way\r | |
67 | /// to communciate with the device hardware to get the measurement or do the\r | |
68 | /// challenge/response for the device authentication.\r | |
69 | ///\r | |
70 | /// NOTE: We don't use EFI_PCI_IO_PROTOCOL_GUID or EFI_USB_IO_PROTOCOL_GUID here,\r | |
71 | /// because we don't want to expose a real protocol. A platform may have driver\r | |
72 | /// register a protocol notify function. Installing a real protocol may cause\r | |
73 | /// the callback function being executed before the device is authenticated.\r | |
74 | ///\r | |
75 | EFI_HANDLE DeviceHandle;\r | |
76 | } EDKII_DEVICE_IDENTIFIER;\r | |
77 | \r | |
78 | //\r | |
79 | // Revision The revision to which the DEVICE_IDENTIFIER interface adheres.\r | |
80 | // All future revisions must be backwards compatible.\r | |
81 | //\r | |
82 | #define EDKII_DEVICE_IDENTIFIER_REVISION 0x00010000\r | |
83 | \r | |
84 | //\r | |
85 | // Device Identifier GUID value\r | |
86 | //\r | |
87 | #define EDKII_DEVICE_IDENTIFIER_TYPE_PCI_GUID \\r | |
88 | { \\r | |
89 | 0x2509b2f1, 0xa022, 0x4cca, { 0xaf, 0x70, 0xf9, 0xd3, 0x21, 0xfb, 0x66, 0x49 } \\r | |
90 | }\r | |
91 | \r | |
92 | #define EDKII_DEVICE_IDENTIFIER_TYPE_USB_GUID \\r | |
93 | { \\r | |
94 | 0x7394f350, 0x394d, 0x488c, { 0xbb, 0x75, 0xc, 0xab, 0x7b, 0x12, 0xa, 0xc5 } \\r | |
95 | }\r | |
96 | \r | |
97 | /**\r | |
98 | The device driver uses this service to measure and/or verify a device.\r | |
99 | \r | |
100 | The flow in device driver is:\r | |
101 | 1) Device driver discovers a new device.\r | |
102 | 2) Device driver creates an EFI_DEVICE_PATH_PROTOCOL.\r | |
103 | 3) Device driver creates a device access protocol. e.g.\r | |
104 | EFI_PCI_IO_PROTOCOL for PCI device.\r | |
105 | EFI_USB_IO_PROTOCOL for USB device.\r | |
106 | EFI_EXT_SCSI_PASS_THRU_PROTOCOL for SCSI device.\r | |
107 | EFI_ATA_PASS_THRU_PROTOCOL for ATA device.\r | |
108 | EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL for NVMe device.\r | |
109 | EFI_SD_MMC_PASS_THRU_PROTOCOL for SD/MMC device.\r | |
110 | 4) Device driver installs the EFI_DEVICE_PATH_PROTOCOL with EFI_DEVICE_PATH_PROTOCOL_GUID,\r | |
111 | and the device access protocol with EDKII_DEVICE_IDENTIFIER_TYPE_xxx_GUID.\r | |
112 | Once it is done, a DeviceHandle is returned.\r | |
113 | 5) Device driver creates EDKII_DEVICE_IDENTIFIER with EDKII_DEVICE_IDENTIFIER_TYPE_xxx_GUID\r | |
114 | and the DeviceHandle.\r | |
115 | 6) Device driver calls DeviceAuthenticate().\r | |
116 | 7) If DeviceAuthenticate() returns EFI_SECURITY_VIOLATION, the device driver uninstalls\r | |
117 | all protocols on this handle.\r | |
118 | 8) If DeviceAuthenticate() returns EFI_SUCCESS, the device driver installs the device access\r | |
119 | protocol with a real protocol GUID. e.g.\r | |
120 | EFI_PCI_IO_PROTOCOL with EFI_PCI_IO_PROTOCOL_GUID.\r | |
121 | EFI_USB_IO_PROTOCOL with EFI_USB_IO_PROTOCOL_GUID.\r | |
122 | \r | |
123 | @param[in] This The protocol instance pointer.\r | |
124 | @param[in] DeviceId The Identifier for the device.\r | |
125 | \r | |
126 | @retval EFI_SUCCESS The device specified by the DeviceId passed the measurement\r | |
127 | and/or authentication based upon the platform policy.\r | |
128 | If TCG measurement is required, the measurement is extended to TPM PCR.\r | |
129 | @retval EFI_SECURITY_VIOLATION The device fails to return the measurement data.\r | |
130 | @retval EFI_SECURITY_VIOLATION The device fails to response the authentication request.\r | |
131 | @retval EFI_SECURITY_VIOLATION The system fails to verify the device based upon the authentication response.\r | |
132 | @retval EFI_SECURITY_VIOLATION The system fails to extend the measurement to TPM PCR.\r | |
133 | **/\r | |
134 | typedef\r | |
135 | EFI_STATUS\r | |
136 | (EFIAPI *EDKII_DEVICE_AUTHENTICATE)(\r | |
137 | IN EDKII_DEVICE_SECURITY_PROTOCOL *This,\r | |
138 | IN EDKII_DEVICE_IDENTIFIER *DeviceId\r | |
139 | );\r | |
140 | \r | |
141 | ///\r | |
142 | /// Device Security Protocol structure.\r | |
143 | /// It is similar to the EFI_SECURITY_ARCH_PROTOCOL, which is used to verify a image.\r | |
144 | /// This protocol is used to authenticate a device based upon the platform policy.\r | |
145 | ///\r | |
146 | struct _EDKII_DEVICE_SECURITY_PROTOCOL {\r | |
147 | UINT64 Revision;\r | |
148 | EDKII_DEVICE_AUTHENTICATE DeviceAuthenticate;\r | |
149 | };\r | |
150 | \r | |
151 | ///\r | |
152 | /// Device Security Protocol GUID variable.\r | |
153 | ///\r | |
154 | extern EFI_GUID gEdkiiDeviceSecurityProtocolGuid;\r | |
155 | \r | |
156 | ///\r | |
157 | /// Device Identifier tpye GUID variable.\r | |
158 | ///\r | |
159 | extern EFI_GUID gEdkiiDeviceIdentifierTypePciGuid;\r | |
160 | extern EFI_GUID gEdkiiDeviceIdentifierTypeUsbGuid;\r | |
161 | \r | |
162 | #endif\r |