Define qapi schema for the uefi variable store state.
Use it and the generated visitor helper functions to store persistent
(EFI_VARIABLE_NON_VOLATILE) variables in JSON format on disk.
Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
---
hw/uefi/var-service-json.c | 243 +++++++++++++++++++++++++++++++++++++
qapi/meson.build | 1 +
qapi/qapi-schema.json | 1 +
qapi/uefi.json | 55 +++++++++
4 files changed, 300 insertions(+)
create mode 100644 hw/uefi/var-service-json.c
create mode 100644 qapi/uefi.json
diff --git a/hw/uefi/var-service-json.c b/hw/uefi/var-service-json.c
new file mode 100644
index 000000000000..761082c11fc1
--- /dev/null
+++ b/hw/uefi/var-service-json.c
@@ -0,0 +1,243 @@
+/*
+ * SPDX-License-Identifier: GPL-2.0-or-later
+ *
+ * uefi vars device - serialize non-volatile varstore from/to json,
+ * using qapi
+ *
+ * tools which can read/write these json files:
+ * - https://gitlab.com/kraxel/virt-firmware
+ * - https://github.com/awslabs/python-uefivars
+ */
+#include "qemu/osdep.h"
+#include "qemu/cutils.h"
+#include "qemu/error-report.h"
+#include "system/dma.h"
+
+#include "hw/uefi/var-service.h"
+
+#include "qobject/qobject.h"
+#include "qobject/qjson.h"
+
+#include "qapi/dealloc-visitor.h"
+#include "qapi/qobject-input-visitor.h"
+#include "qapi/qobject-output-visitor.h"
+#include "qapi/qapi-types-uefi.h"
+#include "qapi/qapi-visit-uefi.h"
+
+static char *generate_hexstr(void *data, size_t len)
+{
+ static const char hex[] = {
+ '0', '1', '2', '3', '4', '5', '6', '7',
+ '8', '9', 'a', 'b', 'c', 'd', 'e', 'f',
+ };
+ uint8_t *src = data;
+ char *dest;
+ size_t i;
+
+ dest = g_malloc(len * 2 + 1);
+ for (i = 0; i < len * 2;) {
+ dest[i++] = hex[*src >> 4];
+ dest[i++] = hex[*src & 15];
+ src++;
+ }
+ dest[i++] = 0;
+
+ return dest;
+}
+
+static UefiVarStore *uefi_vars_to_qapi(uefi_vars_state *uv)
+{
+ UefiVarStore *vs;
+ UefiVariableList **tail;
+ UefiVariable *v;
+ QemuUUID be;
+ uefi_variable *var;
+
+ vs = g_new0(UefiVarStore, 1);
+ vs->version = 2;
+ tail = &vs->variables;
+
+ QTAILQ_FOREACH(var, &uv->variables, next) {
+ if (!(var->attributes & EFI_VARIABLE_NON_VOLATILE)) {
+ continue;
+ }
+
+ v = g_new0(UefiVariable, 1);
+ be = qemu_uuid_bswap(var->guid);
+ v->guid = qemu_uuid_unparse_strdup(&be);
+ v->name = uefi_ucs2_to_ascii(var->name, var->name_size);
+ v->attr = var->attributes;
+
+ v->data = generate_hexstr(var->data, var->data_size);
+
+ if (var->attributes &
+ EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS) {
+ v->time = generate_hexstr(&var->time, sizeof(var->time));
+ if (var->digest && var->digest_size) {
+ v->digest = generate_hexstr(var->digest, var->digest_size);
+ }
+ }
+
+ QAPI_LIST_APPEND(tail, v);
+ }
+ return vs;
+}
+
+static unsigned parse_hexchar(char c)
+{
+ switch (c) {
+ case '0' ... '9': return c - '0';
+ case 'a' ... 'f': return c - 'a' + 0xa;
+ case 'A' ... 'F': return c - 'A' + 0xA;
+ default: return 0;
+ }
+}
+
+static void parse_hexstr(void *dest, char *src, int len)
+{
+ uint8_t *data = dest;
+ size_t i;
+
+ for (i = 0; i < len; i += 2) {
+ *(data++) =
+ parse_hexchar(src[i]) << 4 |
+ parse_hexchar(src[i + 1]);
+ }
+}
+
+static void uefi_vars_from_qapi(uefi_vars_state *uv, UefiVarStore *vs)
+{
+ UefiVariableList *item;
+ UefiVariable *v;
+ QemuUUID be;
+ uefi_variable *var;
+ uint8_t *data;
+ size_t i, len;
+
+ for (item = vs->variables; item != NULL; item = item->next) {
+ v = item->value;
+
+ var = g_new0(uefi_variable, 1);
+ var->attributes = v->attr;
+ qemu_uuid_parse(v->guid, &be);
+ var->guid = qemu_uuid_bswap(be);
+
+ len = strlen(v->name);
+ var->name_size = len * 2 + 2;
+ var->name = g_malloc(var->name_size);
+ for (i = 0; i <= len; i++) {
+ var->name[i] = v->name[i];
+ }
+
+ len = strlen(v->data);
+ var->data_size = len / 2;
+ var->data = data = g_malloc(var->data_size);
+ parse_hexstr(var->data, v->data, len);
+
+ if (v->time && strlen(v->time) == 32) {
+ parse_hexstr(&var->time, v->time, 32);
+ }
+
+ if (v->digest) {
+ len = strlen(v->digest);
+ var->digest_size = len / 2;
+ var->digest = g_malloc(var->digest_size);
+ parse_hexstr(var->digest, v->digest, len);
+ }
+
+ QTAILQ_INSERT_TAIL(&uv->variables, var, next);
+ }
+}
+
+static GString *uefi_vars_to_json(uefi_vars_state *uv)
+{
+ UefiVarStore *vs = uefi_vars_to_qapi(uv);
+ QObject *qobj = NULL;
+ Visitor *v;
+ GString *gstr;
+
+ v = qobject_output_visitor_new(&qobj);
+ if (visit_type_UefiVarStore(v, NULL, &vs, NULL)) {
+ visit_complete(v, &qobj);
+ }
+ visit_free(v);
+ qapi_free_UefiVarStore(vs);
+
+ gstr = qobject_to_json_pretty(qobj, true);
+ qobject_unref(qobj);
+
+ return gstr;
+}
+
+void uefi_vars_json_init(uefi_vars_state *uv, Error **errp)
+{
+ if (uv->jsonfile) {
+ uv->jsonfd = qemu_create(uv->jsonfile, O_RDWR, 0666, errp);
+ }
+}
+
+void uefi_vars_json_save(uefi_vars_state *uv)
+{
+ GString *gstr;
+ int rc;
+
+ if (uv->jsonfd == -1) {
+ return;
+ }
+
+ gstr = uefi_vars_to_json(uv);
+
+ lseek(uv->jsonfd, 0, SEEK_SET);
+ rc = ftruncate(uv->jsonfd, 0);
+ if (rc != 0) {
+ warn_report("%s: ftruncate error", __func__);
+ }
+ rc = write(uv->jsonfd, gstr->str, gstr->len);
+ if (rc != gstr->len) {
+ warn_report("%s: write error", __func__);
+ }
+ fsync(uv->jsonfd);
+
+ g_string_free(gstr, true);
+}
+
+void uefi_vars_json_load(uefi_vars_state *uv, Error **errp)
+{
+ UefiVarStore *vs;
+ QObject *qobj;
+ Visitor *v;
+ char *str;
+ size_t len;
+ int rc;
+
+ if (uv->jsonfd == -1) {
+ return;
+ }
+
+ len = lseek(uv->jsonfd, 0, SEEK_END);
+ if (len == 0) {
+ return;
+ }
+
+ str = g_malloc(len + 1);
+ lseek(uv->jsonfd, 0, SEEK_SET);
+ rc = read(uv->jsonfd, str, len);
+ if (rc != len) {
+ warn_report("%s: read error", __func__);
+ }
+ str[len] = 0;
+
+ qobj = qobject_from_json(str, errp);
+ v = qobject_input_visitor_new(qobj);
+ visit_type_UefiVarStore(v, NULL, &vs, errp);
+ visit_free(v);
+
+ if (!(*errp)) {
+ uefi_vars_from_qapi(uv, vs);
+ uefi_vars_update_storage(uv);
+ }
+
+ qapi_free_UefiVarStore(vs);
+ qobject_unref(qobj);
+ g_free(str);
+}
diff --git a/qapi/meson.build b/qapi/meson.build
index e7bc54e5d047..eadde4db307f 100644
--- a/qapi/meson.build
+++ b/qapi/meson.build
@@ -65,6 +65,7 @@ if have_system
'pci',
'rocker',
'tpm',
+ 'uefi',
]
endif
if have_system or have_tools
diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json
index b1581988e4eb..2877aff73d0c 100644
--- a/qapi/qapi-schema.json
+++ b/qapi/qapi-schema.json
@@ -81,3 +81,4 @@
{ 'include': 'vfio.json' }
{ 'include': 'cryptodev.json' }
{ 'include': 'cxl.json' }
+{ 'include': 'uefi.json' }
diff --git a/qapi/uefi.json b/qapi/uefi.json
new file mode 100644
index 000000000000..c1dfa76b6eb2
--- /dev/null
+++ b/qapi/uefi.json
@@ -0,0 +1,55 @@
+# -*- Mode: Python -*-
+# vim: filetype=python
+#
+
+##
+# = UEFI Variable Store
+#
+# The qemu efi variable store implementation (hw/uefi/) uses this to
+# store non-volatile variables on disk.
+##
+
+##
+# @UefiVariable:
+#
+# UEFI Variable. Check the UEFI specifification for more detailed
+# information on the fields.
+#
+# @guid: variable namespace GUID
+#
+# @name: variable name, in UTF-8 encoding.
+#
+# @attr: variable attributes.
+#
+# @data: variable value, encoded as hex string.
+#
+# @time: variable modification time. EFI_TIME struct, encoded as hex
+# string. Used only for authenticated variables, where the
+# EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS attribute bit
+# is set.
+#
+# @digest: variable certificate digest. Used to verify the signature
+# of updates for authenticated variables.
+#
+# Since: 10.0
+##
+{ 'struct' : 'UefiVariable',
+ 'data' : { 'guid' : 'str',
+ 'name' : 'str',
+ 'attr' : 'int',
+ 'data' : 'str',
+ '*time' : 'str',
+ '*digest' : 'str'}}
+
+##
+# @UefiVarStore:
+#
+# @version: currently allways 2
+#
+# @variables: list of UEFI variables
+#
+# Since: 10.0
+##
+{ 'struct' : 'UefiVarStore',
+ 'data' : { 'version' : 'int',
+ 'variables' : [ 'UefiVariable' ] }}
--
2.48.1Gerd Hoffmann <kraxel@redhat.com> writes:
> Define qapi schema for the uefi variable store state.
>
> Use it and the generated visitor helper functions to store persistent
> (EFI_VARIABLE_NON_VOLATILE) variables in JSON format on disk.
>
> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
[...]
> diff --git a/qapi/meson.build b/qapi/meson.build
> index e7bc54e5d047..eadde4db307f 100644
> --- a/qapi/meson.build
> +++ b/qapi/meson.build
> @@ -65,6 +65,7 @@ if have_system
> 'pci',
> 'rocker',
> 'tpm',
> + 'uefi',
> ]
> endif
> if have_system or have_tools
> diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json
> index b1581988e4eb..2877aff73d0c 100644
> --- a/qapi/qapi-schema.json
> +++ b/qapi/qapi-schema.json
> @@ -81,3 +81,4 @@
> { 'include': 'vfio.json' }
> { 'include': 'cryptodev.json' }
> { 'include': 'cxl.json' }
> +{ 'include': 'uefi.json' }
> diff --git a/qapi/uefi.json b/qapi/uefi.json
> new file mode 100644
> index 000000000000..c1dfa76b6eb2
> --- /dev/null
> +++ b/qapi/uefi.json
> @@ -0,0 +1,55 @@
> +# -*- Mode: Python -*-
> +# vim: filetype=python
> +#
> +
> +##
> +# = UEFI Variable Store
> +#
> +# The qemu efi variable store implementation (hw/uefi/) uses this to
> +# store non-volatile variables on disk.
> +##
> +
> +##
> +# @UefiVariable:
> +#
> +# UEFI Variable. Check the UEFI specifification for more detailed
> +# information on the fields.
> +#
> +# @guid: variable namespace GUID
> +#
> +# @name: variable name, in UTF-8 encoding.
> +#
> +# @attr: variable attributes.
> +#
> +# @data: variable value, encoded as hex string.
I understand this is a blob. We commonly use base64 for that. Why not
here?
> +#
> +# @time: variable modification time. EFI_TIME struct, encoded as hex
> +# string. Used only for authenticated variables, where the
> +# EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS attribute bit
> +# is set.
> +#
> +# @digest: variable certificate digest. Used to verify the signature
> +# of updates for authenticated variables.
How to create and verify these digests will be obvious enough to users
of this interface?
> +#
> +# Since: 10.0
> +##
> +{ 'struct' : 'UefiVariable',
> + 'data' : { 'guid' : 'str',
> + 'name' : 'str',
> + 'attr' : 'int',
> + 'data' : 'str',
> + '*time' : 'str',
> + '*digest' : 'str'}}
> +
> +##
> +# @UefiVarStore:
> +#
> +# @version: currently allways 2
always
> +#
> +# @variables: list of UEFI variables
> +#
> +# Since: 10.0
> +##
> +{ 'struct' : 'UefiVarStore',
> + 'data' : { 'version' : 'int',
> + 'variables' : [ 'UefiVariable' ] }}
Hi, > > +# @data: variable value, encoded as hex string. > > I understand this is a blob. We commonly use base64 for that. Why not > here? It's an existing format already supported by other tools. Guess I should add that to the preamble. > > +# @digest: variable certificate digest. Used to verify the signature > > +# of updates for authenticated variables. > > How to create and verify these digests will be obvious enough to users > of this interface? Well, no. It's a somewhat complicated story ... UEFI has two kinds of authenticated variables. First, the secure boot variables (PK, KEK, db, dbx). These have hard-coded rules, the rule most relevant in practice is that signed update requests for the 'db' and 'dbx' variables are checked against the 'KEK' certificate database. For other authenticated variables UEFI essentially remembers the certificate when the variable is created, and any update / delete requests need a signature from the same certificate (simplified a bit to keep it short, the actual rules are more complicated, details are in the UEFI spec). This digest handles the "remembers the certificate" part. In practice the second kind of authenticated variables is rarely used. I have yet to see a piece of software actually using that in practice (other than the test case I have written). Also note that this is *not* part of the QMP interface. The driver uses this to store the efi variable store in json format on disk (see var-service-json.c in this patch). Adding support for reading/writing uefi variables is something we might add to the monitor in the future. Should that happen it is not clear whenever such an interface would actually use the raw 'UefiVariable' struct or if higher-level interfaces would be more useful. For example a command to query whenever the guest has secure boot turned on. take care, Gerd
Gerd Hoffmann <kraxel@redhat.com> writes: > Hi, > >> > +# @data: variable value, encoded as hex string. >> >> I understand this is a blob. We commonly use base64 for that. Why not >> here? > > It's an existing format already supported by other tools. Having a second format for blobs is unfortunate. I can't judge whether the convenience of sharing the format with other tools is worth the additional interface complexity and code. It could be if it avoids having to re-encode from hex to base64 in multiple places. Got to trust your judgement here. > Guess I > should add that to the preamble. Commit messages are usually a good home for rationale. >> > +# @digest: variable certificate digest. Used to verify the signature >> > +# of updates for authenticated variables. >> >> How to create and verify these digests will be obvious enough to users >> of this interface? > > Well, no. It's a somewhat complicated story ... > > UEFI has two kinds of authenticated variables. First, the secure boot > variables (PK, KEK, db, dbx). These have hard-coded rules, the rule > most relevant in practice is that signed update requests for the 'db' > and 'dbx' variables are checked against the 'KEK' certificate database. > > For other authenticated variables UEFI essentially remembers the > certificate when the variable is created, and any update / delete > requests need a signature from the same certificate (simplified a > bit to keep it short, the actual rules are more complicated, details > are in the UEFI spec). > > This digest handles the "remembers the certificate" part. > > In practice the second kind of authenticated variables is rarely used. > I have yet to see a piece of software actually using that in practice > (other than the test case I have written). > > > Also note that this is *not* part of the QMP interface. The driver uses > this to store the efi variable store in json format on disk (see > var-service-json.c in this patch). > > Adding support for reading/writing uefi variables is something we might > add to the monitor in the future. Should that happen it is not clear > whenever such an interface would actually use the raw 'UefiVariable' > struct or if higher-level interfaces would be more useful. For example > a command to query whenever the guest has secure boot turned on. I wonder how much of this, if anything, should be worked into the doc comment. You decide :) With the typo I pointed out fixed: Acked-by: Markus Armbruster <armbru@redhat.com>
> >> > +# @digest: variable certificate digest. Used to verify the signature
> >> > +# of updates for authenticated variables.
> >>
> >> How to create and verify these digests will be obvious enough to users
> >> of this interface?
> >
> > Well, no. It's a somewhat complicated story ...
> I wonder how much of this, if anything, should be worked into the doc
> comment. You decide :)
A bit verbose for something rarely used. Tried to summarize it,
incremental update below:
take care,
Gerd
------------------------- cut here -----------------------
commit 3d2ef31cbd70f4637330fe8d8418befd907899c4
Author: Gerd Hoffmann <kraxel@redhat.com>
Date: Wed Feb 26 09:07:10 2025 +0100
[fixup] qapi docs
diff --git a/qapi/uefi.json b/qapi/uefi.json
index c1dfa76b6eb2..bdfcabe1df4d 100644
--- a/qapi/uefi.json
+++ b/qapi/uefi.json
@@ -6,7 +6,11 @@
# = UEFI Variable Store
#
# The qemu efi variable store implementation (hw/uefi/) uses this to
-# store non-volatile variables on disk.
+# store non-volatile variables in json format on disk.
+#
+# This is an existing format already supported by (at least) two other
+# projects, specifically https://gitlab.com/kraxel/virt-firmware and
+# https://github.com/awslabs/python-uefivars.
##
##
@@ -29,7 +33,12 @@
# is set.
#
# @digest: variable certificate digest. Used to verify the signature
-# of updates for authenticated variables.
+# of updates for authenticated variables. UEFI has two kinds of
+# authenticated variables. The secure boot variables ('PK',
+# 'KEK', 'db' and 'dbx') have hard coded signature checking rules.
+# For other authenticated variables the firmware stores a digest
+# of the signing certificate at variable creation time, and any
+# updates must be signed with the same certificate.
#
# Since: 10.0
##
@@ -44,7 +53,7 @@
##
# @UefiVarStore:
#
-# @version: currently allways 2
+# @version: currently always 2
#
# @variables: list of UEFI variables
#
Gerd Hoffmann <kraxel@redhat.com> writes: >> >> > +# @digest: variable certificate digest. Used to verify the signature >> >> > +# of updates for authenticated variables. >> >> >> >> How to create and verify these digests will be obvious enough to users >> >> of this interface? >> > >> > Well, no. It's a somewhat complicated story ... > >> I wonder how much of this, if anything, should be worked into the doc >> comment. You decide :) > > A bit verbose for something rarely used. Tried to summarize it, > incremental update below: Looks good to me; Acked-by stands. Thanks!
© 2016 - 2025 Red Hat, Inc.