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