diff --git a/MdeModulePkg/Include/Protocol/DeviceSecurity.h b/MdeModulePkg/Include/Protocol/DeviceSecurity.h new file mode 100644 index 0000000000..c3bf624cac --- /dev/null +++ b/MdeModulePkg/Include/Protocol/DeviceSecurity.h @@ -0,0 +1,162 @@ +/** @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