1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
/** @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
|
