/** @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 |