299 lines
10 KiB
C
299 lines
10 KiB
C
/** @file
|
|
* IPRT - EFI related utilities.
|
|
*/
|
|
|
|
/*
|
|
* Copyright (C) 2021-2023 Oracle and/or its affiliates.
|
|
*
|
|
* This file is part of VirtualBox base platform packages, as
|
|
* available from https://www.virtualbox.org.
|
|
*
|
|
* This program is free software; you can redistribute it and/or
|
|
* modify it under the terms of the GNU General Public License
|
|
* as published by the Free Software Foundation, in version 3 of the
|
|
* License.
|
|
*
|
|
* This program is distributed in the hope that it will be useful, but
|
|
* WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
* General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with this program; if not, see <https://www.gnu.org/licenses>.
|
|
*
|
|
* The contents of this file may alternatively be used under the terms
|
|
* of the Common Development and Distribution License Version 1.0
|
|
* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
|
|
* in the VirtualBox distribution, in which case the provisions of the
|
|
* CDDL are applicable instead of those of the GPL.
|
|
*
|
|
* You may elect to license modified versions of this file under the
|
|
* terms and conditions of either the GPL or the CDDL or both.
|
|
*
|
|
* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
|
|
*/
|
|
|
|
#ifndef IPRT_INCLUDED_efi_h
|
|
#define IPRT_INCLUDED_efi_h
|
|
#ifndef RT_WITHOUT_PRAGMA_ONCE
|
|
# pragma once
|
|
#endif
|
|
|
|
#include <iprt/cdefs.h>
|
|
#include <iprt/types.h>
|
|
#include <iprt/time.h>
|
|
#include <iprt/vfs.h>
|
|
|
|
#include <iprt/formats/efi-common.h>
|
|
|
|
|
|
RT_C_DECLS_BEGIN
|
|
|
|
/** @defgroup grp_rt_efi RTEfi - EFI utilities
|
|
* @ingroup grp_rt
|
|
* @{
|
|
*/
|
|
|
|
|
|
#ifdef IN_RING3
|
|
|
|
/**
|
|
* Converts an EFI time to a time spec (UTC).
|
|
*
|
|
* @returns pTimeSpec on success.
|
|
* @returns NULL if the pEfiTime data is invalid.
|
|
* @param pTimeSpec Where to store the converted time.
|
|
* @param pEfiTime Pointer to the EFI time struct.
|
|
*/
|
|
RTDECL(PRTTIMESPEC) RTEfiTimeToTimeSpec(PRTTIMESPEC pTimeSpec, PCEFI_TIME pEfiTime);
|
|
|
|
|
|
/**
|
|
* Converts a time spec (UTC) to an EFI time.
|
|
*
|
|
* @returns pEfiTime on success.
|
|
* @returns NULL if the pTimeSpec data is invalid.
|
|
* @param pEfiTime Pointer to the EFI time struct.
|
|
* @param pTimeSpec The time spec to convert.
|
|
*/
|
|
RTDECL(PEFI_TIME) RTEfiTimeFromTimeSpec(PEFI_TIME pEfiTime, PCRTTIMESPEC pTimeSpec);
|
|
|
|
|
|
/**
|
|
* Converts the given EFI GUID to the IPRT UUID representation.
|
|
*
|
|
* @returns pUuid.
|
|
* @param pUuid Where to store the converted GUID.
|
|
* @param pEfiGuid The EFI GUID to convert.
|
|
*/
|
|
RTDECL(PRTUUID) RTEfiGuidToUuid(PRTUUID pUuid, PCEFI_GUID pEfiGuid);
|
|
|
|
|
|
/**
|
|
* Converts the given EFI GUID to the IPRT UUID representation.
|
|
*
|
|
* @returns pEfiGuid.
|
|
* @param pEfiGuid Where to store the converted UUID.
|
|
* @param pUuid The UUID to convert.
|
|
*/
|
|
RTDECL(PEFI_GUID) RTEfiGuidFromUuid(PEFI_GUID pEfiGuid, PCRTUUID pUuid);
|
|
|
|
|
|
/**
|
|
* Compares two EFI GUID values.
|
|
*
|
|
* @returns 0 if eq, < 0 or > 0.
|
|
* @param pGuid1 First value to compare.
|
|
* @param pGuid2 Second value to compare.
|
|
*/
|
|
RTDECL(int) RTEfiGuidCompare(PCEFI_GUID pGuid1, PCEFI_GUID pGuid2);
|
|
|
|
|
|
/**
|
|
* Opens an EFI variable store.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hVfsFileIn The file or device backing the store.
|
|
* @param fMntFlags RTVFSMNT_F_XXX.
|
|
* @param fVarStoreFlags Reserved, MBZ.
|
|
* @param phVfs Where to return the virtual file system handle.
|
|
* @param pErrInfo Where to return additional error information.
|
|
*/
|
|
RTDECL(int) RTEfiVarStoreOpenAsVfs(RTVFSFILE hVfsFileIn, uint32_t fMntFlags, uint32_t fVarStoreFlags, PRTVFS phVfs, PRTERRINFO pErrInfo);
|
|
|
|
|
|
/** @name RTEFIVARSTORE_CREATE_F_XXX - RTEfiVarStoreCreate flags
|
|
* @{ */
|
|
/** Use default options. */
|
|
#define RTEFIVARSTORE_CREATE_F_DEFAULT UINT32_C(0)
|
|
/** Don't create a fault tolerant write working space.
|
|
* The default is to create one reducing the size of the variable store. */
|
|
#define RTEFIVARSTORE_CREATE_F_NO_FTW_WORKING_SPACE RT_BIT_32(0)
|
|
/** Mask containing all valid flags. */
|
|
#define RTEFIVARSTORE_CREATE_F_VALID_MASK UINT32_C(0x00000001)
|
|
/** @} */
|
|
|
|
/**
|
|
* Creates a new EFI variable store.
|
|
*
|
|
* @returns IRPT status code.
|
|
* @param hVfsFile The store file.
|
|
* @param offStore The offset into @a hVfsFile of the file.
|
|
* Typically 0.
|
|
* @param cbStore The size of the variable store. Pass 0 if the rest of
|
|
* hVfsFile should be used. The remaining space for variables
|
|
* will be less because of some metadata overhead.
|
|
* @param fFlags See RTEFIVARSTORE_F_XXX.
|
|
* @param cbBlock The logical block size.
|
|
* @param pErrInfo Additional error information, maybe. Optional.
|
|
*/
|
|
RTDECL(int) RTEfiVarStoreCreate(RTVFSFILE hVfsFile, uint64_t offStore, uint64_t cbStore, uint32_t fFlags, uint32_t cbBlock,
|
|
PRTERRINFO pErrInfo);
|
|
|
|
|
|
/**
|
|
* EFI signature type.
|
|
*/
|
|
typedef enum RTEFISIGTYPE
|
|
{
|
|
/** Invalid type, do not use. */
|
|
RTEFISIGTYPE_INVALID = 0,
|
|
/** First valid signature type. */
|
|
RTEFISIGTYPE_FIRST_VALID,
|
|
/** Signature contains a SHA256 hash. */
|
|
RTEFISIGTYPE_SHA256 = RTEFISIGTYPE_FIRST_VALID,
|
|
/** Signature contains a RSA2048 key (only the modulus in big endian form,
|
|
* the exponent is always 65537/0x10001). */
|
|
RTEFISIGTYPE_RSA2048,
|
|
/** Signature contains a RSA2048 signature of a SHA256 hash. */
|
|
RTEFISIGTYPE_RSA2048_SHA256,
|
|
/** Signature contains a SHA1 hash. */
|
|
RTEFISIGTYPE_SHA1,
|
|
/** Signature contains a RSA2048 signature of a SHA1 hash. */
|
|
RTEFISIGTYPE_RSA2048_SHA1,
|
|
/** Signature contains a DER encoded X.509 certificate. */
|
|
RTEFISIGTYPE_X509,
|
|
/** First invalid type (do not use). */
|
|
RTEFISIGTYPE_FIRST_INVALID,
|
|
/** 32bit blowup hack.*/
|
|
RTEFISIGTYPE_32BIT_HACK = 0x7fffffff
|
|
} RTEFISIGTYPE;
|
|
|
|
|
|
/**
|
|
* EFI signature database enumeration callback.
|
|
*
|
|
* @returns IPRT status code, any status code other than VINF_SUCCESS will abort the enumeration.
|
|
* @param hEfiSigDb Handle to the EFI signature database this callback is called on.
|
|
* @param enmSigType The signature type.
|
|
* @param pUuidOwner Signature owner UUID.
|
|
* @param pvSig The signature data (dependent on the type).
|
|
* @param cbSig Size of the signature in bytes.
|
|
* @param pvUser Opaque user data passed in RTEfiSigDbEnum().
|
|
*/
|
|
typedef DECLCALLBACKTYPE(int, FNRTEFISIGDBENUMSIG,(RTEFISIGDB hEfiSigDb, RTEFISIGTYPE enmSigType, PCRTUUID pUuidOwner,
|
|
const void *pvSig, size_t cbSig, void *pvUser));
|
|
/** Pointer to a EFI signature database enumeration callback. */
|
|
typedef FNRTEFISIGDBENUMSIG *PFNRTEFISIGDBENUMSIG;
|
|
|
|
|
|
/**
|
|
* Creates an empty EFI signature database.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param phEfiSigDb Where to store the handle to the empty EFI signature database on success.
|
|
*/
|
|
RTDECL(int) RTEfiSigDbCreate(PRTEFISIGDB phEfiSigDb);
|
|
|
|
|
|
/**
|
|
* Destroys the given EFI signature database handle.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hEfiSigDb The EFI signature database handle to destroy.
|
|
*/
|
|
RTDECL(int) RTEfiSigDbDestroy(RTEFISIGDB hEfiSigDb);
|
|
|
|
|
|
/**
|
|
* Adds the signatures from an existing signature database contained in the given file.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hEfiSigDb The EFI signature database handle.
|
|
* @param hVfsFileIn The file handle containing the existing signature database.
|
|
*/
|
|
RTDECL(int) RTEfiSigDbAddFromExistingDb(RTEFISIGDB hEfiSigDb, RTVFSFILE hVfsFileIn);
|
|
|
|
|
|
/**
|
|
* Adds a new signature to the given signature database from the given file.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hEfiSigDb The EFI signature database handle.
|
|
* @param enmSigType Type of the signature.
|
|
* @param pUuidOwner The UUID of the signature owner.
|
|
* @param hVfsFileIn File handle containing the signature data.
|
|
*/
|
|
RTDECL(int) RTEfiSigDbAddSignatureFromFile(RTEFISIGDB hEfiSigDb, RTEFISIGTYPE enmSigType, PCRTUUID pUuidOwner, RTVFSFILE hVfsFileIn);
|
|
|
|
|
|
/**
|
|
* Adds a new signature to the given signature database from the given buffer.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hEfiSigDb The EFI signature database handle.
|
|
* @param enmSigType Type of the signature.
|
|
* @param pUuidOwner The UUID of the signature owner.
|
|
* @param pvBuf Pointer to the signature data.
|
|
* @param cbBuf Size of the signature data in bytes.
|
|
*/
|
|
RTDECL(int) RTEfiSigDbAddSignatureFromBuf(RTEFISIGDB hEfiSigDb, RTEFISIGTYPE enmSigType, PCRTUUID pUuidOwner,
|
|
const void *pvBuf, size_t cbBuf);
|
|
|
|
|
|
/**
|
|
* Writes the given EFI signature database to the given file.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hEfiSigDb The EFI signature database handle.
|
|
* @param hVfsFileOut The file handle to write the signature database to.
|
|
*/
|
|
RTDECL(int) RTEfiSigDbWriteToFile(RTEFISIGDB hEfiSigDb, RTVFSFILE hVfsFileOut);
|
|
|
|
|
|
/**
|
|
* Enumerate all signatures in the given EFI signature database.
|
|
*
|
|
* @returns IPRT status code.
|
|
* @param hEfiSigDb The EFI signature database handle.
|
|
* @param pfnEnumSig The callback to call for each signature.
|
|
* @param pvUser Opaque user data to pass to the callback.
|
|
*/
|
|
RTDECL(int) RTEfiSigDbEnum(RTEFISIGDB hEfiSigDb, PFNRTEFISIGDBENUMSIG pfnEnumSig, void *pvUser);
|
|
|
|
|
|
/**
|
|
* Returns a human readable string of the given signature type.
|
|
*
|
|
* @returns Human readable string.
|
|
* @param enmSigType The signature type.
|
|
*/
|
|
RTDECL(const char *) RTEfiSigDbTypeStringify(RTEFISIGTYPE enmSigType);
|
|
|
|
|
|
/**
|
|
* Returns a pointer to the EFI GUID identifying the given signature type.
|
|
*
|
|
* @returns Pointer to the EFI GUID.
|
|
* @param enmSigType The signature type.
|
|
*/
|
|
RTDECL(PCEFI_GUID) RTEfiSigDbTypeGetGuid(RTEFISIGTYPE enmSigType);
|
|
|
|
#endif /* IN_RING3 */
|
|
|
|
/** @} */
|
|
|
|
RT_C_DECLS_END
|
|
|
|
#endif /* !IPRT_INCLUDED_efi_h */
|
|
|