Spec updates

specifications/secure-launch-specification.rst

@@ -7,7 +7,7 @@ Secure Launch Specification
 
 .. class:: center
 
-**Version:** 0.5.0
+**Version:** 0.6.0-draft
 
 .. class:: center
 
@@ -138,7 +138,7 @@ Sequence
         +---------------------------------->|              |             |
         |                                   |              |             |
         |                                   |              |             |
-        |                  Initalize Table                 |             |
+        |                  Initialize Table                |             |
         +------------------------------------------------->|             |
         |                                                  |             |
         |    Invoke       |                 |              |             |
@@ -173,7 +173,7 @@ Secure Launch Interfaces
 ========================
 
 There are two interfaces to be defined here, the DLE Handler Specifications and
-the SLRT Specification. 
+the SLRT Specification.
 
 DLE Handler Specification
 -------------------------
@@ -185,7 +185,7 @@ Platform Requirements
 
 | **1** - x86 Platforms
 | **1.1** - The DLE Handler **MAY** be invoked with the CPU in either 32bit
-|       protected mode or 64bit long mode 
+|       protected mode or 64bit long mode
 | **1.2** - The SLRT **SHALL** be passed to the DLE Handler in the EDI/RDI CPU
 |       register
 | **1.3** - All other registers besides EDI/RDI are not guarenteed
@@ -217,7 +217,7 @@ Platform Requirements
 | **1** - General Requirements
 | **1.1** - The SLRT **MUST** begin with the magic value `0x4452544d`.
 | **1.2** - A properly formatted SLRT **SHALL** consist of a table header,
-|	zero or more table entries, and an end entry.
+|       zero or more table entries, and an end entry.
 | **1.3** - The SLRT **SHOULD** be in contiguous physical memory.
 | **1.3.1** - A preallocated, fixed size table is **OPTIONAL** through the use
 |       of the `max_size` field.
@@ -333,16 +333,16 @@ The list of valid entry tags.
 .. code-block:: c
     :linenos: 1
 
-    #define SLR_ENTRY_INVALID	        0x0000
-    #define SLR_ENTRY_DL_INFO	        0x0001
-    #define SLR_ENTRY_LOG_INFO	        0x0002
-    #define SLR_ENTRY_DRTM_POLICY	0x0003
-    #define SLR_ENTRY_INTEL_INFO	0x0004
-    #define SLR_ENTRY_AMD_INFO	        0x0005
-    #define SLR_ENTRY_ARM_INFO	        0x0006
-    #define SLR_ENTRY_UEFI_INFO	        0x0007
-    #define SLR_ENTRY_UEFI_CONFIG	0x0008
-    #define SLR_ENTRY_END		0xffff
+    #define SLR_ENTRY_INVALID           0x0000
+    #define SLR_ENTRY_DL_INFO           0x0001
+    #define SLR_ENTRY_LOG_INFO          0x0002
+    #define SLR_ENTRY_DRTM_POLICY       0x0003
+    #define SLR_ENTRY_INTEL_INFO        0x0004
+    #define SLR_ENTRY_AMD_INFO          0x0005
+    #define SLR_ENTRY_ARM_INFO          0x0006
+    #define SLR_ENTRY_UEFI_INFO         0x0007
+    #define SLR_ENTRY_UEFI_CONFIG       0x0008
+    #define SLR_ENTRY_END               0xffff
 
 Dynamic Launch Configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -430,14 +430,14 @@ D-RTM Measurement Policy
 
 The measurement policy is for conveying to the SL Entry on what it should
 measure, where that entity is located, which PCR the measurement should be
-stored, and how the event should be identified in the TPM event log. 
+stored, and how the event should be identified in the TPM event log.
 
 .. warning::
    The SL Entry **SHALL** fail if it determines an invalid policy is present.
 
 :tag: SLR_ENTRY_ENTRY_POLICY
 :revision: A revision field to identify the version of policy being used.
-:nr_entries: The total number of policy entries available.
+:nr_entries: The total number of policy entries in the array.
 
 .. code-block:: c
     :linenos: 1
@@ -448,7 +448,7 @@ stored, and how the event should be identified in the TPM event log.
         u16 nr_entries;
         /* policy_entries[] */
     };
-  
+
 
 DRTM Policy Entry
 """""""""""""""""
@@ -478,6 +478,10 @@ environment, that attribute will be published as an entity type. A generic
         char evt_info[TPM_EVENT_INFO_LENGTH];
     };
 
+In the current version (one) of the specification, `TPM_EVENT_INFO_LENGTH` is
+defined as 32 bytes. All unused bytes **MUST** be set to `\0`, but the string
+**MAY** not be terminated with `\0` if it fills the whole `evt_info`.
+
 D-RTM Policy Entry Entity Types
 '''''''''''''''''''''''''''''''
 
@@ -486,15 +490,23 @@ The list of valid entity types for D-RTM Policy entries.
 .. code-block:: c
     :linenos: 1
 
-    #define SLR_ET_UNSPECIFIED  0x0000
-    #define SLR_ET_SLRT         0x0001
-    #define SLR_ET_BOOT_PARAMS  0x0002
-    #define SLR_ET_SETUP_DATA   0x0003
-    #define SLR_ET_CMDLINE      0x0004
-    #define SLR_ET_UEFI_MEMMAP  0x0005
-    #define SLR_ET_RAMDISK      0x0006
-    #define SLR_ET_TXT_OS2MLE   0x0010
-    #define SLR_ET_UNUSED       0xffff
+    #define SLR_ET_UNSPECIFIED        0x0000
+    #define SLR_ET_SLRT               0x0001
+    #define SLR_ET_LINUX_BOOT_PARAMS  0x0002
+    #define SLR_ET_LINUX_SETUP_DATA   0x0003
+    #define SLR_ET_CMDLINE            0x0004
+    #define SLR_ET_UEFI_MEMMAP        0x0005
+    #define SLR_ET_RAMDISK            0x0006
+    #define SLR_ET_MULTIBOOT2_INFO    0x0007
+    #define SLR_ET_MULTIBOOT2_MODULE  0x0008
+    #define SLR_ET_TXT_OS2MLE         0x0010
+    #define SLR_ET_UNUSED             0xffff
+
+`SLR_ET_UNUSED` can be used if an entry in the DRTM Policy is to be ignored.
+Note that **RECOMMENDED** solution is to just not include the entry in question,
+this entity type is left as a final resort if entry has to be removed after SLRT
+was created in memory and defragmenting it after removing an entry isn't
+feasible.
 
 D-RTM Policy Entry Flags
 ''''''''''''''''''''''''
@@ -504,8 +516,12 @@ The list of valid flags for D-RTM Policy entries.
 .. code-block:: c
     :linenos: 1
 
-    #define SLR_POLICY_FLAG_MEASURED	0x1
-    #define SLR_POLICY_IMPLICIT_SIZE	0x2
+    #define SLR_POLICY_FLAG_MEASURED    0x1
+    #define SLR_POLICY_IMPLICIT_SIZE    0x2
+
+Only some of the entry types can have `SLR_POLICY_IMPLICIT_SIZE` flag set. Such
+entries have their `size` specified as zero, and they **SHALL** be measured as
+described in Appendix A.
 
 Intel TXT Platforms
 ~~~~~~~~~~~~~~~~~~~
@@ -562,6 +578,9 @@ Saved MTRR State
         struct txt_mtrr_pair mtrr_pair[TXT_VARIABLE_MTRRS_LENGTH];
     };
 
+In the current version (one) of the specification, `TXT_VARIABLE_MTRRS_LENGTH`
+is defined as 32 entries. All fields in unused entries **MUST** be set to 0.
+
 AMD Secure Launch Platforms
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -633,7 +652,7 @@ measured.
         u16 nr_entries;
         /* slr_uefi_cfg_entries[] */
     };
-  
+
 UEFI Config Entry
 """"""""""""""""
 
@@ -658,6 +677,10 @@ be measured.
         char evt_info[TPM_EVENT_INFO_LENGTH];
     } __packed;
 
+In the current version (one) of the specification, `TPM_EVENT_INFO_LENGTH` is
+defined as 32 bytes. All unused bytes **MUST** be set to `\0`, but the string
+**MAY** not be terminated with `\0` if it fills the whole `evt_info`.
+
 Appendix A: Measuring the DRTM Policy
 =====================================
 
@@ -686,7 +709,7 @@ H(), the extend operation, is defined as:
 |        }
 
 Measuring the Policy
----------------------
+--------------------
 
 Measuring the policy is not as simple as hashing the block of memory containing
 the policy. This will not work as the policy may contain memory addresses that
@@ -713,6 +736,84 @@ Using this logic, the resulting operation to measure the policy would be as:
 The result, `M_policy`, will be a hash of the policy that can then be extended
 into one, or more if using as a cap value, PCR(s).
 
+Note that current SLRT specification version doesn't require measuring the
+policy, neither does it have appropriate policy entry type for that measurement.
+
+Measuring the SLRT
+------------------
+
+In revision one of the SLRT, the only table that needs to be measured is the
+vendor info table, i.e. one of `SLR_ENTRY_INTEL_INFO`, `SLR_ENTRY_AMD_INFO` or
+`SLR_ENTRY_ARM_INFO`. Everything else is meta-data, addresses and sizes. Note
+the size of what to measure is not set. The flag `SLR_POLICY_IMPLICIT_SIZE`
+leaves it to the measuring code to choose and use proper structure's size.
+The structure is measured as a whole, together with its header.
+
+Measuring the Linux setup_data
+------------------------------
+
+Single linked list of `struct setup_data` is a way to pass extensible boot
+parameters and other data from bootloader to Linux kernel.
+
+:next: Pointer to next `setup_data` structure, or NULL if this is the last one
+:type: Type of entry
+:len: Length of following data
+:data: Parameters passed from bootloader
+
+.. code-block:: c
+    :linenos: 1
+
+    struct setup_data {
+        u64 next;
+        u32 type;
+        u32 len;
+        u8  data[0];
+    };
+
+The above structure is limited by maximum size that can be specified, as well as
+by the fact that data must be immediately following the header. To handle these
+situations, a `setup_indirect` structure was added in later Linux boot protocol:
+
+:type: Type of entry, logically ORed with `SETUP_INDIRECT`
+:len: Length of data
+:addr: Pointer to data
+
+.. code-block:: c
+    :linenos: 1
+
+    struct setup_indirect {
+        u32 type;
+        u32 reserved;  /* Reserved, must be set to zero. */
+        u64 len;
+        u64 addr;
+    };
+
+If indirect entries are used, the `setup_indirect` is put as `setup_data->data`,
+and `setup_data->type` is set to `SETUP_INDIRECT`.
+
+Pointer to the first `setup_data` is saved in DRTM Policy Entry. As these
+structures consist of physical addresses and other metadata that may change
+between boots, only the actual data is measured. For direct entries this is
+`data`, and for indirect -- memory pointed by `addr`. All `setup_data`s are
+measured in order, each as a separate entry in the TPM event log.
+
+Measuring OS to MLE data
+------------------------
+
+Version 1 of the OS-MLE heap structure has no fields to measure. It just has
+addresses and sizes and a scratch buffer. As such, this entry is skipped as of
+now, but this may change in the future versions.
+
+Measuring Multiboot2 boot information
+-------------------------------------
+
+Multiboot2 information data structure contains set of Tag-Length-Value (TLV)
+entries, however, for the sake of measurement it can be treated as a consecutive
+range of memory. Only the total length of this structure is important, it can be
+read from first field of that structure, i.e. `u32 total_size`. This is how the
+kernel obtains the size, so measuring code should also use it, hence this entity
+has `SLR_POLICY_IMPLICIT_SIZE` flag set.
+
 Appendix B: Intel TXT OS2MLE
 ============================