EFI_VARIABLE_T(3)

✨ EFI_VARIABLE_T ✨

okay so bestie, this is a page from the Library Functions Manual (section 3, we're in C library land 💅) and it's all about efi_variable_t — the little in-memory glow-up for UEFI variables. let's get into it 🦋

🎀 NAME 🎀

efi_variable_import, efi_variable_export, efi_variable_alloc, efi_variable_free, efi_variable_set_name, efi_variable_get_name, efi_variable_set_guid, efi_variable_get_guid, efi_variable_set_data, efi_variable_get_data, efi_variable_set_attributes, efi_variable_get_attributes, efi_variable_realize — these are the utility functions that import and export UEFI variables to files. that's the whole vibe. 🫶

🌈 SYNOPSIS 🌈

#include <efivar.h>

typedef struct efi_variable efi_variable_t;

ssize_t efi_variable_import(uint8_t *data, size_t size, efi_variable_t **var);
ssize_t efi_variable_export(efi_variable_t *var, uint8_t **data, size_t *size);

efi_variable_t *efi_variable_alloc(void);
void efi_variable_free(efi_variable_t *var, int free_data);

int efi_variable_set_name(efi_variable_t *var, char *name);
char *efi_variable_get_name(efi_variable_t *var);

int efi_variable_set_guid(efi_variable_t *var, efi_guid_t *guid);
int efi_variable_get_guid(efi_variable_t *var, efi_guid_t **guid);

int efi_variable_set_data(efi_variable_t *var, uint8_t *data, size_t size);
int efi_variable_get_data(efi_variable_t *var, uint8_t **data, size_t *size);

#define EFI_VARIABLE_NON_VOLATILE 0x0000000000000001
#define EFI_VARIABLE_BOOTSERVICE_ACCESS 0x0000000000000002
#define EFI_VARIABLE_RUNTIME_ACCESS 0x0000000000000004
#define EFI_VARIABLE_HARDWARE_ERROR_RECORD 0x0000000000000008
#define EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS 0x0000000000000010
#define EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS 0x0000000000000020
#define EFI_VARIABLE_APPEND_WRITE 0x0000000000000040
#define EFI_VARIABLE_HAS_AUTH_HEADER 0x0000000100000000
#define EFI_VARIABLE_HAS_SIGNATURE 0x0000000200000000

int efi_variable_set_attributes(efi_variable_t *var, uint64_t attrs);
int efi_variable_get_attributes(efi_variable_t *var, uint64_t *attrs);

int efi_variable_realize(efi_variable_t *var);

💖 DESCRIPTION 💖

so efi_variable_t is an opaque data type, right? its whole job is holding variables in-memory so the rest of this API can play with them. mysterious. iconic. we don't need to know its inner workings, we just need to know it's there for us. 💅

🍓 importing & exporting

efi_variable_import() is your girl for pulling in raw data that was read from a file. she returns the amount of data consumed by this variable, and — plot twist — you can call her over and over again, using her return code as an offset, to chew through a whole list of variables. ate. 🔥

heads up bestie: the internal guid, name, and data values are allocated separately, so they gotta be freed either individually or via the free_data parameter of efi_variable_free(). the _get() accessors for those values hand you back data that's suitable for freeing individually — except in those cases where a _set() accessor was passed an object that was already unsuitable for that. 😭

efi_variable_export() does the reverse glow-up: she marshalls efi_variable_t objects into linear data you can write to a file. and here's the cute part — if you don't provide the data or size parameters, she'll just tell you how much storage a caller must allocate. otherwise, efi_variable_export() will use the storage referred to as its buffer; and if size is smaller than the amount of needed storage, the buffer will not be modified, and the difference between the needed space and size will be returned. no cap. ✨

🧚 allocating & freeing

efi_variable_alloc() allocates you an unpopulated efi_variable_t object — a blank canvas, suitable to be used throughout this whole API. efi_variable_free() is her counterpart: she frees an efi_variable_t object, and if free_data is nonzero, she also frees its constituent data. clean up after yourself, periodt. 🎀

🦋 the accessor lore

each pair of _set() and _get() accessors has essentially the same semantics. and listen — neither operation performs any memory management, including freeing previously set values or values that got set by efi_variable_import(). so in some cases you may need to use a _get() accessor to retrieve an object that you then free yourself. and if no value has been set? _get() accessors will set errno to ENOENT and return a negative value or NULL. noted. 💀

👑 the individual accessors

• efi_variable_set_name() and efi_variable_get_name() — set and retrieve the name of the variable that the efi_variable_t object is referring to.
• efi_variable_set_guid() and efi_variable_get_guid() — set and retrieve the Vendor GUID value of the variable that the efi_variable_t object is referring to.
• efi_variable_set_data() and efi_variable_get_data() — set and retrieve an efi_variable_t object's variable data.
• efi_variable_set_attributes() and efi_variable_get_attributes — set and retrieve an efi_variable_t object's attributes.

🌸 about those attributes

all bits except EFI_VARIABLE_HAS_AUTH_HEADER and EFI_VARIABLE_HAS_SIGNATURE are defined in the UEFI specification and should be used accordingly. fr fr.

EFI_VARIABLE_HAS_AUTH_HEADER should be used by applications to track whether the variable data contents include an authentication header.

EFI_VARIABLE_HAS_SIGNATURE should be used by applications to track if the variable's data contents include a signature — and it should not be set unless EFI_VARIABLE_HAS_AUTH_HEADER is also set. read that twice bestie. 🙈

these attributes are how you track whether an exported variable is in a state of partial construction — for example, if an authenticated variable has been created but is intended to be signed at a later date. werk-in-progress energy. 💜

🌟 realize

efi_variable_realize() is a convenience function — she sets or appends a UEFI variable on the running system from an efi_variable_t object. her return codes are the same as efi_append_variable(3) if EFI_VARIABLE_APPEND_WRITE is set, and efi_set_variable() if that bit is not set.

additionally, in the case that any of the authentication bits are set, efi_variable_realize() will return an error and set errno to EPERM unless both the EFI_VARIABLE_HAS_AUTH_HEADER and EFI_VARIABLE_HAS_SIGNATURE attribute bits have been set. so like… no half-signed shenanigans. 💅

⭐ RETURN VALUE ⭐

• efi_variable_import() returns 0 on success, and -1 on failure. in cases where it can't parse the data, errno will be set to EINVAL. in cases where memory has been exhausted, errno will be set to ENOMEM. 😭
• efi_variable_export() returns the size of the buffer data on success, or a negative value in the case of an error. if the data or size parameters are not provided, this function will return how much storage a caller must allocate. otherwise, this function will use the storage provided in data; if size is less than the needed space, the buffer will not be modified, and the return value will be the difficiency in size. 🫶
• efi_variable_alloc() returns a newly allocated efi_variable_t object — but she does not perform any allocation for that object's name, guid, or data. in the case that memory is exhausted, NULL will be returned, and errno will be set to ENOMEM. 💀
• efi_variable_get_name() returns a pointer to the NUL-terminated string containing the efi_variable_t object's name information. ✨
• efi_variable_set_name(), efi_variable_set_guid(), efi_variable_get_guid(), efi_variable_set_data(), efi_variable_get_data(), efi_variable_set_attributes(), efi_variable_get_attributes(), and efi_variable_realize() return 0 on success and -1 on error. that's it, that's the rule. 👑

🎀 AUTHORS 🎀

Peter Jones <pjones@redhat.com> — the icon, the moment, the legend. 👑

and that's the whole page bestie!! this one's from Thu Nov 11 2014, out of the EFI_VARIABLE_T(3) manual — go forth and import/export your variables responsibly, mwah 💖🦋🌸