> >> > +# @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 <kra...@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
#
