Default variables

TAs/optee_ta/AuthVars/README.md

@@ -24,6 +24,10 @@ The storage is currently encrypted by OP-TEE using a TA Storage Key (TSK) encryp
 
 The UEFI spec describes an authenticated variable store for use with Secure Boot. The TA supports variable reads and writes up to 16KB in size (this is a limitation of the rich OS side driver). This should allow for a reasonable set of Secure Boot keys to be stored.
 
+### Default Variables
+
+The AuthVar TA can encode a set of default variables at compile time, and place them into NV memory when it first runs. This is useful for forcing at default set of UEFI Secure Boot variables to be active during first boot, and as a protection against RPMB wipes. This can be turned on by setting `CFG_AUTHVARS_DEFAULT_VARS=y`. See [defaultvars/README.md](./defaultvars/README.md) for details on configuring this behavior.
+
 ## Debugging AuthVars
 
 ### Clearing Storage

TAs/optee_ta/AuthVars/defaultvars/README.md

@@ -0,0 +1,70 @@
+# Default Variables
+
+Setting `CFG_AUTHVARS_DEFAULT_VARS=y` will cause the AuthVars TA to ensure a set of default variables are present during first boot.
+
+If the TA detects that there is no pre-existing non-volatile storage it will set the default variables as if it received a call from UEFI. The name, GUID, attributes, and binary data of the variables are defined in a JSON file, passed via `CFG_DEFAULT_VARS_JSON=/path/to/vars.json`.
+
+## JSON File
+The JSON file pointed to by `CFG_DEFAULT_VARS_JSON=/path/to/vars.json` defines which variables will be added.
+
+* **`name:`** ECS-2 encodable string. Since the JSON file is saved as UTF-8 the unicode characters can be placed directly in the string.
+* **`bin_path:`** Path to the binary contents of the variable. If the variable is authenticated this binary should include the authentication headers. **If** the path is not absolute, it is taken relative to the AuthVars TA root directory (`MSRSec/TAs/optee_ta/AuthVars`).
+* **`guid:`** The variable GUID, must be valid C syntax. May also be one of the well known GUIDs `EFI_IMAGE_SECURITY_DATABASE_GUID` or `EFI_GLOBAL_VARIABLE`.
+* **`attributes:`** The attributes the variable should be saved with (from `uefidefs.h`). Must be valid C syntax.
+
+The variables will be saved into the AuthVar TA in the order they are found in the JSON file.
+
+```json
+{
+    "variables": [
+        {
+            "name": "Default Volatile Variable Example / (Supports ECS-2 characters ✍)",
+            "bin_path": "defaultvars/example.bin",
+            "guid": "{0xe4b297c1, 0x507d, 0x407f, {0xbe,0x4a,0xe9,0x25,0x68,0x69,0x25,0x14}}",
+            "attributes": "EFI_VARIABLE_APPEND_WRITE | EFI_VARIABLE_NON_VOLATILE | EFI_VARIABLE_RUNTIME_ACCESS | EFI_VARIABLE_BOOTSERVICE_ACCESS"
+        }
+    ]
+}
+```
+
+### Examples
+Two examples are included, along with binaries.
+
+The first example, `defaultvars_example.json`, is included by default if `CFG_DEFAULT_VARS_JSON` is left unset. It adds a single variable (as shown above).
+
+The second example, `defaultvars_secureboot_example.json` can be used by setting `CFG_DEFAULT_VARS_JSON=defaultvars/defaultvars_secureboot_example.json`. This example automatically enables secure boot using **NON-SECURE** keys from the [TurnkeySecurity](https://github.com/ms-iot/security/tree/master/TurnkeySecurity) repository. They are included for example purposes only. A production image must use newly generated signing keys.
+
+### Text Encoding of Variable Names
+The JSON file **must be `UTF-8` encoded**, as the python script explicitly decodes it as UTF-8. The JSON file may contain *MOST*, **but not all** unicode characters. UEFI uses ECS-2 encoding for its strings, a subset of UTF-16. ECS-2 does not allow 4-byte characters to be stored, so no UTF-16 surrogate pairs. Valid ECS-2 values are: `[0x0000, 0xd800] ∪ [0xdfff, 0xffff]`. The python script used to compile the variables will check the validity of the encoding for each character.
+
+
+## Compilation
+At compilation time `defaultvars.py` runs, taking the JSON file found at `CFG_DEFAULT_VARS_JSON`, and creating the file `$(sub-dir-out)/defaultvars_encoding.c`. This C file encodes each variable in the JSON file as a set of C variables:
+```c
+WCHAR var_0_name[] = L"Abcd" "\x1234" "5678";
+GUID var_0_guid = {0x12345678,0x9abc,0xdef0,{0x12,0x34,0x56,0x78,0x9A,0xBC,0xDE,0xF0}};
+ATTRIBUTES var_0_attributes = "EFI_VARIABLE_NON_VOLATILE | EFI_VARIABLE_RUNTIME_ACCESS | EFI_VARIABLE_BOOTSERVICE_ACCESS";
+BYTE var_0_bin[] = { 0x0, 0x1, 0x2, 0x3, ... };
+
+WCHAR var_2_name[] = L"XYZ" "\x1234" "5678";
+...
+```
+
+The generated C file also contains the definition for `InitializeDefaultVariables()`, which is defined in `defaultvars.h`, and is called during initialization of the TA in `AuthVarInitStorage()` if and only if there is no pre-existing non-volatile storage pressent (assuming `CFG_DEFAULT_VARS_JSON=y`).
+
+```c
+TEE_Result InitializeDefaultVariables( VOID ) {
+    TEE_Result res;
+
+    res = SetDefaultVariable(var_0_name, sizeof(var_0_name), var_0_bin, sizeof(var_0_bin), var_0_guid, var_0_attributes);
+    if (res != TEE_SUCCESS)
+        return res;
+
+    res = SetDefaultVariable(var_1_name, sizeof(var_1_name), var_1_bin, sizeof(var_1_bin), var_1_guid, var_1_attributes);
+    if (res != TEE_SUCCESS)
+        return res;
+
+    DMSG("Done setting 2 default variables");
+    return TEE_SUCCESS;
+}
+```

TAs/optee_ta/AuthVars/defaultvars/defaultvars.c

@@ -0,0 +1,94 @@
+/*  The copyright in this software is being made available under the BSD License,
+ *  included below. This software may be subject to other third party and
+ *  contributor rights, including patent rights, and no such rights are granted
+ *  under this license.
+ *
+ *  Copyright (c) Microsoft Corporation
+ *
+ *  All rights reserved.
+ *
+ *  BSD License
+ *
+ *  Redistribution and use in source and binary forms, with or without modification,
+ *  are permitted provided that the following conditions are met:
+ *
+ *  Redistributions of source code must retain the above copyright notice, this list
+ *  of conditions and the following disclaimer.
+ *
+ *  Redistributions in binary form must reproduce the above copyright notice, this
+ *  list of conditions and the following disclaimer in the documentation and/or
+ *  other materials provided with the distribution.
+ *
+ *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ""AS IS""
+ *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ *  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ *  ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ *  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ *  ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ *  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+
+#include <defaultvars.h>
+
+TEE_Result
+SetDefaultVariable(
+    WCHAR *Name, UINT32 NameSize, BYTE *Bin, UINT32 BinSize,
+    GUID Guid, ATTRIBUTES Attributes
+)
+/*++
+
+    Routine Description:
+
+        Populates and uses a set variable paramteter structure for the
+        pre-compiled default variables. Called from the autogenerated
+        file defaultvars_encoding.c (see defaultvars.py).
+
+    Arguments:
+
+            Name - Null terminated WCHAR string with the variable name
+
+            NameSize - Length of the name
+
+            Bin - Pointer to the binary contents of the variable
+
+            BinSize - Size of the binary
+
+            Guid - Variable GUID
+
+            Attributes - Attributes to set the variable with
+
+    Returns:
+
+    TEE_Result
+
+--*/
+{
+    TEE_Result res;
+    UINT32 totalSize = sizeof(VARIABLE_SET_PARAM) + NameSize + BinSize;
+    PVARIABLE_SET_PARAM setParam = TEE_Malloc(totalSize, TEE_MALLOC_FILL_ZERO);
+
+    if(!setParam) {
+        return TEE_ERROR_OUT_OF_MEMORY;
+    }
+
+    setParam->Size = sizeof(VARIABLE_SET_PARAM);
+    setParam->NameSize = NameSize;
+    setParam->VendorGuid = Guid;
+    setParam->Attributes = Attributes;
+    setParam->DataSize = BinSize;
+    setParam->OffsetName = 0;
+    setParam->OffsetData = NameSize;
+
+    memcpy(&setParam->Payload[0], Name, NameSize);
+    memcpy(&setParam->Payload[NameSize], Bin, BinSize);
+
+    res = SetVariable(totalSize, setParam);
+
+    TEE_Free(setParam);
+
+    return res;
+}

TAs/optee_ta/AuthVars/defaultvars/defaultvars.h

@@ -0,0 +1,54 @@
+/*  The copyright in this software is being made available under the BSD License,
+ *  included below. This software may be subject to other third party and
+ *  contributor rights, including patent rights, and no such rights are granted
+ *  under this license.
+ *
+ *  Copyright (c) Microsoft Corporation
+ *
+ *  All rights reserved.
+ *
+ *  BSD License
+ *
+ *  Redistribution and use in source and binary forms, with or without modification,
+ *  are permitted provided that the following conditions are met:
+ *
+ *  Redistributions of source code must retain the above copyright notice, this list
+ *  of conditions and the following disclaimer.
+ *
+ *  Redistributions in binary form must reproduce the above copyright notice, this
+ *  list of conditions and the following disclaimer in the documentation and/or
+ *  other materials provided with the distribution.
+ *
+ *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ""AS IS""
+ *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ *  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ *  ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ *  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ *  ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ *  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#pragma once
+#include <tee_internal_api.h>
+#include <tee_internal_api_extensions.h>
+#include <utee_defines.h>
+#include <ntdefs.h>
+#include <uefidefs.h>
+#include <varops.h>
+
+/*
+ * Defined in an autogenerated file, see defaultvars.py.
+ */
+TEE_Result
+InitializeDefaultVariables(
+    VOID
+);
+
+TEE_Result
+SetDefaultVariable(
+    WCHAR *Name, UINT32 NameSize, BYTE *Bin, UINT32 BinSize,
+    GUID Guid, ATTRIBUTES Attributes
+);