DeviceSecurity.h File Reference

Data Structures
struct	EDKII_DEVICE_IDENTIFIER
struct	_EDKII_DEVICE_SECURITY_PROTOCOL

Macros
#define	EDKII_DEVICE_SECURITY_PROTOCOL_GUID
#define	EDKII_DEVICE_SECURITY_PROTOCOL_REVISION   0x00010000
#define	EDKII_DEVICE_IDENTIFIER_REVISION   0x00010000
#define	EDKII_DEVICE_IDENTIFIER_TYPE_PCI_GUID
#define	EDKII_DEVICE_IDENTIFIER_TYPE_USB_GUID

Typedefs
typedef struct _EDKII_DEVICE_SECURITY_PROTOCOL	EDKII_DEVICE_SECURITY_PROTOCOL
typedef EFI_STATUS(EFIAPI *	EDKII_DEVICE_AUTHENTICATE )(IN EDKII_DEVICE_SECURITY_PROTOCOL *This, IN EDKII_DEVICE_IDENTIFIER *DeviceId)

Variables
EFI_GUID	gEdkiiDeviceSecurityProtocolGuid
EFI_GUID	gEdkiiDeviceIdentifierTypePciGuid
EFI_GUID	gEdkiiDeviceIdentifierTypeUsbGuid

Detailed Description

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.
SPDX-License-Identifier: BSD-2-Clause-Patent

Macro Definition Documentation

#define EDKII_DEVICE_IDENTIFIER_REVISION   0x00010000

#define EDKII_DEVICE_IDENTIFIER_TYPE_PCI_GUID

Value:

{ \
      0x2509b2f1, 0xa022, 0x4cca, { 0xaf, 0x70, 0xf9, 0xd3, 0x21, 0xfb, 0x66, 0x49 } \
    }

#define EDKII_DEVICE_IDENTIFIER_TYPE_USB_GUID

Value:

{ \
      0x7394f350, 0x394d, 0x488c, { 0xbb, 0x75, 0xc, 0xab, 0x7b, 0x12, 0xa, 0xc5 } \
    }

#define EDKII_DEVICE_SECURITY_PROTOCOL_GUID

Value:

{ \
      0x5d6b38c8, 0x5510, 0x4458, { 0xb4, 0x8d, 0x95, 0x81, 0xcf, 0xa7, 0xb0, 0xd } \
    }

#define EDKII_DEVICE_SECURITY_PROTOCOL_REVISION   0x00010000

Typedef Documentation

typedef EFI_STATUS(EFIAPI * EDKII_DEVICE_AUTHENTICATE)(IN EDKII_DEVICE_SECURITY_PROTOCOL *This, IN EDKII_DEVICE_IDENTIFIER *DeviceId)

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.

Parameters

[in]	This	The protocol instance pointer.
[in]	DeviceId	The Identifier for the device.

Return values

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.
EFI_SECURITY_VIOLATION	The device fails to return the measurement data.
EFI_SECURITY_VIOLATION	The device fails to response the authentication request.
EFI_SECURITY_VIOLATION	The system fails to verify the device based upon the authentication response.
EFI_SECURITY_VIOLATION	The system fails to extend the measurement to TPM PCR.

typedef struct _EDKII_DEVICE_SECURITY_PROTOCOL EDKII_DEVICE_SECURITY_PROTOCOL

Variable Documentation

EFI_GUID gEdkiiDeviceIdentifierTypePciGuid

Device Identifier tpye GUID variable.

EFI_GUID gEdkiiDeviceIdentifierTypeUsbGuid

EFI_GUID gEdkiiDeviceSecurityProtocolGuid

Device Security Protocol GUID variable.