VirtualBox

source: vbox/trunk/include/iprt/efi.h@ 103224

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.0 KB
Line 
1/** @file
2 * IPRT - EFI related utilities.
3 */
4
5/*
6 * Copyright (C) 2021-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_efi_h
37#define IPRT_INCLUDED_efi_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/cdefs.h>
43#include <iprt/types.h>
44#include <iprt/time.h>
45#include <iprt/vfs.h>
46
47#include <iprt/formats/efi-common.h>
48
49
50RT_C_DECLS_BEGIN
51
52/** @defgroup grp_rt_efi RTEfi - EFI utilities
53 * @ingroup grp_rt
54 * @{
55 */
56
57
58#ifdef IN_RING3
59
60/**
61 * Converts an EFI time to a time spec (UTC).
62 *
63 * @returns pTimeSpec on success.
64 * @returns NULL if the pEfiTime data is invalid.
65 * @param pTimeSpec Where to store the converted time.
66 * @param pEfiTime Pointer to the EFI time struct.
67 */
68RTDECL(PRTTIMESPEC) RTEfiTimeToTimeSpec(PRTTIMESPEC pTimeSpec, PCEFI_TIME pEfiTime);
69
70
71/**
72 * Converts a time spec (UTC) to an EFI time.
73 *
74 * @returns pEfiTime on success.
75 * @returns NULL if the pTimeSpec data is invalid.
76 * @param pEfiTime Pointer to the EFI time struct.
77 * @param pTimeSpec The time spec to convert.
78 */
79RTDECL(PEFI_TIME) RTEfiTimeFromTimeSpec(PEFI_TIME pEfiTime, PCRTTIMESPEC pTimeSpec);
80
81
82/**
83 * Converts the given EFI GUID to the IPRT UUID representation.
84 *
85 * @returns pUuid.
86 * @param pUuid Where to store the converted GUID.
87 * @param pEfiGuid The EFI GUID to convert.
88 */
89RTDECL(PRTUUID) RTEfiGuidToUuid(PRTUUID pUuid, PCEFI_GUID pEfiGuid);
90
91
92/**
93 * Converts the given EFI GUID to the IPRT UUID representation.
94 *
95 * @returns pEfiGuid.
96 * @param pEfiGuid Where to store the converted UUID.
97 * @param pUuid The UUID to convert.
98 */
99RTDECL(PEFI_GUID) RTEfiGuidFromUuid(PEFI_GUID pEfiGuid, PCRTUUID pUuid);
100
101
102/**
103 * Compares two EFI GUID values.
104 *
105 * @returns 0 if eq, < 0 or > 0.
106 * @param pGuid1 First value to compare.
107 * @param pGuid2 Second value to compare.
108 */
109RTDECL(int) RTEfiGuidCompare(PCEFI_GUID pGuid1, PCEFI_GUID pGuid2);
110
111
112/**
113 * Opens an EFI variable store.
114 *
115 * @returns IPRT status code.
116 * @param hVfsFileIn The file or device backing the store.
117 * @param fMntFlags RTVFSMNT_F_XXX.
118 * @param fVarStoreFlags Reserved, MBZ.
119 * @param phVfs Where to return the virtual file system handle.
120 * @param pErrInfo Where to return additional error information.
121 */
122RTDECL(int) RTEfiVarStoreOpenAsVfs(RTVFSFILE hVfsFileIn, uint32_t fMntFlags, uint32_t fVarStoreFlags, PRTVFS phVfs, PRTERRINFO pErrInfo);
123
124
125/** @name RTEFIVARSTORE_CREATE_F_XXX - RTEfiVarStoreCreate flags
126 * @{ */
127/** Use default options. */
128#define RTEFIVARSTORE_CREATE_F_DEFAULT UINT32_C(0)
129/** Don't create a fault tolerant write working space.
130 * The default is to create one reducing the size of the variable store. */
131#define RTEFIVARSTORE_CREATE_F_NO_FTW_WORKING_SPACE RT_BIT_32(0)
132/** Mask containing all valid flags. */
133#define RTEFIVARSTORE_CREATE_F_VALID_MASK UINT32_C(0x00000001)
134/** @} */
135
136/**
137 * Creates a new EFI variable store.
138 *
139 * @returns IRPT status code.
140 * @param hVfsFile The store file.
141 * @param offStore The offset into @a hVfsFile of the file.
142 * Typically 0.
143 * @param cbStore The size of the variable store. Pass 0 if the rest of
144 * hVfsFile should be used. The remaining space for variables
145 * will be less because of some metadata overhead.
146 * @param fFlags See RTEFIVARSTORE_F_XXX.
147 * @param cbBlock The logical block size.
148 * @param pErrInfo Additional error information, maybe. Optional.
149 */
150RTDECL(int) RTEfiVarStoreCreate(RTVFSFILE hVfsFile, uint64_t offStore, uint64_t cbStore, uint32_t fFlags, uint32_t cbBlock,
151 PRTERRINFO pErrInfo);
152
153
154/**
155 * EFI signature type.
156 */
157typedef enum RTEFISIGTYPE
158{
159 /** Invalid type, do not use. */
160 RTEFISIGTYPE_INVALID = 0,
161 /** First valid signature type. */
162 RTEFISIGTYPE_FIRST_VALID,
163 /** Signature contains a SHA256 hash. */
164 RTEFISIGTYPE_SHA256 = RTEFISIGTYPE_FIRST_VALID,
165 /** Signature contains a RSA2048 key (only the modulus in big endian form,
166 * the exponent is always 65537/0x10001). */
167 RTEFISIGTYPE_RSA2048,
168 /** Signature contains a RSA2048 signature of a SHA256 hash. */
169 RTEFISIGTYPE_RSA2048_SHA256,
170 /** Signature contains a SHA1 hash. */
171 RTEFISIGTYPE_SHA1,
172 /** Signature contains a RSA2048 signature of a SHA1 hash. */
173 RTEFISIGTYPE_RSA2048_SHA1,
174 /** Signature contains a DER encoded X.509 certificate. */
175 RTEFISIGTYPE_X509,
176 /** First invalid type (do not use). */
177 RTEFISIGTYPE_FIRST_INVALID,
178 /** 32bit blowup hack.*/
179 RTEFISIGTYPE_32BIT_HACK = 0x7fffffff
180} RTEFISIGTYPE;
181
182
183/**
184 * EFI signature database enumeration callback.
185 *
186 * @returns IPRT status code, any status code other than VINF_SUCCESS will abort the enumeration.
187 * @param hEfiSigDb Handle to the EFI signature database this callback is called on.
188 * @param enmSigType The signature type.
189 * @param pUuidOwner Signature owner UUID.
190 * @param pvSig The signature data (dependent on the type).
191 * @param cbSig Size of the signature in bytes.
192 * @param pvUser Opaque user data passed in RTEfiSigDbEnum().
193 */
194typedef DECLCALLBACKTYPE(int, FNRTEFISIGDBENUMSIG,(RTEFISIGDB hEfiSigDb, RTEFISIGTYPE enmSigType, PCRTUUID pUuidOwner,
195 const void *pvSig, size_t cbSig, void *pvUser));
196/** Pointer to a EFI signature database enumeration callback. */
197typedef FNRTEFISIGDBENUMSIG *PFNRTEFISIGDBENUMSIG;
198
199
200/**
201 * Creates an empty EFI signature database.
202 *
203 * @returns IPRT status code.
204 * @param phEfiSigDb Where to store the handle to the empty EFI signature database on success.
205 */
206RTDECL(int) RTEfiSigDbCreate(PRTEFISIGDB phEfiSigDb);
207
208
209/**
210 * Destroys the given EFI signature database handle.
211 *
212 * @returns IPRT status code.
213 * @param hEfiSigDb The EFI signature database handle to destroy.
214 */
215RTDECL(int) RTEfiSigDbDestroy(RTEFISIGDB hEfiSigDb);
216
217
218/**
219 * Adds the signatures from an existing signature database contained in the given file.
220 *
221 * @returns IPRT status code.
222 * @param hEfiSigDb The EFI signature database handle.
223 * @param hVfsFileIn The file handle containing the existing signature database.
224 */
225RTDECL(int) RTEfiSigDbAddFromExistingDb(RTEFISIGDB hEfiSigDb, RTVFSFILE hVfsFileIn);
226
227
228/**
229 * Adds a new signature to the given signature database from the given file.
230 *
231 * @returns IPRT status code.
232 * @param hEfiSigDb The EFI signature database handle.
233 * @param enmSigType Type of the signature.
234 * @param pUuidOwner The UUID of the signature owner.
235 * @param hVfsFileIn File handle containing the signature data.
236 */
237RTDECL(int) RTEfiSigDbAddSignatureFromFile(RTEFISIGDB hEfiSigDb, RTEFISIGTYPE enmSigType, PCRTUUID pUuidOwner, RTVFSFILE hVfsFileIn);
238
239
240/**
241 * Adds a new signature to the given signature database from the given buffer.
242 *
243 * @returns IPRT status code.
244 * @param hEfiSigDb The EFI signature database handle.
245 * @param enmSigType Type of the signature.
246 * @param pUuidOwner The UUID of the signature owner.
247 * @param pvBuf Pointer to the signature data.
248 * @param cbBuf Size of the signature data in bytes.
249 */
250RTDECL(int) RTEfiSigDbAddSignatureFromBuf(RTEFISIGDB hEfiSigDb, RTEFISIGTYPE enmSigType, PCRTUUID pUuidOwner,
251 const void *pvBuf, size_t cbBuf);
252
253
254/**
255 * Writes the given EFI signature database to the given file.
256 *
257 * @returns IPRT status code.
258 * @param hEfiSigDb The EFI signature database handle.
259 * @param hVfsFileOut The file handle to write the signature database to.
260 */
261RTDECL(int) RTEfiSigDbWriteToFile(RTEFISIGDB hEfiSigDb, RTVFSFILE hVfsFileOut);
262
263
264/**
265 * Enumerate all signatures in the given EFI signature database.
266 *
267 * @returns IPRT status code.
268 * @param hEfiSigDb The EFI signature database handle.
269 * @param pfnEnumSig The callback to call for each signature.
270 * @param pvUser Opaque user data to pass to the callback.
271 */
272RTDECL(int) RTEfiSigDbEnum(RTEFISIGDB hEfiSigDb, PFNRTEFISIGDBENUMSIG pfnEnumSig, void *pvUser);
273
274
275/**
276 * Returns a human readable string of the given signature type.
277 *
278 * @returns Human readable string.
279 * @param enmSigType The signature type.
280 */
281RTDECL(const char *) RTEfiSigDbTypeStringify(RTEFISIGTYPE enmSigType);
282
283
284/**
285 * Returns a pointer to the EFI GUID identifying the given signature type.
286 *
287 * @returns Pointer to the EFI GUID.
288 * @param enmSigType The signature type.
289 */
290RTDECL(PCEFI_GUID) RTEfiSigDbTypeGetGuid(RTEFISIGTYPE enmSigType);
291
292#endif /* IN_RING3 */
293
294/** @} */
295
296RT_C_DECLS_END
297
298#endif /* !IPRT_INCLUDED_efi_h */
299
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette