SBAT.example.md

   1 SBAT: Current proposal
   2 ================
   3
   4 `.sbat` section
   5 -------------
   6
   7 the `.sbat` section has the following fields:
   8 | field | meaning |
   9 |---|---|
  10 | component_name | the name we're comparing
  11 | component_generation | the generation number for the comparison
  12 | vendor_name | human readable vendor name
  13 | vendor_package_name | human readable package name
  14 | vendor_version | human readable package version (maybe machine parseable too, not specified here)
  15 | vendor_url | url to look stuff up, contact, whatever.
  16
  17 `SBAT` EFI variable
  18 -----------------
  19 The SBAT EFI variable (`SBAT-605dab50-e046-4300-abb6-3dd810dd8b23`) is structured as a series ASCII CSV records:
  20
  21 ```
  22 sbat,1
  23 component_name,component_generation
  24 component_name,component_generation
  25 ```
  26
  27 with the first record being our structure version number expressed as: `{'s', 'b', 'a', 't', ',', '1', '\n'}`
  28
  29 Validation Rules
  30 -----------------
  31 - If an `SBAT` variable is set, binaries validated directly by shim (i.e. not with the API) get validated using SBAT
  32 - If a binary validated by the API *does* have a `.sbat` section, it also gets validating using SBAT
  33 - If a binary is enrolled in `db` by its hash rather than by certificate, the validation result is logged only, not enforced
  34 - When validating SBAT, any `component_name` that's in both `SBAT` and `.sbat` gets compared
  35 - `component_generation` in `.sbat` must be >= `component_generation` of the identical `component_name` in `SBAT`
  36 - That version comparison includes the `"sbat"` entry
  37 - Component versions must be positive integers.
  38
  39 Example universe starting point
  40 -------------------------------
  41 For grub, a build from a fresh checkout of upstream might have the following in
  42 `.sbat`:
  43 ```
  44 sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
  45 grub,1,Free Software Foundation,grub,2.04,https://www.gnu.org/software/grub/
  46 ```
  47
  48 A Fedora build believed to have exactly the same set of vulnerabilities plus
  49 one that was never upstream might have:
  50 ```
  51 sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
  52 grub,1,Free Software Foundation,grub,2.04,https://www.gnu.org/software/grub/
  53 grub.fedora,1,The Fedora Project,grub2,2.04-31.fc33,https://src.fedoraproject.org/rpms/grub2
  54 ```
  55
  56 Likewise, Red Hat has various builds for RHEL 7 and RHEL 8, all of which have
  57 something akin to the following in `.sbat`:
  58 ```
  59 sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
  60 grub,1,Free Software Foundation,grub,2.02,https://www.gnu.org/software/grub/
  61 grub.fedora,1,Red Hat Enterprise Linux,grub2,2.02-0.34.fc24,mail:secalert@redhat.com
  62 grub.rhel,1,Red Hat Enterprise Linux,grub2,2.02-0.34.el7_2,mail:secalert@redhat.com
  63 ```
  64
  65 The Debian package believed to have the same set of vulnerabilities as upstream
  66 might have:
  67 ```
  68 sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
  69 grub,1,Free Software Foundation,grub,2.04,https://www.gnu.org/software/grub/
  70 grub.debian,1,Debian,grub2,2.04-12,https://packages.debian.org/source/sid/grub2
  71 ```
  72
  73 Another party known for less than high quality software who carry a bunch of
  74 out of tree grub patches on top of a very old grub version from before any of
  75 the upstream vulns were committed to the tree.  They haven't ever had the
  76 upstream vulns, and in fact have never shipped any vulnerabilities.  Their grub
  77 `.sbat` might have the following (which we'd be very suspect of signing, but
  78 hey, suppose it turns out to be correct):
  79 ```
  80 sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
  81 grub.acme,1,Acme Corporation,grub,1.96-8191,https://acme.arpa/packages/grub
  82 ```
  83
  84 At the same time, we're all shipping the same `shim-16` codebase, and in our
  85 `shim` builds, we all have the following in `.sbat`:
  86 ```
  87 sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
  88 ```
  89
  90 The `SBAT` data we've all agreed on and the UEFI CA has distributed is:
  91 ```
  92 sbat,1
  93 shim,1
  94 grub,1
  95 grub.fedora,1
  96 ```
  97
  98 Which is literally the byte array:
  99 ```
 100 {
 101   's', 'b', 'a', 't', ',', '1', '\n',
 102   's', 'h', 'i', 'm', ',', '1', '\n',
 103   'g', 'r', 'u', 'b', ',', '1', '\n',
 104   'g', 'r', 'u', 'b', '.', 'f', 'e', 'd', 'o', 'r', 'a', ',', '1', '\n',
 105 }
 106 ```
 107
 108 Along comes bug 0
 109 -----------------
 110 Let's say we find a bug in Fedora that's serious, but it's only in Fedora's
 111 patches, because we're the dumb ones.  Fedora issues a new shim build with the
 112 following `.sbat` info:
 113 ```
 114 sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
 115 grub,1,Free Software Foundation,grub,2.04,https://www.gnu.org/software/grub/
 116 grub.fedora,2,The Fedora Project,grub2,2.04-32.fc33,https://src.fedoraproject.org/rpms/grub2
 117 ```
 118
 119 For some (clearly insane) reason, 9 RHEL builds are also produced with the same
 120 fixes and the same data in `.sbat` that Fedora has.  The RHEL 7.2 update (just
 121 one example, same one as the RHEL example above) has the following in its
 122 `.sbat` data:
 123 ```
 124 sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
 125 grub,1,Free Software Foundation,grub,2.02,https://www.gnu.org/software/grub/
 126 grub.fedora,2,Red Hat Enterprise Linux,grub2,2.02-0.34.fc24,mail:secalert@redhat.com
 127 grub.rhel,2,Red Hat Enterprise Linux,grub2,2.02-0.34.el7_2.1,mail:secalert@redhat.com
 128 ```
 129
 130 The UEFI CA issues a new `SBAT` update which looks like:
 131 ```
 132 sbat,1
 133 shim,1
 134 grub,1
 135 grub.fedora,2
 136 ```
 137
 138 Along comes bug 1
 139 -----------------
 140 Another kind security researcher shows up with a serious bug, and this one was
 141 in upstream grub-0.94 and every version after that, and is shipped by all
 142 vendors.
 143
 144 At this point, each vendor updates their grub builds, and updates the
 145 `component_generation` in `.sbat` to `2`.  The upstream build now looks like:
 146 ```
 147 sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
 148 grub,2,Free Software Foundation,grub,2.05,https://www.gnu.org/software/grub/
 149 ```
 150
 151 But Fedora's now looks like:
 152 ```
 153 sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
 154 grub,2,Free Software Foundation,grub,2.04,https://www.gnu.org/software/grub/
 155 grub.fedora,2,The Fedora Project,grub2,2.04-33.fc33,https://src.fedoraproject.org/rpms/grub2
 156 ```
 157
 158 Other distros either rebase on 2.05 or theirs change similarly to Fedora's.  We now have two options for Acme Corp:
 159 - add a `grub.acme,1` entry to `SBAT`
 160 - have Acme Corp add `grub,2,Free Software Foundation,grub,1.96,https://www.gnu.org/software/grub/` to their new build's `.sbat`
 161
 162 We talk to Acme and they agree to do the latter, thus saving flash real estate
 163 to be developed on another day.  Their binary now looks like:
 164 ```
 165 sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
 166 grub,2,Free Software Foundation,grub,1.96,https://www.gnu.org/software/grub/
 167 grub.acme,2,Acme Corporation,grub,1.96-8192,https://acme.arpa/packages/grub
 168 ```
 169
 170 The UEFI CA issues an update which looks like:
 171 ```
 172 sbat,1
 173 shim,1
 174 grub,2
 175 grub.fedora,2
 176 ```
 177
 178 Acme Corp gets with the program
 179 -------------------------------
 180 Acme at this point discovers some features have been added to grub and they
 181 want them.  They ship a new grub build that's completely rebased on top of
 182 upstream and has no known vulnerabilities.  Its `.sbat` data looks like:
 183 ```
 184 sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
 185 grub,2,Free Software Foundation,grub,2.05,https://www.gnu.org/software/grub/
 186 grub.acme,2,Acme Corporation,grub,2.05-1,https://acme.arpa/packages/grub
 187 ```
 188
 189 Someone was wrong on the internet and bug 2
 190 -------------------------------------------
 191 Debian discovers that they actually shipped bug 0 as well (woops).  They
 192 produce a new build which fixes it and has the following in `.sbat`:
 193 ```
 194 sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
 195 grub,1,Free Software Foundation,grub,2.04,https://www.gnu.org/software/grub/
 196 grub.debian,2,Debian,grub2,2.04-13,https://packages.debian.org/source/sid/grub2
 197 ```
 198
 199 Before the UEFI CA has released an update, though, another upstream issue is
 200 found.  Everybody updates their builds as they did for bug 1.  Debian also
 201 updates theirs, as they would, and their new build has:
 202 ```
 203 sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
 204 grub,3,Free Software Foundation,grub,2.04,https://www.gnu.org/software/grub/
 205 grub.debian,2,Debian,grub2,2.04-13,https://packages.debian.org/source/sid/grub2
 206 ```
 207
 208 And the UEFI CA issues an update to SBAT which has:
 209 ```
 210 sbat,1
 211 shim,1
 212 grub,3
 213 grub.fedora,2
 214 ```
 215
 216 Two key things here:
 217 - `grub.debian` still got updated to `2` in their `.sbat` data, because a vulnerability was fixed that is only covered by that updated number.
 218 - There is still no `SBAT` update for `grub.debian`, because there's no binary that needs it which is not covered by updating `grub` to `3`.