uefi-ref/edk2
1
0
Fork 0
mirror of https://github.com/tianocore/edk2 synced 2026-08-27 00:23:19 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
edk2/MdeModulePkg/Include/Protocol/DeviceSecurity.h
Michael Kubacki 7a934d0bef MdeModulePkg: Replace include guards with #pragma once 
Replace traditional `#ifndef`/`#define`/`#endif` include guards with
`#pragma` once.

`#pragma once` is a widely supported preprocessor directive that
prevents header files from being included multiple times. It is
supported by all toolchains used to build edk2: GCC, Clang/LLVM, and
MSVC.

Compared to macro-based include guards, `#pragma once`:

- Eliminates the risk of macro name collisions or copy/paste errors
  where two headers inadvertently use the same guard macro.
- Eliminate inconsistency in the way include guard macros are named
  (e.g., some files use `__FILE_H__`, others use `FILE_H_`, etc.).
- Reduces boilerplate (three lines replaced by one).
- Avoids polluting the macro namespace with guard symbols.
- Can improve build times as the preprocessor can skip re-opening the
  file entirely, rather than re-reading it to find the matching
  `#endif` ("multiple-include optimization").
  - Note that some compilers may already optimize traditional include
    guards, by recognzining the idiomatic pattern.

This change is made acknowledging that overall portability of the
code will technically be reduced, as `#pragma once` is not part of the
C/C++ standards.

However, this is considered acceptable given:

1. edk2 already defines a subset of supported compilers in
   BaseTools/Conf/tools_def.template, all of which have supported
   `#pragma once` for over two decades.
2. There have been concerns raised to the project about inconsistent
   include guard naming and potential macro collisions.

Approximate compiler support dates:

- MSVC: Supported since Visual C++ 4.2 (1996)
- GCC: Supported since 3.4 (2004)
  (http://gnu.ist.utl.pt/software/gcc/gcc-3.4/changes.html)
- Clang (LLVM based): Since initial release in 2007

Signed-off-by: Michael Kubacki <michael.kubacki@microsoft.com>
2026-02-23 21:01:28 +00:00

158 lines
6.3 KiB
C
Raw Permalink Blame History

/** @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
**/
#pragma once
//
// 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;
Reference in a new issue View git blame Copy permalink