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
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
|
/** @file
This file declares the Variable Storage Protocol.
This protocol abstracts read-only access to the UEFI variable store
on a NVM (Non-Volatile Memory) device during the Runtime DXE phase.
Copyright (c) 2016, Intel Corporation. All rights reserved.<BR>
This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
http://opensource.org/licenses/bsd-license.php.
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
#ifndef _VARIABLE_STORAGE_PROTOCOL_H_
#define _VARIABLE_STORAGE_PROTOCOL_H_
extern EFI_GUID gVariableStorageProtocolGuid;
///
/// Revision
///
#define VARIABLE_STORAGE_PROTOCOL_REVISION 1
typedef struct _VARIABLE_STORAGE_PROTOCOL VARIABLE_STORAGE_PROTOCOL;
/**
Retrieves a protocol instance-specific GUID.
Returns a unique GUID per VARIABLE_STORAGE_PROTOCOL instance.
@param[out] VariableGuid A pointer to an EFI_GUID that is this protocol instance's GUID.
@retval EFI_SUCCESS The data was returned successfully.
@retval EFI_INVALID_PARAMETER A required parameter is NULL.
**/
typedef
EFI_STATUS
(EFIAPI *VARIABLE_STORAGE_GET_ID)(
OUT EFI_GUID *InstanceGuid
);
/**
This service retrieves a variable's value using its name and GUID.
Read the specified variable from the UEFI variable store. If the Data
buffer is too small to hold the contents of the variable,
the error EFI_BUFFER_TOO_SMALL is returned and DataSize is set to the
required buffer size to obtain the data.
@param[in] This A pointer to this instance of the VARIABLE_STORAGE_PROTOCOL.
@param[in] VariableName A pointer to a null-terminated string that is the variable's name.
@param[in] VariableGuid A pointer to an EFI_GUID that is the variable's GUID. The combination of
VariableGuid and VariableName must be unique.
@param[out] Attributes If non-NULL, on return, points to the variable's attributes.
@param[in, out] DataSize On entry, points to the size in bytes of the Data buffer.
On return, points to the size of the data returned in Data.
@param[out] Data Points to the buffer which will hold the returned variable value.
@retval EFI_SUCCESS The variable was read successfully.
@retval EFI_NOT_FOUND The variable could not be found.
@retval EFI_BUFFER_TOO_SMALL The DataSize is too small for the resulting data.
DataSize is updated with the size required for
the specified variable.
@retval EFI_INVALID_PARAMETER VariableName, VariableGuid, DataSize or Data is NULL.
@retval EFI_DEVICE_ERROR The variable could not be retrieved because of a device error.
**/
typedef
EFI_STATUS
(EFIAPI *VARIABLE_STORAGE_GET_VARIABLE)(
IN CONST VARIABLE_STORAGE_PROTOCOL *This,
IN CONST CHAR16 *VariableName,
IN CONST EFI_GUID *VariableGuid,
OUT UINT32 *Attributes,
IN OUT UINTN *DataSize,
OUT VOID *Data
);
/**
This service retrieves an authenticated variable's value using its name and GUID.
Read the specified authenticated variable from the UEFI variable store. If the Data
buffer is too small to hold the contents of the variable,
the error EFI_BUFFER_TOO_SMALL is returned and DataSize is set to the
required buffer size to obtain the data.
@param[in] This A pointer to this instance of the VARIABLE_STORAGE_PROTOCOL.
@param[in] VariableName A pointer to a null-terminated string that is the variable's name.
@param[in] VariableGuid A pointer to an EFI_GUID that is the variable's GUID. The combination of
VariableGuid and VariableName must be unique.
@param[out] Attributes If non-NULL, on return, points to the variable's attributes.
@param[in, out] DataSize On entry, points to the size in bytes of the Data buffer.
On return, points to the size of the data returned in Data.
@param[out] Data Points to the buffer which will hold the returned variable value.
@param[out] KeyIndex Index of associated public key in database
@param[out] MonotonicCount Associated monotonic count value to protect against replay attack
@param[out] TimeStamp Associated TimeStamp value to protect against replay attack
@retval EFI_SUCCESS The variable was read successfully.
@retval EFI_NOT_FOUND The variable could not be found.
@retval EFI_BUFFER_TOO_SMALL The DataSize is too small for the resulting data.
DataSize is updated with the size required for
the specified variable.
@retval EFI_INVALID_PARAMETER VariableName, VariableGuid, DataSize or Data is NULL.
@retval EFI_DEVICE_ERROR The variable could not be retrieved because of a device error.
**/
typedef
EFI_STATUS
(EFIAPI *VARIABLE_STORAGE_GET_AUTHENTICATED_VARIABLE)(
IN CONST VARIABLE_STORAGE_PROTOCOL *This,
IN CONST CHAR16 *VariableName,
IN CONST EFI_GUID *VariableGuid,
OUT UINT32 *Attributes,
IN OUT UINTN *DataSize,
OUT VOID *Data,
OUT UINT32 *KeyIndex,
OUT UINT64 *MonotonicCount,
OUT EFI_TIME *TimeStamp
);
/**
Return the next variable name and GUID.
This function is called multiple times to retrieve the VariableName
and VariableGuid of all variables currently available in the system.
On each call, the previous results are passed into the interface,
and, on return, the interface returns the data for the next
interface. When the entire variable list has been returned,
EFI_NOT_FOUND is returned.
@param[in] This A pointer to this instance of the VARIABLE_STORAGE_PROTOCOL.
@param[in, out] VariableNameSize On entry, points to the size of the buffer pointed to by
VariableName. On return, the size of the variable name buffer.
@param[in, out] VariableName On entry, a pointer to a null-terminated string that is the
variable's name. On return, points to the next variable's
null-terminated name string.
@param[in, out] VariableGuid On entry, a pointer to an EFI_GUID that is the variable's GUID.
On return, a pointer to the next variable's GUID.
@param[out] VariableAttributes A pointer to the variable attributes.
@retval EFI_SUCCESS The variable was read successfully.
@retval EFI_NOT_FOUND The variable could not be found.
@retval EFI_BUFFER_TOO_SMALL The VariableNameSize is too small for the resulting
data. VariableNameSize is updated with the size
required for the specified variable.
@retval EFI_INVALID_PARAMETER VariableName, VariableGuid or
VariableNameSize is NULL.
@retval EFI_DEVICE_ERROR The variable could not be retrieved because of a device error.
**/
typedef
EFI_STATUS
(EFIAPI *VARIABLE_STORAGE_GET_NEXT_VARIABLE_NAME)(
IN CONST VARIABLE_STORAGE_PROTOCOL *This,
IN OUT UINTN *VariableNameSize,
IN OUT CHAR16 *VariableName,
IN OUT EFI_GUID *VariableGuid,
OUT UINT32 *VariableAttributes
);
/**
Returns information on the amount of space available in the variable store. If the amount of data that can be written
depends on if the platform is in Pre-OS stage or OS stage, the AtRuntime parameter should be used to compute usage.
@param[in] This A pointer to this instance of the VARIABLE_STORAGE_PROTOCOL.
@param[in] AtRuntime TRUE is the platform is in OS Runtime, FALSE if still in Pre-OS stage
@param[out] VariableStoreSize The total size of the NV storage. Indicates the maximum amount
of data that can be stored in this NV storage area.
@param[out] CommonVariablesTotalSize The total combined size of all the common UEFI variables that are
stored in this NV storage area. Excludes variables with the
EFI_VARIABLE_HARDWARE_ERROR_RECORD attribute set.
@param[out] HwErrVariablesTotalSize The total combined size of all the UEFI variables that have the
EFI_VARIABLE_HARDWARE_ERROR_RECORD attribute set and which are
stored in this NV storage area. Excludes all other variables.
@retval EFI_INVALID_PARAMETER Any of the given parameters are NULL
@retval EFI_SUCCESS Space information returned successfully.
**/
typedef
EFI_STATUS
(EFIAPI *VARIABLE_STORAGE_GET_STORAGE_USAGE)(
IN CONST VARIABLE_STORAGE_PROTOCOL *This,
IN BOOLEAN AtRuntime,
OUT UINT32 *VariableStoreSize,
OUT UINT32 *CommonVariablesTotalSize,
OUT UINT32 *HwErrVariablesTotalSize
);
/**
Returns whether this NV storage area supports storing authenticated variables or not
@param[in] This A pointer to this instance of the VARIABLE_STORAGE_PROTOCOL.
@param[out] AuthSupported TRUE if this NV storage area can store authenticated variables,
FALSE otherwise
@retval EFI_SUCCESS AuthSupported was returned successfully.
**/
typedef
EFI_STATUS
(EFIAPI *VARIABLE_STORAGE_GET_AUTHENTICATED_SUPPORT)(
IN CONST VARIABLE_STORAGE_PROTOCOL *This,
OUT BOOLEAN *AuthSupported
);
/**
Returns whether this NV storage area is ready to accept calls to SetVariable() or not
@param[in] This A pointer to this instance of the VARIABLE_STORAGE_PROTOCOL.
@retval TRUE The NV storage area is ready to accept calls to SetVariable()
@retval FALSE The NV storage area is not ready to accept calls to SetVariable()
**/
typedef
BOOLEAN
(EFIAPI *VARIABLE_STORAGE_WRITE_SERVICE_IS_READY)(
IN CONST VARIABLE_STORAGE_PROTOCOL *This
);
/**
A callback to be invoked by the VARIABLE_STORAGE_PROTOCOL to indicate to the core variable driver that
the WriteServiceIsReady() function is now returning TRUE instead of FALSE.
The VARIABLE_STORAGE_PROTOCOL is required to call this function as quickly as possible after the core
variable driver invokes RegisterWriteServiceReadyCallback() to set the callback.
@retval EFI_SUCCESS Change to WriteServiceIsReady() status was processed successfully.
**/
typedef
EFI_STATUS
(EFIAPI *VARIABLE_STORAGE_WRITE_SERVICE_READY_CALLBACK)(
VOID
);
/**
Sets the callback to be invoked when the VARIABLE_STORAGE_PROTOCOL is ready to accept calls to SetVariable()
The VARIABLE_STORAGE_PROTOCOL is required to invoke the callback as quickly as possible after the core
variable driver invokes RegisterWriteServiceReadyCallback() to set the callback.
@param[in] This A pointer to this instance of the VARIABLE_STORAGE_PROTOCOL.
@param[in] CallbackFunction The callback function
@retval EFI_SUCCESS The callback function was sucessfully registered
**/
typedef
EFI_STATUS
(EFIAPI *VARIABLE_STORAGE_REGISTER_WRITE_SERVICE_READY_CALLBACK)(
IN CONST VARIABLE_STORAGE_PROTOCOL *This,
IN VARIABLE_STORAGE_WRITE_SERVICE_READY_CALLBACK CallbackFunction
);
/**
This code sets a variable's value using its name and GUID.
Caution: This function may receive untrusted input.
This function may be invoked in SMM mode, and datasize and data are external input.
This function will do basic validation, before parsing the data.
This function will parse the authentication carefully to avoid security issues, like
buffer overflow, integer overflow.
This function will check attribute carefully to avoid authentication bypass.
@param[in] This A pointer to this instance of the VARIABLE_STORAGE_PROTOCOL.
@param[in] VariableName Name of Variable to be found.
@param[in] VendorGuid Variable vendor GUID.
@param[in] Attributes Attribute value of the variable found
@param[in] DataSize Size of Data found. If size is less than the
data, this value contains the required size.
@param[in] Data Data pointer.
@param[in] AtRuntime TRUE is the platform is in OS Runtime, FALSE if still in Pre-OS stage
@param[in] KeyIndex If writing an authenticated variable, the public key index
@param[in] MonotonicCount If writing a monotonic counter authenticated variable, the counter value
@param[in] TimeStamp If writing a timestamp authenticated variable, the timestamp value
@retval EFI_INVALID_PARAMETER Invalid parameter.
@retval EFI_SUCCESS Set successfully.
@retval EFI_OUT_OF_RESOURCES Resource not enough to set variable.
@retval EFI_NOT_FOUND Not found.
@retval EFI_WRITE_PROTECTED Variable is read-only.
**/
typedef
EFI_STATUS
(EFIAPI *VARIABLE_STORAGE_SET_VARIABLE)(
IN CONST VARIABLE_STORAGE_PROTOCOL *This,
IN CHAR16 *VariableName,
IN EFI_GUID *VendorGuid,
IN UINT32 Attributes,
IN UINTN DataSize,
IN VOID *Data,
IN BOOLEAN AtRuntime,
IN UINT32 KeyIndex OPTIONAL,
IN UINT64 MonotonicCount OPTIONAL,
IN EFI_TIME *TimeStamp OPTIONAL
);
///
/// Variable Storage Protocol
/// Interface functions for variable NVM storage access in DXE phase.
///
struct _VARIABLE_STORAGE_PROTOCOL {
VARIABLE_STORAGE_GET_ID GetId; ///< Retrieves a protocol instance-specific GUID
VARIABLE_STORAGE_GET_VARIABLE GetVariable; ///< Retrieves a variable's value given its name and GUID
VARIABLE_STORAGE_GET_AUTHENTICATED_VARIABLE GetAuthenticatedVariable; ///< Retrieves an authenticated variable's value given its name and GUID
VARIABLE_STORAGE_GET_NEXT_VARIABLE_NAME GetNextVariableName; ///< Return the next variable name and GUID
VARIABLE_STORAGE_GET_STORAGE_USAGE GetStorageUsage; ///< Returns information on storage usage in the variable store
VARIABLE_STORAGE_GET_AUTHENTICATED_SUPPORT GetAuthenticatedSupport; ///< Returns whether this NV storage area supports authenticated variables
VARIABLE_STORAGE_SET_VARIABLE SetVariable; ///< Sets a variable's value using its name and GUID.
VARIABLE_STORAGE_WRITE_SERVICE_IS_READY WriteServiceIsReady; ///< Indicates if SetVariable() is ready or not
VARIABLE_STORAGE_REGISTER_WRITE_SERVICE_READY_CALLBACK RegisterWriteServiceReadyCallback; ///< Sets the callback to notify that SetVariable() is ready
};
#endif
|
