[edk2-devel] [PATCH V3 2/4] MdeModulePkg/Include: Add DeviceSecurity.h
Yao, Jiewen
jiewen.yao at intel.com
Thu Nov 7 13:37:36 UTC 2019
REF: https://bugzilla.tianocore.org/show_bug.cgi?id=2303
EDKII_DEVICE_SECURITY_PROTOCOL is used for device
measurement and/or authentication.
It is similar to EFI_SECURITY_ARCH_PROTOCOL.
Cc: Jian J Wang <jian.j.wang at intel.com>
Cc: Hao A Wu <hao.a.wu at intel.com>
Cc: Yun Lou <yun.lou at intel.com>
Signed-off-by: Jiewen Yao <jiewen.yao at intel.com>
---
.../Include/Protocol/DeviceSecurity.h | 162 ++++++++++++++++++
1 file changed, 162 insertions(+)
create mode 100644 MdeModulePkg/Include/Protocol/DeviceSecurity.h
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.<BR>
+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
--
2.19.2.windows.1
-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#50215): https://edk2.groups.io/g/devel/message/50215
Mute This Topic: https://groups.io/mt/46026427/1813853
Group Owner: devel+owner at edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [edk2-devel-archive at redhat.com]
-=-=-=-=-=-=-=-=-=-=-=-
More information about the edk2-devel-archive
mailing list