From 80ff1751183bd36b197ac19ed255e832af1f4fca Mon Sep 17 00:00:00 2001 From: Peter Jones Date: Thu, 18 Feb 2021 16:09:19 -0500 Subject: 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 --- mok.c | 57 +++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 47 insertions(+), 10 deletions(-) (limited to 'mok.c') 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; }; -- cgit v1.2.3