Re: [edk2-devel] [PATCH V2 2/4] MdeModulePkg/Include: Add DeviceSecurity.h

["Yao, Jiewen" <jiewen.yao@intel.com>]

Hi Jian/Hao/Ray
Would you please review this patch?

We need this feature in next stable tag as planned.

Thank you
Yao Jiewen

> -----Original Message-----
> From: devel@edk2.groups.io <devel@edk2.groups.io> On Behalf Of Yao, Jiewen
> Sent: Thursday, October 31, 2019 8:30 PM
> To: devel@edk2.groups.io
> Cc: Wang, Jian J <jian.j.wang@intel.com>; Wu, Hao A <hao.a.wu@intel.com>;
> Lou, Yun <yun.lou@intel.com>
> Subject: [edk2-devel] [PATCH V2 2/4] MdeModulePkg/Include: Add
> DeviceSecurity.h
> 
> 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
> 
> 
>