MdeModulePkg/Include/Protocol/DeviceSecurity.h

   1 /** @file
   2   Device Security Protocol definition.
   3
   4   It is used to authenticate a device based upon the platform policy.
   5   It is similar to the EFI_SECURITY_ARCH_PROTOCOL, which is used to verify a image.
   6
   7 Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
   8 SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10 **/
  11
  12 #ifndef __DEVICE_SECURITY_H__
  13 #define __DEVICE_SECURITY_H__
  14
  15 //
  16 // Device Security Protocol GUID value
  17 //
  18 #define EDKII_DEVICE_SECURITY_PROTOCOL_GUID \
  19     { \
  20       0x5d6b38c8, 0x5510, 0x4458, { 0xb4, 0x8d, 0x95, 0x81, 0xcf, 0xa7, 0xb0, 0xd } \
  21     }
  22
  23 //
  24 // Forward reference for pure ANSI compatability
  25 //
  26 typedef struct _EDKII_DEVICE_SECURITY_PROTOCOL EDKII_DEVICE_SECURITY_PROTOCOL;
  27
  28 //
  29 // Revision The revision to which the DEVICE_SECURITY interface adheres.
  30 //          All future revisions must be backwards compatible.
  31 //          If a future version is not back wards compatible it is not the same GUID.
  32 //
  33 #define EDKII_DEVICE_SECURITY_PROTOCOL_REVISION  0x00010000
  34
  35 //
  36 // The device identifier.
  37 //
  38 typedef struct {
  39   ///
  40   /// Version of this data structure.
  41   ///
  42   UINT32    Version;
  43   ///
  44   /// Type of the device.
  45   /// This field is also served as a device Access protocol GUID.
  46   /// The device access protocol is installed on the DeviceHandle.
  47   /// The device access protocol is device specific.
  48   ///   EDKII_DEVICE_IDENTIFIER_TYPE_PCI_GUID means the device access protocol is PciIo.
  49   ///   EDKII_DEVICE_IDENTIFIER_TYPE_USB_GUID means the device access protocol is UsbIo.
  50   ///
  51   EFI_GUID    DeviceType;
  52   ///
  53   /// The handle created for this device.
  54   /// NOTE: This might be a temporary handle.
  55   ///       If the device is not authenticated, this handle shall be uninstalled.
  56   ///
  57   /// As minimal requirement, there should be 2 protocols installed on the device handle.
  58   /// 1) An EFI_DEVICE_PATH_PROTOCOL with EFI_DEVICE_PATH_PROTOCOL_GUID.
  59   /// 2) A device access protocol with EDKII_DEVICE_IDENTIFIER_TYPE_xxx_GUID.
  60   ///    If the device is PCI device, the EFI_PCI_IO_PROTOCOL is installed with
  61   ///    EDKII_DEVICE_IDENTIFIER_TYPE_PCI_GUID.
  62   ///    If the device is USB device, the EFI_USB_IO_PROTOCOL is installed with
  63   ///    EDKII_DEVICE_IDENTIFIER_TYPE_USB_GUID.
  64   ///
  65   ///    The device access protocol is required, because the verifier need have a way
  66   ///    to communciate with the device hardware to get the measurement or do the
  67   ///    challenge/response for the device authentication.
  68   ///
  69   /// NOTE: We don't use EFI_PCI_IO_PROTOCOL_GUID or EFI_USB_IO_PROTOCOL_GUID here,
  70   ///       because we don't want to expose a real protocol. A platform may have driver
  71   ///       register a protocol notify function. Installing a real protocol may cause
  72   ///       the callback function being executed before the device is authenticated.
  73   ///
  74   EFI_HANDLE    DeviceHandle;
  75 } EDKII_DEVICE_IDENTIFIER;
  76
  77 //
  78 // Revision The revision to which the DEVICE_IDENTIFIER interface adheres.
  79 //          All future revisions must be backwards compatible.
  80 //
  81 #define EDKII_DEVICE_IDENTIFIER_REVISION  0x00010000
  82
  83 //
  84 // Device Identifier GUID value
  85 //
  86 #define EDKII_DEVICE_IDENTIFIER_TYPE_PCI_GUID \
  87     { \
  88       0x2509b2f1, 0xa022, 0x4cca, { 0xaf, 0x70, 0xf9, 0xd3, 0x21, 0xfb, 0x66, 0x49 } \
  89     }
  90
  91 #define EDKII_DEVICE_IDENTIFIER_TYPE_USB_GUID \
  92     { \
  93       0x7394f350, 0x394d, 0x488c, { 0xbb, 0x75, 0xc, 0xab, 0x7b, 0x12, 0xa, 0xc5 } \
  94     }
  95
  96 /**
  97   The device driver uses this service to measure and/or verify a device.
  98
  99   The flow in device driver is:
 100   1) Device driver discovers a new device.
 101   2) Device driver creates an EFI_DEVICE_PATH_PROTOCOL.
 102   3) Device driver creates a device access protocol. e.g.
 103      EFI_PCI_IO_PROTOCOL for PCI device.
 104      EFI_USB_IO_PROTOCOL for USB device.
 105      EFI_EXT_SCSI_PASS_THRU_PROTOCOL for SCSI device.
 106      EFI_ATA_PASS_THRU_PROTOCOL for ATA device.
 107      EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL for NVMe device.
 108      EFI_SD_MMC_PASS_THRU_PROTOCOL for SD/MMC device.
 109   4) Device driver installs the EFI_DEVICE_PATH_PROTOCOL with EFI_DEVICE_PATH_PROTOCOL_GUID,
 110      and the device access protocol with EDKII_DEVICE_IDENTIFIER_TYPE_xxx_GUID.
 111      Once it is done, a DeviceHandle is returned.
 112   5) Device driver creates EDKII_DEVICE_IDENTIFIER with EDKII_DEVICE_IDENTIFIER_TYPE_xxx_GUID
 113      and the DeviceHandle.
 114   6) Device driver calls DeviceAuthenticate().
 115   7) If DeviceAuthenticate() returns EFI_SECURITY_VIOLATION, the device driver uninstalls
 116      all protocols on this handle.
 117   8) If DeviceAuthenticate() returns EFI_SUCCESS, the device driver installs the device access
 118      protocol with a real protocol GUID. e.g.
 119      EFI_PCI_IO_PROTOCOL with EFI_PCI_IO_PROTOCOL_GUID.
 120      EFI_USB_IO_PROTOCOL with EFI_USB_IO_PROTOCOL_GUID.
 121
 122   @param[in]  This              The protocol instance pointer.
 123   @param[in]  DeviceId          The Identifier for the device.
 124
 125   @retval EFI_SUCCESS              The device specified by the DeviceId passed the measurement
 126                                    and/or authentication based upon the platform policy.
 127                                    If TCG measurement is required, the measurement is extended to TPM PCR.
 128   @retval EFI_SECURITY_VIOLATION   The device fails to return the measurement data.
 129   @retval EFI_SECURITY_VIOLATION   The device fails to response the authentication request.
 130   @retval EFI_SECURITY_VIOLATION   The system fails to verify the device based upon the authentication response.
 131   @retval EFI_SECURITY_VIOLATION   The system fails to extend the measurement to TPM PCR.
 132 **/
 133 typedef
 134 EFI_STATUS
 135 (EFIAPI *EDKII_DEVICE_AUTHENTICATE)(
 136   IN EDKII_DEVICE_SECURITY_PROTOCOL  *This,
 137   IN EDKII_DEVICE_IDENTIFIER         *DeviceId
 138   );
 139
 140 ///
 141 /// Device Security Protocol structure.
 142 /// It is similar to the EFI_SECURITY_ARCH_PROTOCOL, which is used to verify a image.
 143 /// This protocol is used to authenticate a device based upon the platform policy.
 144 ///
 145 struct _EDKII_DEVICE_SECURITY_PROTOCOL {
 146   UINT64                       Revision;
 147   EDKII_DEVICE_AUTHENTICATE    DeviceAuthenticate;
 148 };
 149
 150 ///
 151 /// Device Security Protocol GUID variable.
 152 ///
 153 extern EFI_GUID  gEdkiiDeviceSecurityProtocolGuid;
 154
 155 ///
 156 /// Device Identifier tpye GUID variable.
 157 ///
 158 extern EFI_GUID  gEdkiiDeviceIdentifierTypePciGuid;
 159 extern EFI_GUID  gEdkiiDeviceIdentifierTypeUsbGuid;
 160
 161 #endif