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