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