public inbox for devel@edk2.groups.io
 help / color / mirror / Atom feed
From: "Yao, Jiewen" <jiewen.yao@intel.com>
To: devel@edk2.groups.io
Cc: Jian J Wang <jian.j.wang@intel.com>,
	Hao A Wu <hao.a.wu@intel.com>, Yun Lou <yun.lou@intel.com>
Subject: [PATCH V2 2/4] MdeModulePkg/Include: Add DeviceSecurity.h
Date: Thu, 31 Oct 2019 20:30:10 +0800	[thread overview]
Message-ID: <20191031123012.16020-3-jiewen.yao@intel.com> (raw)
In-Reply-To: <20191031123012.16020-1-jiewen.yao@intel.com>

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@intel.com>
Cc: Hao A Wu <hao.a.wu@intel.com>
Cc: Yun Lou <yun.lou@intel.com>
Signed-off-by: Jiewen Yao <jiewen.yao@intel.com>
---
 MdeModulePkg/Include/Protocol/DeviceSecurity.h | 162 ++++++++++++++++++++
 1 file changed, 162 insertions(+)

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


  parent reply	other threads:[~2019-10-31 12:30 UTC|newest]

Thread overview: 20+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-10-31 12:30 [PATCH V2 0/4] Add SPDM device security Yao, Jiewen
2019-10-31 12:30 ` [PATCH V2 1/4] MdePkg/Include: Add DMTF SPDM definition Yao, Jiewen
2019-11-06 14:38   ` Liming Gao
2019-11-07  0:25     ` Yao, Jiewen
     [not found]     ` <15D4B9B24059B4F1.19610@groups.io>
2019-11-07  0:57       ` [edk2-devel] " Yao, Jiewen
2019-10-31 12:30 ` Yao, Jiewen [this message]
2019-11-06  7:55   ` [edk2-devel] [PATCH V2 2/4] MdeModulePkg/Include: Add DeviceSecurity.h Ni, Ray
2019-11-06  8:25     ` Yao, Jiewen
2019-11-07  1:58       ` Ni, Ray
     [not found]       ` <15D4BEC95EBB70CB.18056@groups.io>
2019-11-07  4:31         ` Ni, Ray
2019-11-07  7:13           ` Yao, Jiewen
2019-11-07  7:16             ` Ni, Ray
2019-10-31 12:30 ` [PATCH V2 3/4] MdeModulePkg/dec: Add EdkiiDeviceSecurityProtocolGuid Yao, Jiewen
2019-10-31 12:30 ` [PATCH V2 4/4] MdeModulePkg/Pci: Add DeviceSecurity support Yao, Jiewen
2019-11-07  4:42   ` Ni, Ray
2019-11-07  7:05     ` Yao, Jiewen
     [not found] ` <15D2BB2D773DBDBA.23805@groups.io>
2019-11-06  6:47   ` [edk2-devel] [PATCH V2 1/4] MdePkg/Include: Add DMTF SPDM definition Yao, Jiewen
     [not found] ` <15D2BB2E5CC7FD95.31603@groups.io>
2019-11-06  6:47   ` [edk2-devel] [PATCH V2 4/4] MdeModulePkg/Pci: Add DeviceSecurity support Yao, Jiewen
     [not found] ` <15D2BB2DC41C838D.31603@groups.io>
2019-11-06  6:47   ` [edk2-devel] [PATCH V2 2/4] MdeModulePkg/Include: Add DeviceSecurity.h Yao, Jiewen
     [not found] ` <15D2BB2E0995721D.31603@groups.io>
2019-11-06  6:47   ` [edk2-devel] [PATCH V2 3/4] MdeModulePkg/dec: Add EdkiiDeviceSecurityProtocolGuid Yao, Jiewen

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-list from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20191031123012.16020-3-jiewen.yao@intel.com \
    --to=devel@edk2.groups.io \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox