libreboot / lbwww (public) (License: Unspecified) (since 2023-04-11) (hash sha1)
libreboot website (markdown files). https://libreboot.org/
Clone URLs: https://rocketgit.com/user/libreboot/lbwww ssh://rocketgit@ssh.rocketgit.com/user/libreboot/lbwww git://git.rocketgit.com/user/libreboot/lbwww
25.04 25.06 master
List of commits:
Subject Hash Author Date (UTC)
complete cleanup of grub.cfg docs c50c0e16768ac5e62a3a4cb8d0f6455bf280afdd Leah Rowe 2024-08-27 00:38:53
make grub_cbfs.md a bit clearer 30cae6536afde27d05c2e5c8c44a51ae2b89590c Leah Rowe 2024-08-26 21:36:21
grub_hardening: document addition security/safety c6fde88de753766836a7ab5d579671b9853e4a7d Leah Rowe 2024-08-26 20:55:49
clarifification about flash descriptor override a54283de34b7a676ca92c18dbe25b81f81467399 Leah Rowe 2024-08-26 20:24:32
clarify ifdtool location for grub hardening 972de7d8405dace7601046e76a1057369b4a0b84 Leah Rowe 2024-08-26 17:53:47
improved grub hardening guide 2e6ed95570fd8997179085a7619148e25df11093 Leah Rowe 2024-08-26 17:51:02
remove redundant i945 thinkpad unbrick info 9bc8fb3eba363f5d68086d55fb6ad8222c4de687 Leah Rowe 2024-08-26 02:47:30
move devmem.md to correct location 41861ae96f70d243634198c19c4353ed1d529bc1 Leah Rowe 2024-08-26 02:14:08
unified iomem=relaxed instructions 1a330900d4b5934e043047d1c6dc7ea4b7702189 Leah Rowe 2024-08-26 02:12:42
unified internal dell latitude flashing guide d2e8cda2d111f9316c6d24086cdc079af179fba6 Leah Rowe 2024-08-26 01:22:04
delete unused page 82120ac94e131f56d965bbacabf016f502e224e2 Leah Rowe 2024-08-25 13:08:18
update freedom-status f8f58a679e6e9ecdcf67cbc2fbdb2c74bda3cb65 Leah Rowe 2024-08-25 11:05:23
rounded borders on images 111405dfe70c79b9da02dddc5ff8e801e9d0979c Leah Rowe 2024-08-24 13:46:29
make text a bit darker (#ccc, not #eee) 918b8a968a716a74eea575050df3010a35764a81 Leah Rowe 2024-08-23 14:30:41
switch libreboot.org back to purple bae3fad52cb2c9527024f7b0bd340e452b112057 Leah Rowe 2024-08-23 11:14:00
snip a2164297b94a5cc348a61af3e3ea3daa0329b23e Leah Rowe 2024-08-23 00:28:08
re-add news/10.md b5ca9e1686854c4c75fe90b0d18975319b726d9c Leah Rowe 2024-08-22 23:38:56
w541: clarify notes about chip select b7c7fd53e48b2300048b298191ce41cb49a47718 Leah Rowe 2024-08-18 00:26:14
install/w541_external: new guide f1151c0f3e620907bebf708efe1251c1aba894f9 Leah Rowe 2024-08-18 00:20:56
ivy_has_common: add clarification 47c02c29b71c7a08c06344b310841e8b53255c32 Leah Rowe 2024-08-18 00:09:45
Commit c50c0e16768ac5e62a3a4cb8d0f6455bf280afdd - complete cleanup of grub.cfg docs
remove all the redundant information, and merge some of it
between the two articles (grub hardening and grub cbfs guides)

Signed-off-by: Leah Rowe <info@minifree.org>
Author: Leah Rowe
Author date (UTC): 2024-08-27 00:38
Committer name: Leah Rowe
Committer date (UTC): 2024-08-27 00:38
Parent(s): 30cae6536afde27d05c2e5c8c44a51ae2b89590c
Signer:
Signing key:
Signing status: N
Tree: 863fdd16ae2ba2bf279f8ce51e73490c2864569d
File Lines added Lines deleted
site/docs/linux/grub_cbfs.md 92 75
site/docs/linux/grub_hardening.md 153 259
File site/docs/linux/grub_cbfs.md changed (mode: 100644) (index 7de647a..9f2cc04)
... ... title: Modifying grub.cfg in CBFS
3 3 x-toc-enable: true x-toc-enable: true
4 4 ... ...
5 5
6 NOTE: Libreboot standardises on [flashprog](https://flashprog.org/wiki/Flashprog)
7 now, as of 27 January 2024, which is a fork of flashrom.
6 Read [Libreboot flashing guides](../install/) before continuing, and make sure
7 to back up the current flash contents before you consider following this guide.
8 8
9 9 Before you follow this guide, it is advisable that you have the ability to Before you follow this guide, it is advisable that you have the ability to
10 flash externally, just in case something goes wrong.
10 [flash externally](../install/spi.md), just in case something goes wrong.
11 11
12 12 Libreboot's own GRUB configuration automatically scans for one provided by Libreboot's own GRUB configuration automatically scans for one provided by
13 13 your distro, and this automation will usually work. Sometimes, you might wish your distro, and this automation will usually work. Sometimes, you might wish
 
... ... to override it with your own custom menuentry or additional logic in the GRUB
15 15 config. You can configure GRUB however you like, and this topic is vast so what config. You can configure GRUB however you like, and this topic is vast so what
16 16 to actually *put in the config* will not be covered here. to actually *put in the config* will not be covered here.
17 17
18 This guide will simply teach you how to modify the config, but not what to put.
18 This guide will simply teach you how to modify the config, but not what to put,
19 whereas the [GRUB hardening](../linux/grub_hardening.md) guide specifically
20 says what to modify; cross reference that page and this page.
19 21
20 Compile flashprog and cbfstool
21 =============================
22 **Disable security before continuing**
23 ================================
22 24
23 libreboot does not currently distribute utilities pre-compiled. It only
24 provides ROM images pre-compiled, where feasible. Therefore, you have to build
25 the utilities from source.
25 **Before internal flashing, you must first disable `/dev/mem` protections. Make
26 sure to re-enable them after you're finished.**
26 27
27 As for the ROM, there are mainly three methods for obtaining a libreboot ROM
28 image:
28 **See: [Disabling /dev/mem protection](../install/devmem.md)**
29 29
30 1. Dump the contents of the the main *boot flash* on your system, which already
31 has libreboot installed (with GRUB as the default payload). Extract the
32 GRUB configuration from *that* ROM image.
33 2. Extract it from a libreboot ROM image supplied by the libreboot project, on
34 the libreboot website or mirrors of the libreboot website.
35 3. Build the ROM yourself, using the libreboot build system. Instructions for
36 how to do this are covered in the following article:
37 [How to build libreboot from source](../build/)
30 This only applies if you're following these instructions via internal
31 flashing, from an existing installation. If you're externally flashing the
32 machine, you can ignore this advice.
38 33
39 In either case, you will use the `cbfstool` supplied in the libreboot build
40 system.
41 This can be found under `coreboot/*/util/cbfstool/` as source code,
42 where `*` can be any coreboot source code directory for a given mainboard.
43 The directory named `default` should suffice.
34 Build dependencies
35 ==================
44 36
45 Install the build dependencies. For Debian and similar, you can run
46 the following command in the libreboot build system, from the root directory
47 of the libreboot Git repository.
37 **Please first [install build dependencies](../build/).**
48 38
49 ./mk dependencies debian
39 Coreboot utilities
40 ------------------
50 41
51 Determine what coreboot tree you need for your board. For example, if building
52 for `x200_8mb`, check `config/coreboot/x200_8mb/target.cfg` and it might
53 say `tree="default"` - in this case, the coreboot tree is named `default`.
42 You need `cbfstool` from coreboot. For whatever board you have, check which
43 coreboot tree it uses in Libreboot's build system, lbmk. For example, let's
44 say your board is `x200_8mb`, you would do:
54 45
55 Then, download coreboot (we'll assume the `default` tree is correct):
46 grep tree= config/coreboot/x200_8mb/target.cfg
56 47
57 ./mk -f coreboot default
48 In this example, the output might be:
58 49
59 Finally, compile the `cbutils` payload (and you will then have the utils):
50 tree="default"
60 51
61 ./mk -b grub
52 This means you should compile `cbfstool` from the `default` coreboot tree,
53 like so:
62 54
63 GRUB is multi-tree, but for GRUB utilities that's fine because we don't patch
64 those in any tree; we only patch the GRUB kernel to add various drivers and
65 extra crypto such as argon2.
55 ./mk -d coreboot default
66 56
67 Among other things, this will produce a `cbfstool` executable under any of the
68 subdirectories in `src/coreboot/` under `util/cbfstool/cbfstool`.
57 This will result in the following binary: `elf/cbfstool/default/cbfstool`
69 58
70 For example: `src/coreboot/default/util/cbfstool/cbfstool`
59 We won't assume the path to cbfstool, in the remainder of this guide, so
60 adapt accordingly.
71 61
72 The `cbfstool` utility is what you shall use. It is used to manipulate CBFS
73 (coreboot file system) which is a file system contained within the coreboot
74 ROM image; as a *coreboot distribution*, libreboot inherits this technology.
62 GRUB utilities
63 --------------
75 64
76 You can compile cbfstool and ifdtool for the given coreboot tree, e.g.:
65 Again, let's assume the coreboot board is `x200_8mb`. Check the
66 file `config/coreboot/x200_8mb/target.cfg` for `grubtree` - if it's not set,
67 then the GRUB tree is `default`. We will assume `default`:
77 68
78 ./mk -d coreboot default
69 ./mk -b grub default
70
71 This will compile GRUB for the given tree. If you need to use any of the GRUB
72 utilities, this command will build them and in this example, they will be
73 available under `src/grub/default/`.
79 74
80 This will create `elf/cbfstool/default/cbfbstool`
81 and `elf/ifdtool/default/ifdtool`.
75 Flashprog
76 ---------
82 77
83 You will also want to build `flashprog` which libreboot recommends for reading
84 from and/or writing to the boot flash. In the libreboot build system, you can
85 build it by running this command:
78 Compile flashprog like so:
86 79
87 80 ./mk -b flashprog ./mk -b flashprog
88 81
89 An executable will be available at `elf/flashprog/flashprog` after you have done
90 this.
82 A binary will appear at `elf/flashprog/flashprog`.
91 83
92 Dump the boot flash
84 Default GRUB config
93 85 =================== ===================
94 86
87 The coreboot image has its own filesystem, CBFS, and within CBFS is the GRUB
88 binary, and within the GRUB binary is another filesystem called memdisk, where
89 the default GRUB configuration is located.
90
91 You can override it by inserting your own GRUB config within CBFS.
92
93 Acquiring a GRUB config
94 =======================
95
96 Dump the boot flash
97 -------------------
98
99 This is only useful if you already inserted a GRUB config in CBFS. Otherwise,
100 you can grab it from Libreboot's build system, lbmk.
101
95 102 [Learn how to externally reprogram these chips](../install/spi.md) and use [Learn how to externally reprogram these chips](../install/spi.md) and use
96 103 the `-r` option in flashprog; alternatively, for internal flash access, the `-r` option in flashprog; alternatively, for internal flash access,
97 104 look at the [main flashing guide](../install/). look at the [main flashing guide](../install/).
98 105
99 106 Those guides show how to dump the flash contents, which you are advised to do. Those guides show how to dump the flash contents, which you are advised to do.
100 107
108 Default GRUB config location
109 ----------------------------
110
111 We'll assume that your GRUB tree is `default`, so the
112 file `config/grub/default/config/payload` is your GRUB config; this will be the
113 same as what you have in memdisk. Make a copy of this file, for modification.
114
115 Modify *that* file, or the one you extracted if you already inserted a custom
116 one before, and you will re-insert it when you're done.
117
118 Insert grubtest.cfg
119 ===================
120
121 Before reading the next section, please note: if you only have the fallback
122 GRUB config in memdisk, and no configs in CBFS, you can test the modified
123 version by inserting it as `grubtest.cfg`, instead of `grub.cfg`:
124
125 cbfstool libreboot.rom add -f grubtest.cfg -n grubtest.cfg
126
127 Libreboot will not automatically load it, but it will be available from the
128 default GRUB menu. This can be useful for test purposes, hence the name.
129
101 130 Insert new grub.cfg Insert new grub.cfg
102 131 =================== ===================
103 132
 
... ... Now remove it:
110 139
111 140 cbfstool libreboot.rom remove -n grub.cfg cbfstool libreboot.rom remove -n grub.cfg
112 141
113 It's important that you re-add `grub.cfg` before flashing:
142 It's important that you re-add `grub.cfg` before flashing (or just add it, if
143 it was never there in the first place):
114 144
115 145 cbfstool libreboot.rom add -f grub.cfg -n grub.cfg cbfstool libreboot.rom add -f grub.cfg -n grub.cfg
116 146
117 Repeat this for `grubtest.cfg` if you wish.
147 **If you flash the Libreboot image without a `grub.cfg` in CBFS, it will
148 default back to the one in GRUB memdisk.
118 149
119 If you're using a default Libreboot image, there *is no `grub.cfg` in flash*.
120 This is because there is also a default one embedded inside the GRUB binary,
121 which is inside CBFS. So:
150 AGAIN:
122 151
123 The coreboot image has its own filesystem, CBFS, and within CBFS is the GRUB
124 binary, and within the GRUB binary is another filesystem called memdisk, where
125 the default GRUB configuration is located.
126
127 You can insert a `grub.cfg` into CBFS and it will override the one in memdisk.
128
129 Check your board, e.g. `x200_8mb`, look at the file: `config/coreboot/x200_8mb/target.cfg`
130 and check for `grubtree` - if it's not sot, then it's `default`, otherwise check
131 what it's set to.
132
133 We'll assume it's `default`, so the
134 file `config/grub/default/config/payload` is your GRUB config; this will be the
135 same as what yo uhave in memdisk.
136
137 Modify *that* file, or the one you extracted if you already inserted a custom
138 one before, and you will re-insert it when you're done.
152 If you only want to test your changes first, insert it first as `grubtest.cfg`
153 and ensure that no `grub.cfg` exists in flash. This will let you access the
154 test config from the default menu, before deciding whether to make it the
155 main config, as `grub.cfg`, overriding the one in GRUB memdisk.
139 156
140 157 Flash the modified ROM image Flash the modified ROM image
141 158 ============================ ============================
File site/docs/linux/grub_hardening.md changed (mode: 100644) (index 6469e98..efdf128)
... ... title: Hardening GRUB
3 3 x-toc-enable: true x-toc-enable: true
4 4 ... ...
5 5
6 **NOTE: [Encrypted /boot with LUKS2 on argon2 key derivation is now
7 possible](../../news/argon2.md). This is covered in
8 the [main Linux guide](./).**
6 GRUB supports various security mechanisms that are not enabled by default.
7 This page will tell you how to enable them, for the purpose of boot security,
8 both detecting and attempting to prevent certain types of attack.
9 9
10 GRUB can have password protection at boot, prevent unauthorised access to the
11 shell and to menuentries. You can also boot from fully encrypted distros, where
12 the `/boot` directory is already encrypted, containing your kernel. You can
13 additionally verify each file, including GRUB configuration files and Linux
14 kernels, using GPG; GRUB supports putting a GPG pubkey in CBFS, and using it
15 to verify all files that it accesses.
10 **Make sure you have an [external SPI programmer](../install/spi.md), for
11 recovery purposes, just in case you brick your machine. The modifications
12 documented here are highly invasive and it would be easy to make mistakes.**
16 13
17 Let's begin.
14 Full disk encryption
15 ====================
18 16
19 **Disable security before flashing**
20 ================================
17 [Encrypted /boot with LUKS2 on argon2 key derivation is now
18 possible](../../news/argon2.md).
21 19
22 **Before internal flashing, you must first disable `/dev/mem` protections. Make
23 sure to re-enable them after you're finished.**
20 This is covered in
21 the [main Linux guide](./#encrypted-boot-via-luks2-with-argon2), in the
22 section pertaining to LUKS2/argon2.
24 23
25 **See: [Disabling /dev/mem protection](../install/devmem.md)**
24 You are strongly advised to create an encrypted Linux installation, before
25 setting up GRUB as shown in the guide below. Adapt it for whichever distro
26 you're installing (documenting every distro on the Libreboot documentation
27 would be a futile exercise and will not be attempted).
26 28
27 This only applies if you're following these instructions via internal
28 flashing, from an existing installation.
29 You are advised to do this *first*, because steps below depend on certain
30 configuration changes to be made on your installed Linux distro.
29 31
30 Back up your flash first!
31 =========================
32
33 Make sure you also back up the current flash contents, before you proceed with
34 this guide. See: [Libreboot flashing guides](../install/) (it also says how
35 to read the flash, in addition to writing it)
32 **Dependencies (do this first)**
33 =============================
36 34
37 Build dependencies
38 ==================
35 **Please read this: [Modifying GRUB in CBFS](grub_cbfs.md)**
39 36
40 You need `cbfstool` from coreboot. For whatever board you have, check which
41 coreboot tree it uses in Libreboot's build system, lbmk. For example, let's
42 say your board is `x200_8mb`, you would do:
37 **Assimilate that knowledge before continuing with the instructions below,
38 which tells you what modifications to actually perform, whereas the guide
39 linked above tells you how to apply your modifications for flashing.**
43 40
44 grep tree= config/coreboot/x200_8mb/target.cfg
41 Flash write protection
42 ======================
45 43
46 In this example, the output might be:
44 Although not strictly related to GNU GRUB, flash protection will prevent anyone
45 except you from overwriting the flash without permission. This is important,
46 because you don't want some malicious software running as root from overwriting
47 your flash, thus removing any of the above protections.
47 48
48 tree="default"
49 Build-time write protect
50 ---------------------------
49 51
50 This means you should compile `cbfstool` from the `default` coreboot tree,
51 like so:
52 Let's assume your board is `x200_8mb`, do:
52 53
53 ./mk -d coreboot default
54 ./mk -m coreboot x200_8mb
54 55
55 This will result in the following binary: `elf/cbfstool/default/cbfstool`
56 Find this section: Security -> Boot media protection mechanism
56 57
57 We won't assume the path to cbfstool, in the remainder of this guide, so
58 adapt accordingly.
58 In the above example, I found:
59 59
60 Background information
61 =========================
60 * Lock boot media using the controller
61 * Lock boot media using the chip
62 62
63 By default, the `grub.cfg` file and `grubtest.cfg` file are not present in
64 CBFS, because the GRUB memdisk, contained within the GRUB binary itself, within
65 CBFS, contains a GRUB configuration file.
63 Which one to pick depends on your board. Let's pick "controller".
66 64
67 Libreboot will switch to `grub.cfg` from flash instead, if it exists,
68 skipping the one in memdisk.
65 Now we can see: Security -> Boot media protected regions
69 66
70 Because we need to put a signature next to each file, that would mean
71 re-building GRUB if you wanted to use the one in memdisk. Therefore, we can
72 insert a custom one in CBFS, to mitigate that fact.
67 In there, there is the option to ban writes, or to ban both reads and writes.
68 Banning reads may be desirable, for example if you have a salt hashed password
69 stored in `grub.cfg`! (as this guide told you to do)
73 70
74 By doing it this way, you can avoid re-building GRUB, or indeed anything inside
75 your current Libreboot images.
71 You'll have to play around with this yourself. These options are not enabled
72 by default, because Libreboot images are supposed to allow writes by default,
73 when booted. You have to enable such security yourself, because the design of
74 Libreboot is to be as easy to use as possible by defalut, which include updates,
75 thus implying read-write flash permissions.
76 76
77 References:
77 This example was for `x200_8mb`, but other boards may look different in config.
78 Anyway, when you're done, save the config and then build it from source in lbmk.
78 79
79 * [GRUB manual](https://www.gnu.org/software/grub/manual/html_node/Security.html#Security)
80 * [GRUB info pages](http://git.savannah.gnu.org/cgit/grub.git/tree/docs/grub.texi)
81 * [Coreboot GRUB security howto](https://www.coreboot.org/GRUB2#Security)
80 See: [build from source](../build/)
82 81
83 GRUB Password
84 =============
82 IFD-based flash protection
83 --------------------------
85 84
86 The security of this setup depends on a good GRUB password as GPG signature
87 checking can be disabled through the interactive console:
85 The simplest way is to just do this:
88 86
89 set check_signatures=no
87 ifdtool -x libreboot.rom -O libreboot.rom
90 88
91 Disabling signatures, using the above command, is useful when you're booting
92 regular media such as live distros via USB.
89 If you did the step before, to compile `cbfstool`, you can find ifdtool in
90 the `elf/` directory, e.g. `elf/ifdtool/default/ifdtool`. Use the ifdtool
91 version matching the coreboot tree for your mainboard.
93 92
94 You are strongly advised to use an *open diceware* passphrase (look that up).
95 Generate a strong passphrase of completely random words, at least 20 words in
96 total is ideal. Passphrases are better than pass*words* containing lots
97 of random letters and symbols, because pass*phrases* have higher entropy and
98 are therefore harder to crack.
93 Note that this only works for Intel-based systems that use an Intel Flash
94 Descriptor, which is actually most Intel systems that Libreboot supports.
99 95
100 The GRUB password can be stored in one of two ways:
96 Other facts
97 -----------
101 98
102 * plaintext
103 * protected with [PBKDF2](https://en.wikipedia.org/wiki/Pbkdf2)
99 Strapping `HDA_SDO` or `HDA_DOCK_EN` requires physical access, because you have
100 to short a pin on the HDA chip on the motherboard, or there will be a header
101 for this on the board (e.g. "service mode" jumper). If you strap those pins,
102 it disables descriptor-based flash protections.
104 103
105 We will *obviously* use the latter method. Generating the PBKDF2 derived key is
106 done using the `grub-mkpasswd-pbkdf2` utility. You can get it by
107 installing GRUB version 2. Generate a key by giving it a password:
104 On *Dell Latitude* laptops specifically, the EC can unlock flash by setting
105 the SDO/DOCK\_EN signal as described, and this is in fact what
106 the `dell-flash-unlock` utility does, so you can consider IFD locking there
107 to be basically useless.
108 108
109 NOTE: This utility is included under the `grub/` directory, when you build
110 GRUB using the libreboot build system. Run the following commands (assuming
111 you have the correct build dependencies installed) to build GRUB, from the
112 libreboot Git repository:
109 In addition to the above, you may also consider `/dev/mem` protection.
110 Enable `CONFIG_STRICT_DEVMEM` in your Linux kernel, or set `securelevel` above
111 zero on your BSD setup (but BSD cannot be booted with GRUB very easily so
112 it's a moot point).
113 113
114 ./mk -b grub default
114 FLILL
115 -----
115 116
116 The following executable will then be available under `src/grub/default/`:
117 On Intel Flash Descriptor, you can insert up to four (4) commands on a list
118 within, called *FLILL*; not yet documented, but any SPI command listed here
119 would no longer work during internal flash operations. For example, you could
120 use it to disable certain erase/write commands. You could also use it to
121 disable *reads*.
117 122
118 grub-mkpasswd-pbkdf2
123 PRx registers
124 -------------
119 125
120 Run that program. It will ask you to choose a new passphrase. Its output will
121 be a string of the following form:
126 Protected Range registers are available on Intel platforms, to disable flash
127 writes. This is not yet documented, and it varies per platform.
122 128
123 grub.pbkdf2.sha512.10000.HEXDIGITS.MOREHEXDIGITS
129 GRUB Password
130 =============
124 131
125 Make sure to copy this into the correct GRUB config. The correct GRUB config
126 can be determined as follows. Again, let's assume that you have `x200_8mb`:
132 The security of this setup depends on a good GRUB password as GPG signature
133 checking can be disabled through the GRUB console with this command:
127 134
128 grep grubtree= config/coreboot/x200_8mb/target.cfg
135 set check_signatures=no
129 136
130 It *may* or *may not* output anything. If it outputs *nothing*, then the
131 GRUB tree is `default`, otherwise it might output something like:
137 The above GRUB shell command is required when you want to live USB media,
138 or other Linux setups that don't yet have signatures on files e.g. linux.
132 139
133 grubtree="nvme"
140 We will assume that you're using the `default` GRUB tree; the GRUB CBFS guide
141 linked above tells you how to determine which GRUB tree to use.
134 142
135 Make *sure* to use the correct GRUB tree. We will assume `default`, so you
136 should adapt accordingly, when doing this yourself:
143 The following executable will then be available under `src/grub/default/`:
137 144
138 cp config/grub/default/config/payload grub.cfg
145 grub-mkpasswd-pbkdf2
139 146
140 Now, your `grub.cfg` file is correct for the board, and you can insert
141 the salted, hashed passphrase that you get from `grub-mkpasswd-pbkdf2` earlier.
147 Run that program. It will ask you to choose a new passphrase. Its output will
148 be a string of the following form:
142 149
143 Now open my.grubtest.cfg and put the following before the menu entries
144 (prefered above the functions and after other directives). Of course use
145 the pbdkf string that you had generated yourself:
150 grub.pbkdf2.sha512.10000.HEXDIGITS.MOREHEXDIGITS
146 151
147 152 Put this *before* the menuentries (just before) in `grub.cfg`, but note that Put this *before* the menuentries (just before) in `grub.cfg`, but note that
148 153 you should **not** literally use what is below; the hash below is not the one you should **not** literally use what is below; the hash below is not the one
 
... ... Example:
156 161 **Again**, replace it with the correct hash that you actually obtained for the **Again**, replace it with the correct hash that you actually obtained for the
157 162 password you entered. In other words, *do not use the hash that you see above!* password you entered. In other words, *do not use the hash that you see above!*
158 163
159 Once this configuration is inserted, you will need to enter a passphrase every
160 time you boot. GRUB will also ask for a username. In the above example, we
161 made a username `root`, but you can set it to what you want and
162 adapt accordingly.
164 GRUB will also ask for a username in addition to the password; the "root" user
165 is specified above, but you can cahnge it to whatever you want.
163 166
164 Another good thing to do, if we chose to load signed on-disk GRUB
165 configurations, is to remove (or comment out) `unset superusers`. Find any line
166 that says this, in your `grub.cfg` file:
167 Unset superusers
168 ================
169
170 Find this line in `grub.cfg`:
167 171
168 172 unset superusers unset superusers
169 173
 
... ... Change it to this:
171 175
172 176 # unset superusers # unset superusers
173 177
174 The `unset superusers` command disables password authentication, which will
175 allow the attacker to boot an arbitrary operating system, regardless of
176 signature checking. The default libreboot configuration is tweaked for *ease of
177 use* by end users, and it is *not* done with security in mind (though security
178 is preferred). Thus, libreboot is less restrictive by default. What you are
179 doing, per this article, is making your system *more secure* but at the expense
180 of user-friendliness.
181
182 That just about covers it, where password setup is concerned!
178 Commenting it, as shown above, ensures that password authentication works,
179 because `unset superusers` in fact disables passwordh authentication, so it's
180 very important that you comment out this line.
183 181
184 SeaBIOS first?
185 ==============
182 Disable the SeaBIOS menu
183 ====================
186 184
187 185 **Very important. Make sure you read this carefully.** **Very important. Make sure you read this carefully.**
188 186
189 187 In releases after Libreboot 20240504, SeaBIOS is the primary payload on In releases after Libreboot 20240504, SeaBIOS is the primary payload on
190 all images, but GRUB is available in the boot menu. Select a ROM image
191 with `grubfirst` at the end, and do this to the ROM image:
188 all images, but GRUB is available in the boot menu.
189
190 Do this:
192 191
193 192 cbfstool libreboot.rom add-int -i 0 -n etc/show-boot-menu cbfstool libreboot.rom add-int -i 0 -n etc/show-boot-menu
194 193
195 This disables the SeaBIOS menu, so that it only loads GRUB. The `grubfirst`
196 image had this done to it by lbmk (Libreboot build system) during build:
194 This disables the SeaBIOS menu, so that it only loads GRUB.
195
196 If your ROM image doesn't auto-start GRUB, you should also insert the
197 bootorder file:
197 198
198 199 cbfstool libreboot.rom add -f config/grub/bootorder -n bootorder -t raw cbfstool libreboot.rom add -f config/grub/bootorder -n bootorder -t raw
199 200
 
... ... This `bootorder` file has the following contents:
203 204 /rom@img/grub2 /rom@img/grub2
204 205 ``` ```
205 206
206 You can add it yourself if your image doesn't have it. With this, SeaBIOS
207 only loads GRUB first. You can still put a GRUB config in CBFS to override
208 the default one, as of Libreboot 20240612.
209
210 NOTE: Before disabling the boot menu, make sure GRUB works. Access it using
211 the `bootorder` file and/or press ESC in the SeaBIOS menu. Then disable the
212 SeaBIOS menu:
213
214 cbfstool libreboot.rom add-int -i 0 -n etc/show-boot-menu
215
216 Although the `bootorder` file only specifies *GRUB*, this just means that
217 SeaBIOS won't automatically try to boot anything else. The SeaBIOS menu is still
218 accessible, by pressing ESC when prompted; the above `add-int` command disables
219 that menu, so that *only* the GRUB payload will be executed.
207 Release images with `seagrub` in the name already have this bootorder file,
208 so you only need to disable the menu on these images. If you have the
209 image with `seabios` in the name (instead of `seagrub`), you must do both.
220 210
221 211 SeaBIOS option ROMs SeaBIOS option ROMs
222 ===================
212 -------------------
223 213
224 214 SeaBIOS will also still execute PCI option ROMs. Depending on your preference, SeaBIOS will also still execute PCI option ROMs. Depending on your preference,
225 215 you may wish to disable this, but please note that this will break certain you may wish to disable this, but please note that this will break certain
 
... ... things like graphics cards. More information is available here:
227 217
228 218 <https://www.seabios.org/Runtime_config> <https://www.seabios.org/Runtime_config>
229 219
230 On a laptop, you probably don't have to worry about option ROMs at all, but
231 desktops are much more easily upgradeable; though, in practise, anyone
232 inclined to insert a card with a malicious option ROM on it wouldn't do that
233 anyway, because if they have access to your hardware, they could just
234 externally re-flash the machine anyway, so I wouldn't worry, but it's up to you.
235
236 220 If you're using a graphics card, you *need* VGA option ROMs at least. If you're using a graphics card, you *need* VGA option ROMs at least.
237 221
238 222 GPG keys GPG keys
 
... ... First, generate a GPG keypair to use for signing. Option RSA (sign only)
242 226 is ok. is ok.
243 227
244 228 WARNING: GRUB does not read ASCII armored keys. When attempting to WARNING: GRUB does not read ASCII armored keys. When attempting to
245 trust ... a key filename it will print `error: bad signature` on the screen.
229 trust ASCII armor keys, it will print `error: bad signature` on the screen.
246 230
247 231 ``` ```
248 232 mkdir --mode 0700 keys mkdir --mode 0700 keys
 
... ... Now that we have a key, we can sign some files with it. We must sign:
256 240 - a kernel - a kernel
257 241 - (if we have one) an initramfs - (if we have one) an initramfs
258 242 - (if we wish to transfer control to it) an on-disk `grub.cfg` - (if we wish to transfer control to it) an on-disk `grub.cfg`
259 - `grubtest.cfg` (so that you can go back to `grubtest.cfg` after signature
260 checking is enforced. You can always get back to `grub.cfg` by pressing ESC,
261 but, afterwards, `grubtest.cfg` is not signed and it will not load. The
262 GRUB config we made earlier can be copied to `grubtest.cfg` and inserted,
263 but please only do this at the end of the guide when it tells you to insert
264 the GRUB config, because there are still osme things you need to do.
265
266 Suppose that we have a pair of `my.kernel` and `my.initramfs` and an
267 on-disk `libreboot_grub.cfg`. We will sign them by running the following
243 - `grubtest.cfg` in CBFS, if it exists
244 - `grub.cfg` in CBFS, if it exists
245
246 You must provide a *detached signature* alongside each file. For example, if
247 a file in a directory is named `foo`, and GRUB uses this file, an accompaning
248 file `foo.sig` must exist alongside it.
249
250 Suppose that we have a pair of `my.kernel`, `my.initramfs` and an
251 on-disk `grub.cfg`. We will sign them by running the following
268 252 commands: commands:
269 253
270 254 ``` ```
271 255 gpg --homedir keys --detach-sign my.initramfs gpg --homedir keys --detach-sign my.initramfs
272 256 gpg --homedir keys --detach-sign my.kernel gpg --homedir keys --detach-sign my.kernel
273 gpg --homedir keys --detach-sign libreboot_grub.cfg
274 gpg --homedir keys --detach-sign my.grubtest.cfg
257 gpg --homedir keys --detach-sign grub.cfg
275 258 ``` ```
276 259
277 Of course, some further modifications to grubtest.cfg will be required. We
278 need to *trust* the key and enable signature enforcement (put this before menu
279 entries):
260 You must also do the above on any file that goes in CBFS, and insert it
261 into CBFS, using instructions already provided on the GRUB CBFS guide linked
262 above, earlier on in this guide.
263
264 Enforce GPG check in GRUB
265 =========================
266
267 The following must be present in `grub.cfg`, but please note that the
268 background image used by GRUB is in the memdisk by default, not CBFS, so you
269 might want to put it *after* the command that enables a background:
280 270
281 271 ``` ```
282 272 trust (cbfsdisk)/boot.key trust (cbfsdisk)/boot.key
 
... ... set check_signatures=enforce
286 276 What remains now is to include the modifications into the libreboot image What remains now is to include the modifications into the libreboot image
287 277 (ROM): (ROM):
288 278
289 ```
290 cbfstool libreboot.rom add -n boot.key -f boot.key -t raw
291
292 # You might consider copying `grub.cfg` to `grubtest.cfg` and adding that.
293 # Otherwise, adding just `grub.cfg` is also fine.
294
295 cbfstool libreboot.rom add -n grub.cfg -f my.grub.cfg -t raw
296 cbfstool libreboot.rom add -n grub.cfg.sig -f my.grub.cfg.sig -t raw
297
298 cbfstool libreboot.rom add -n grubtest.cfg -f my.grubtest.cfg -t raw
299 cbfstool libreboot.rom add -n grubtest.cfg.sig -f my.grubtest.cfg.sig -t raw
300 ```
301
302 Congratulations!
303 ================
304
305 With any luck, this should work perfectly. Your system will no longer boot
306 anything unless it's signed by your key.
307
308 If your entire system is also encrypted, including `/boot`, then that protects
309 everything including the privkey much more robustly, and it further prevents
310 tampering with your kernel (where GPG only detects tampering, encryption can
311 prevent it).
312
313 Encryption, combined with a GRUB passphrase, combined with a GPG check, should
314 make you pretty damn secure at boot time. All that's left now is one final,
315 optional step:
316
317 Flash write protection
318 ======================
319
320 Although not strictly related to GNU GRUB, flash protection will prevent anyone
321 except you from overwriting the flash without permission. This is important,
322 because you don't want some malicious software running as root from overwriting
323 your flash, thus removing any of the above protections.
324
325 The simplest way is to just do this:
326
327 ifdtool -x libreboot.rom -O libreboot.rom
328
329 If you did the step before, to compile `cbfstool`, you can find ifdtool in
330 the `elf/` directory, e.g. `elf/ifdtool/default/ifdtool`. Make sure to use
331 the correct version, as per `tree=` (same as before when deciding to which
332 cbfstool version to use based on the coreboot tree used by your board).
333
334 Note that this only works for Intel-based systems that use an Intel Flash
335 Descriptor, which is actually most Intel systems that Libreboot supports.
336
337 You can still flash externally, or strap `HDA_SDO` (`HDA_DOCK_EN` on older
338 GM45 machines) accordingly. Note that the x4x/ich10-based machines don't have
339 flash descriptors, and neither do the i945 machines, but the GM45 and newer
340 Intel platforms do.
341
342 Other facts
343 -----------
344
345 Strapping `HDA_SDO` or `HDA_DOCK_EN` requires physical access, because you have
346 to short a pin on the HDA chip on the motherboard, or there will be a header
347 for this on the board (e.g. "service mode" jumper).
348
349 On *Dell Latitude* laptops specifically, the EC can unlock flash by setting
350 the SDO/DOCK\_EN signal as described, and this is in fact what
351 the `dell-flash-unlock` utility does, so you can consider IFD locking there
352 to be basically useless.
353
354 In addition to the above, you may also consider `/dev/mem` protection.
355 Enable `CONFIG_STRICT_DEVMEM` in your Linux kernel, or set `securelevel` above
356 zero on your BSD setup (but BSD cannot be booted with GRUB very easily so
357 it's a moot point).
358
359 Other write-protect methods
360 ---------------------------
361
362 The steps above do not require recompilation of the Libreboot images. However,
363 coreboot offers additional security at build time, which you can select if you
364 wish.
365
366 Let's assume your board is `x200_8mb`, do:
367
368 ./mk -m coreboot x200_8mb
369
370 Find this section: Security -> Boot media protection mechanism
371
372 In the above example, I found:
373
374 * Lock boot media using the controller
375 * Lock boot media using the chip
376
377 Which one to pick depends on your board. Let's pick "controller".
378
379 Now we can see: Security -> Boot media protected regions
380
381 In there, there is the option to ban writes, or to ban both reads and writes.
382 Banning reads may be desirable, for example if you have a salt hashed password
383 stored in `grub.cfg`! (as this guide told you to do)
384
385 You'll have to play around with this yourself. These options are not enabled
386 by default, because Libreboot images are supposed to allow writes by default,
387 when booted. You have to enable such security yourself, because the design of
388 Libreboot is to be as easy to use as possible by defalut, which include updates,
389 thus implying read-write flash permissions.
390
391 This example was for `x200_8mb`, but other boards may look different in config.
392 Anyway, when you're done, save the config and then build it from source in lbmk.
393
394 See: [build from source](../build/)
279 Please read and follow the [GRUB configuration guide](grub_cbfs.md); this is
280 the GRUB CBFS guide that was also linked above, earlier on in the article
281 you're currently reading.
395 282
396 283 Install the new image Install the new image
397 284 ===================== =====================
 
... ... up just fine. Shut it down and wait a few seconds. If you screwed it up
404 291 and the system is now unbootable, that's OK because you can use an and the system is now unbootable, that's OK because you can use an
405 292 external flasher; please external flasher; please
406 293 read [external flashing instructions](../install/spi.md) read [external flashing instructions](../install/spi.md)
294
295 References
296 ==========
297
298 * [GRUB manual](https://www.gnu.org/software/grub/manual/html_node/Security.html#Security)
299 * [GRUB info pages](http://git.savannah.gnu.org/cgit/grub.git/tree/docs/grub.texi)
300 * [Coreboot GRUB security howto](https://www.coreboot.org/GRUB2#Security)
Hints:
Before first commit, do not forget to setup your git environment:
git config --global user.name "your_name_here"
git config --global user.email "your@email_here"

Clone this repository using HTTP(S):
git clone https://rocketgit.com/user/libreboot/lbwww

Clone this repository using ssh (do not forget to upload a key first):
git clone ssh://rocketgit@ssh.rocketgit.com/user/libreboot/lbwww

Clone this repository using git:
git clone git://git.rocketgit.com/user/libreboot/lbwww

You are allowed to anonymously push to this repository.
This means that your pushed commits will automatically be transformed into a merge request:
... clone the repository ...
... make some changes and some commits ...
git push origin main