Document struct mok_state_variable better.

Add a pile of documentation comments to help remember what all the
fields in our mok mirroring structure do.

Signed-off-by: Peter Jones <pjones@redhat.com>

1 files changed, 47 insertions, 10 deletions

diff --git a/mok.c b/mok.c
index c8de6a69..c3288994 100644
--- a/mok.c
+++ b/mok.c
@@ -78,29 +78,66 @@ typedef vendor_addend_category_t (vendor_addend_categorizer_t)(struct mok_state_
  * tpm as well.
  */
 struct mok_state_variable {
-	CHAR16 *name;
-	char *name8;
-	CHAR16 *rtname;
-	char *rtname8;
-	EFI_GUID *guid;
+	CHAR16 *name;	/* UCS-2 BS|NV variable name */
+	char *name8;	/* UTF-8 BS|NV variable name */
+	CHAR16 *rtname;	/* UCS-2 RT variable name */
+	char *rtname8;	/* UTF-8 RT variable name */
+	EFI_GUID *guid;	/* variable GUID */
 
+	/*
+	 * these are used during processing, they shouldn't be filled out
+	 * in the static table below.
+	 */
 	UINT8 *data;
 	UINTN data_size;
 
 	/*
+	 * addend are added to the input variable, as part of the runtime
+	 * variable, so that they're visible to the kernel.  These are
+	 * where we put vendor_cert / vendor_db / vendor_dbx
+	 *
 	 * These are indirect pointers just to make initialization saner...
 	 */
-	vendor_addend_categorizer_t *categorize_addend;
+	vendor_addend_categorizer_t *categorize_addend; /* determines format */
+	/*
+	 * we call categorize_addend() and it determines what kind of thing
+	 * this is.  That is, if this shim was built with VENDOR_CERT, for
+	 * the DB entry it'll return VENDOR_ADDEND_X509; if you used
+	 * VENDOR_DB instead, it'll return VENDOR_ADDEND_DB.  If you used
+	 * neither, it'll do VENDOR_ADDEND_NONE.
+	 *
+	 * The existing categorizers are for db and dbx; they differ
+	 * because we don't currently support a CERT for dbx.
+	 */
 	UINT8 **addend;
 	UINT32 *addend_size;
 
+	/*
+	 * build_cert is our build-time cert.  Like addend, this is added
+	 * to the input variable, as part of the runtime variable, so that
+	 * they're visible to the kernel.  This is the ephemeral cert used
+	 * for signing MokManager.efi and fallback.efi.
+	 *
+	 * These are indirect pointers just to make initialization saner...
+	 */
 	UINT8 **build_cert;
 	UINT32 *build_cert_size;
 
-	UINT32 yes_attr;
-	UINT32 no_attr;
-	UINT32 flags;
-	UINTN pcr;
+	UINT32 yes_attr;	/* var attrs that must be set */
+	UINT32 no_attr;		/* var attrs that must not be set */
+	UINT32 flags;		/* flags on what and how to mirror */
+	/*
+	 * MOK_MIRROR_KEYDB	    mirror this as a key database
+	 * MOK_MIRROR_DELETE_FIRST  delete any existing variable first
+	 * MOK_VARIABLE_MEASURE	    extend PCR 7 and log the hash change
+	 * MOK_VARIABLE_LOG	    measure into whatever .pcr says and log
+	 */
+	UINTN pcr;		/* PCR to measure and hash to */
+
+	/*
+	 * if this is a state value, a pointer to our internal state to be
+	 * mirrored.
+	 */
 	UINT8 *state;
 };