Add documentation of the Mok variables

Brief overview of the function and format of the various variables used
by Shim and MokManager.

1 files changed, 51 insertions, 0 deletions

diff --git a/MokVars.txt b/MokVars.txt
new file mode 100644
index 00000000..74f09083
--- /dev/null
+++ b/MokVars.txt
@@ -0,0 +1,51 @@
+Variables used by Shim and Mokmanager
+
+Request variables:
+
+MokPW: Set by MokUtil when setting a password. A SHA-256 hash of the 
+UCS-2 representation of the password. The user will be asked to 
+re-enter the password to confirm. If the hash of the entered password 
+matches the contents of MokPW, the user will be prompted to copy MokPW 
+into MokPWState. BS,RT,NV
+
+MokSB: Set by MokUtil when requesting a change in state of signature 
+validation. A packed structure as follows:
+
+typedef struct {
+        UINT32 MokSBState;
+        UINT32 PWLen;
+        CHAR16 Password[PASSWORD_MAX];
+} __attribute__ ((packed)) MokSBvar;
+
+If MokSBState is 0, the user will be prompted to disable signature 
+validation. Otherwise, the user will be prompted to enable it. PWLen 
+is the length of the password, in characters. Password is a UCS-2 
+representation of the password. The user will be prompted to enter 
+three randomly chosen characters from the password. If successful, 
+they will then be prompted to change the signature validation 
+according to MokSBState. BS,RT,NV
+
+MokNew: Set by MokUtil when requesting the addition or removal of keys 
+from MokList. Is an EFI_SIGNATURE_LIST as described in the UEFI 
+specification. BS,RT,NV
+
+MokAuth: A hash dependent upon the contents of MokNew and the sealing 
+password. The user's password in UCS-2 form should be appended to the 
+contents of MokNew and a SHA-256 hash generated and stored in MokAuth. 
+The hash will be regenerated by MokManager after the user is requested 
+to enter their password to confirm enrolment of the keys. If the hash 
+matches MokAuth, the user will be prompted to enrol the keys. BS,RT,NV
+
+State variables:
+
+MokList: A list of whitelisted keys and hashes. An EFI_SIGNATURE_LIST 
+as described in the UEFI specification. BS,NV
+
+MokListRT: A copy of MokList made available to the kernel at runtime. RT
+
+MokSBState: An 8-bit unsigned integer. If 1, shim will switch to 
+insecure mode. BS,NV
+
+MokPWStore: A SHA-256 representation of the password set by the user 
+via MokPW. The user will be prompted to enter this password in order 
+to interact with MokManager.