--- /dev/null
+/** @file\r
+ Device Security Protocol definition.\r
+\r
+ It is used to authenticate a device based upon the platform policy.\r
+ It is similar to the EFI_SECURITY_ARCH_PROTOCOL, which is used to verify a image.\r
+\r
+Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>\r
+SPDX-License-Identifier: BSD-2-Clause-Patent\r
+\r
+**/\r
+\r
+\r
+#ifndef __DEVICE_SECURITY_H__\r
+#define __DEVICE_SECURITY_H__\r
+\r
+//\r
+// Device Security Protocol GUID value\r
+//\r
+#define EDKII_DEVICE_SECURITY_PROTOCOL_GUID \\r
+ { \\r
+ 0x5d6b38c8, 0x5510, 0x4458, { 0xb4, 0x8d, 0x95, 0x81, 0xcf, 0xa7, 0xb0, 0xd } \\r
+ }\r
+\r
+//\r
+// Forward reference for pure ANSI compatability\r
+//\r
+typedef struct _EDKII_DEVICE_SECURITY_PROTOCOL EDKII_DEVICE_SECURITY_PROTOCOL;\r
+\r
+//\r
+// Revision The revision to which the DEVICE_SECURITY interface adheres.\r
+// All future revisions must be backwards compatible.\r
+// If a future version is not back wards compatible it is not the same GUID.\r
+//\r
+#define EDKII_DEVICE_SECURITY_PROTOCOL_REVISION 0x00010000\r
+\r
+//\r
+// The device identifier.\r
+//\r
+typedef struct {\r
+ ///\r
+ /// Version of this data structure.\r
+ ///\r
+ UINT32 Version;\r
+ ///\r
+ /// Type of the device.\r
+ /// This field is also served as a device Access protocol GUID.\r
+ /// The device access protocol is installed on the DeviceHandle.\r
+ /// The device access protocol is device specific.\r
+ /// EDKII_DEVICE_IDENTIFIER_TYPE_PCI_GUID means the device access protocol is PciIo.\r
+ /// EDKII_DEVICE_IDENTIFIER_TYPE_USB_GUID means the device access protocol is UsbIo.\r
+ ///\r
+ EFI_GUID DeviceType;\r
+ ///\r
+ /// The handle created for this device.\r
+ /// NOTE: This might be a temporary handle.\r
+ /// If the device is not authenticated, this handle shall be uninstalled.\r
+ ///\r
+ /// As minimal requirement, there should be 2 protocols installed on the device handle.\r
+ /// 1) An EFI_DEVICE_PATH_PROTOCOL with EFI_DEVICE_PATH_PROTOCOL_GUID.\r
+ /// 2) A device access protocol with EDKII_DEVICE_IDENTIFIER_TYPE_xxx_GUID.\r
+ /// If the device is PCI device, the EFI_PCI_IO_PROTOCOL is installed with\r
+ /// EDKII_DEVICE_IDENTIFIER_TYPE_PCI_GUID.\r
+ /// If the device is USB device, the EFI_USB_IO_PROTOCOL is installed with\r
+ /// EDKII_DEVICE_IDENTIFIER_TYPE_USB_GUID.\r
+ ///\r
+ /// The device access protocol is required, because the verifier need have a way\r
+ /// to communciate with the device hardware to get the measurement or do the\r
+ /// challenge/response for the device authentication.\r
+ ///\r
+ /// NOTE: We don't use EFI_PCI_IO_PROTOCOL_GUID or EFI_USB_IO_PROTOCOL_GUID here,\r
+ /// because we don't want to expose a real protocol. A platform may have driver\r
+ /// register a protocol notify function. Installing a real protocol may cause\r
+ /// the callback function being executed before the device is authenticated.\r
+ ///\r
+ EFI_HANDLE DeviceHandle;\r
+} EDKII_DEVICE_IDENTIFIER;\r
+\r
+//\r
+// Revision The revision to which the DEVICE_IDENTIFIER interface adheres.\r
+// All future revisions must be backwards compatible.\r
+//\r
+#define EDKII_DEVICE_IDENTIFIER_REVISION 0x00010000\r
+\r
+//\r
+// Device Identifier GUID value\r
+//\r
+#define EDKII_DEVICE_IDENTIFIER_TYPE_PCI_GUID \\r
+ { \\r
+ 0x2509b2f1, 0xa022, 0x4cca, { 0xaf, 0x70, 0xf9, 0xd3, 0x21, 0xfb, 0x66, 0x49 } \\r
+ }\r
+\r
+#define EDKII_DEVICE_IDENTIFIER_TYPE_USB_GUID \\r
+ { \\r
+ 0x7394f350, 0x394d, 0x488c, { 0xbb, 0x75, 0xc, 0xab, 0x7b, 0x12, 0xa, 0xc5 } \\r
+ }\r
+\r
+/**\r
+ The device driver uses this service to measure and/or verify a device.\r
+\r
+ The flow in device driver is:\r
+ 1) Device driver discovers a new device.\r
+ 2) Device driver creates an EFI_DEVICE_PATH_PROTOCOL.\r
+ 3) Device driver creates a device access protocol. e.g.\r
+ EFI_PCI_IO_PROTOCOL for PCI device.\r
+ EFI_USB_IO_PROTOCOL for USB device.\r
+ EFI_EXT_SCSI_PASS_THRU_PROTOCOL for SCSI device.\r
+ EFI_ATA_PASS_THRU_PROTOCOL for ATA device.\r
+ EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL for NVMe device.\r
+ EFI_SD_MMC_PASS_THRU_PROTOCOL for SD/MMC device.\r
+ 4) Device driver installs the EFI_DEVICE_PATH_PROTOCOL with EFI_DEVICE_PATH_PROTOCOL_GUID,\r
+ and the device access protocol with EDKII_DEVICE_IDENTIFIER_TYPE_xxx_GUID.\r
+ Once it is done, a DeviceHandle is returned.\r
+ 5) Device driver creates EDKII_DEVICE_IDENTIFIER with EDKII_DEVICE_IDENTIFIER_TYPE_xxx_GUID\r
+ and the DeviceHandle.\r
+ 6) Device driver calls DeviceAuthenticate().\r
+ 7) If DeviceAuthenticate() returns EFI_SECURITY_VIOLATION, the device driver uninstalls\r
+ all protocols on this handle.\r
+ 8) If DeviceAuthenticate() returns EFI_SUCCESS, the device driver installs the device access\r
+ protocol with a real protocol GUID. e.g.\r
+ EFI_PCI_IO_PROTOCOL with EFI_PCI_IO_PROTOCOL_GUID.\r
+ EFI_USB_IO_PROTOCOL with EFI_USB_IO_PROTOCOL_GUID.\r
+\r
+ @param[in] This The protocol instance pointer.\r
+ @param[in] DeviceId The Identifier for the device.\r
+\r
+ @retval EFI_SUCCESS The device specified by the DeviceId passed the measurement\r
+ and/or authentication based upon the platform policy.\r
+ If TCG measurement is required, the measurement is extended to TPM PCR.\r
+ @retval EFI_SECURITY_VIOLATION The device fails to return the measurement data.\r
+ @retval EFI_SECURITY_VIOLATION The device fails to response the authentication request.\r
+ @retval EFI_SECURITY_VIOLATION The system fails to verify the device based upon the authentication response.\r
+ @retval EFI_SECURITY_VIOLATION The system fails to extend the measurement to TPM PCR.\r
+**/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *EDKII_DEVICE_AUTHENTICATE)(\r
+ IN EDKII_DEVICE_SECURITY_PROTOCOL *This,\r
+ IN EDKII_DEVICE_IDENTIFIER *DeviceId\r
+ );\r
+\r
+///\r
+/// Device Security Protocol structure.\r
+/// It is similar to the EFI_SECURITY_ARCH_PROTOCOL, which is used to verify a image.\r
+/// This protocol is used to authenticate a device based upon the platform policy.\r
+///\r
+struct _EDKII_DEVICE_SECURITY_PROTOCOL {\r
+ UINT64 Revision;\r
+ EDKII_DEVICE_AUTHENTICATE DeviceAuthenticate;\r
+};\r
+\r
+///\r
+/// Device Security Protocol GUID variable.\r
+///\r
+extern EFI_GUID gEdkiiDeviceSecurityProtocolGuid;\r
+\r
+///\r
+/// Device Identifier tpye GUID variable.\r
+///\r
+extern EFI_GUID gEdkiiDeviceIdentifierTypePciGuid;\r
+extern EFI_GUID gEdkiiDeviceIdentifierTypeUsbGuid;\r
+\r
+#endif\r