You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -47,138 +45,134 @@ The [Bootguard fuses](https://trmm.net/Bootguard) fuses provide protection
47
45
bootguard and only the Librem laptops ship with unfused keys.
48
46
49
47
An attacker who controls this key can flash new firmware via hardware means
50
-
(and possibly remotely via software, unless other steps are taken).
48
+
(and possibly remotely via software, unless other steps are taken).
51
49
52
-
TPM Owner password
53
-
---
50
+
## TPM Owner password
54
51
55
-
As part of setting up Heads the TPM is "owned" by the user and the owner
56
-
password is set. This clears all existing NVRAM and spaces (but does not reset
57
-
counters?).
52
+
As part of setting up Heads, the TPM is "owned" by the user and the owner
53
+
password is set. This clears all existing NVRAM and spaces.
58
54
59
-
Are there any consequences of an attacker controlling this key?
55
+
An attacker who controls this key can reseal TPMTOTP shared secret.
60
56
61
-
TPMTOTP shared secret
62
-
---
57
+
## TPMTOTP shared secret
63
58
64
59
65
60
66
61
Since humans have trouble doing RSA public key cryptography in their brains,
67
-
Heads uses [TPM TOTP](https://trmm.net/Tpmtotp) to let the system attest to the
68
-
user that the firmware is unmodified. During system setup a random 20-byte
69
-
value is generated and shared (via QR code) to the user's phone as well as
70
-
sealed with the correct TPM PCR values into the TPM NVRAM. On subsequent boots
71
-
the TPM will unseal the secret if and only if the PCRs match, and the computer
72
-
then generates a one-time password based on the current clock time, which the
73
-
user can compare to the value displayed on their phone. A new secret must be
74
-
generated each time the firmware is updated since this will change the PCRs.
62
+
Heads uses [TPM TOTP](https://trmm.net/Tpmtotp) to let the system attest to the
63
+
user that the firmware is unmodified. During setup, a random 20-byte value is
64
+
generated and shared (via QR code) to the user's phone and sealed with the
65
+
correct TPM PCR values into the TPM NVRAM. On subsequent boots, the TPM will
66
+
unseal the secret if the PCRs match, and the computer generates a one-time
67
+
password based on the current clock time, which the user can compare to the
68
+
value displayed on their phone. A new secret must be generated each time the
69
+
firmware is updated since this will change the PCRs.
75
70
76
71
If an attacker can control this shared secret (such as by directly sending PCR
77
-
values into the TPM) they can install malicious firmware in the SPI flash and
78
-
generate valid TOTP codes.
72
+
values into the TPM), they can install malicious firmware in the SPI flash and
73
+
generate valid TOTP codes.
79
74
80
-
TPM counter key
81
-
---
75
+
## TPM counter key
82
76
83
77
The TPM's increment-only counters can be used to prevent roll-back attacks on
84
-
the signed kernel and initramfs configurations. An attacker who controls this
85
-
key can increment the counter, causing a denial of service attack against the
86
-
system, but it does not provide any access to encrypted data nor any way to
87
-
roll back to an old version.
88
-
89
-
TPM disk encryption key
90
-
---
91
-
92
-
The TPM NVRAM also stores one of the disk encryption keys, which is encrypted
93
-
with the user's disk unlock password and sealed with the TPM PCR values for
94
-
the firmware and the LUKS headers on the disk. On every boot the user types in
95
-
their password and the TPM will unseal and decrypt the disk encryption key if
96
-
and only if the firmware is unmodified and the password matches. Since the
97
-
TPMTOTP one-time code matched, the user can have confidence that the firmware
98
-
is unmodified before they enter their password. If the system is booted in
99
-
recovery mode, the PCRs will not match and this key is not accessible to the
100
-
user.
78
+
the signed kernel and initramfs configurations. An attacker who controls this
79
+
key can increment the counter, causing a denial of service attack against the
80
+
system, but it does not provide access to encrypted data nor any way to roll
81
+
back to an old version.
82
+
83
+
## TPM Disk Unlock key
84
+
85
+
The TPM NVRAM stores one of the disk encryption keys, which is encrypted with
86
+
the user's Disk Unlock Key passphrase and sealed with the TPM PCR values for
87
+
the firmware and the LUKS headers of the disk. On every boot, the user types in
88
+
their TPM Disk Unlock Key passphrase and the TPM will unseal and decrypt the
89
+
disk encryption key if the firmware is unmodified and the passphrase matches.
90
+
Since the TPMTOTP one-time code matched, the user can have confidence that the
91
+
firmware is unmodified before they enter their TPM Disk Unlock Key passphrase.
92
+
If the system is booted in recovery mode, the PCRs will not match and this key
93
+
is not accessible to the user.
101
94
102
95
The Heads firmware inserts this key into the Qubes `initramfs.cpio` as
103
-
`/secret.key`, which is listed in the `/etc/crypttab` file as the decryption
104
-
key for the various partitions. The dracut/systemd startup scripts will read
105
-
the `/etc/crypttab` file and use it to decrypt the drives without further user
106
-
intervention.
96
+
`/secret.key`, which is listed in the `/etc/crypttab` file as the decryption
97
+
key for the various partitions. The dracut/systemd startup scripts will read
98
+
the `/etc/crypttab` file and use it to decrypt the drives without further user
99
+
intervention.
107
100
108
101
The sealed blob is not secret since it is both encrypted and sealed, but if an
109
-
attacker can extract this unsealed and decrypted key they can decrypt the data
110
-
on the disk. If they extract the TPM they can set the PCRs to the correct
111
-
values and attempt to brute force the unlock code, although the TPM should
112
-
provide some rate limiting. TODO: Can the TPM also flush the keys if too many
113
-
attempts are made?
102
+
attacker can extract this unsealed and decrypted key, they can decrypt the data
103
+
on the disk. If they extract the TPM, they can set the PCRs to the correct
104
+
values and attempt to brute force the unlock code, although the TPM should
105
+
provide some rate limiting. TODO: Can the TPM also flush the keys if too many
106
+
attempts are made?
114
107
115
-
Disk recovery key
116
-
---
108
+
## Disk Recovery Key
117
109
118
-
During initial system setup the disk is encrypted with a user chosen passphrase.
119
-
This key is only entered if the TPM PCRs have been changed, such as following a
120
-
firmware update, or if the disk has been moved to a new machine and the user
121
-
needs to back up the code. If the system is booted into recovery mode, the TPM
122
-
PCRs will not match the TPM sealed encryption key, so the user will need to
123
-
enter the recovery key to decrypt the drives.
110
+
During initial system setup, the disk is encrypted with a user-chosen
111
+
passphrase. When a TPM Disk Unlock Key is set up, this key is only entered if
112
+
the TPM PCRs have changed, such as following a firmware update, or if the disk
113
+
has been moved to a new machine and the user needs to back up the code. If the
114
+
system is booted into recovery mode, the TPM PCRs will not match the TPM sealed
115
+
Disk Unlock Key, so the user will need to enter the recovery key to decrypt the
116
+
drives.
124
117
125
-
If an attacker gains control of this recovery key they can decrypt the disk to
126
-
get access to the data, but not necessarily the system configuration if
127
-
dm-verity is configured. They can also add additional disk decryption keys,
128
-
although this will be detected by the TPM measurement of the LUKS headers.
118
+
If an attacker gains control of this recovery key, they can decrypt the disk to
119
+
access the data, but not necessarily the system configuration if dm-verity is
120
+
configured. They can also add additional disk decryption keys, although this
121
+
will be detected by the TPM measurement of the LUKS headers.
129
122
130
-
LUKS disk encryption key
131
-
---
123
+
## LUKS Keys and Passphrases
132
124
133
-
The TPM disk encryption and user's disk recovery keys are not the actual
134
-
encryption keys for the disk; they are passed through[PBKDF2](https://en.wikipedia.org/wiki/PBKDF2)
135
-
and the result is used to encrypt the actual disk encryption key, which is
136
-
stored in the LUKS header on the disk. Under normal circumstances this key is
137
-
not visible to the user and is only an implementation detail.
125
+
The TPM Disk Unlock and user's Disk Recovery passphrases are not the actual
126
+
encryption keys for the disk. These passphrases are processed through
127
+
[PBKDF2](https://en.wikipedia.org/wiki/PBKDF2) (LUKS1) or [Argon2]
128
+
(https://en.wikipedia.org/wiki/Argon2) (LUKS2) to derive a key. This derived
129
+
key then decrypts the actual disk encryption key stored in the LUKS header.
138
130
139
-
Access to this key has the same risks as the disk recovery key.
131
+
The disk encryption key itself remains hidden from users, serving only as an
132
+
implementation detail for the encryption process.
140
133
141
-
Owner's GPG key
142
-
---
134
+
## Owner's GPG key
143
135
144
136
145
137
146
-
The owner of the machine generates a GPG key pair as part of installing Heads.
147
-
Ideally the private key does not live on the machine, but instead is in a
148
-
Yubikey or other USB Security dongle.
138
+
The owner of the machine generates a GPG key pair as part of installing Heads.
139
+
Ideally, the private key does not live on the machine, but instead is in a
140
+
Yubikey or other USB Security dongle.
149
141
150
-
The security dongle may be used in the disk decryption process. Some of the [Linux distros](https://docs.puri.sm/Librem_Key/Getting_Started/User_Manual.html#decrypt-luks-encrypted-drives-with-librem-key) have incorporated this using /etc/crypttab with a keyscript option.
142
+
The security dongle may be used in the disk decryption process. Some of the
(16): Used for TPM futurecalc of LUKS header when setting up a TPM disk encryption key
194
-
195
-
Some history
196
-
---
197
-
Heads relied on coreboot patches until coreboot 4.8.1 for measured boot
198
-
implementation, since coreboot had none.
199
-
Heads measured boot scheme [changed](https://github.com/osresearch/heads/pull/793) to match coreboot 4.12's, which for the first time included seperated measured boot implementation from vboot implementation.
200
-
201
-
Since coreboot 4.12, Heads stopped patching coreboot to implement measured boot.
202
-
coreboot measured boot implementation is the one filling PCR2, above.
203
-
204
-
Heads since then solely extends PCRs of it's own (PCRs 4-5-6-7 above) which are used when
205
-
sealing/unsealing.
206
-
207
-
As you can see above, coreboot measures itself from bootblock then other boot phases up to its
208
-
payload in PCR2, in conformity of their [SRTM](https://doc.coreboot.org/security/vboot/measured_boot.html#srtm-mode) measured boot policy.
209
-
An example is given from [coreboot docs](https://doc.coreboot.org/security/vboot/measured_boot.html#platform-configuration-register).
210
-
211
-
TPM_Unseal errors
212
-
---
213
-
Consequently, if either coreboot phases, boot mode, kernel modules, LUKS headers
214
-
or CBFS files are different then when those measurements were used to seal secrets,
215
-
unseal operations will fail. HOTP/TOTP/TPM Disk Unlock Key passphrase should give errors
216
-
in case of tempering.
217
-
218
-
The TPM Disk Unlock Key passphrase would fail with a different error then:
219
-
`Error Authentication failed (Incorrect Password) from TPM_Unseal` when a user types
220
-
a [TPM Disk Unlock key passphrase](/Keys/#disk-unlock-key-passphrase-prompt-output).
221
-
222
-
Indeed, the PCRs measurements used to seal the Disk Unlock Key in TPM NV memory cannot unseal
223
-
that secret, even with a good TPM Disk Unlock Key passphrase, while HOTP/TOTP should not be able
224
-
to unseal either.
225
-
226
-
227
-
TCPA Event log
228
-
---
229
-
From the [Recovery Shell](/Recovery), it is possible to review PCR2 [TCPA event log](https://doc.coreboot.org/security/vboot/measured_boot.html#tcpa-eventlog) by typing:
230
-
`cbmem -L`
231
-
232
-
233
-
Disk Unlock Key passphrase prompt output
234
-
====
235
-
236
-
237
-
Here you can see that "Boot block, ROM stage, RAM stage, Heads payload", "Drive LUKS headers" and "Heads user-specific config files" have filled the registers PCR-02, PCR-06 and PCR-07 respectively. You can also see the TPM returning the error "Error Authentication failed (Incorrect Password)" which is an invitation to try again, this time typing more slowly. Measurements are consistent to what was sealed, but the passphrase is bad. This is good news.
238
-
239
-
After 3 unsuccessful attempts releasing TPM Disk Unlock Key, Heads will propose you to decrypt with your Disk Recovery Key passphrase, directly from the OS, bypassing Heads protection. Still good news.
240
-
241
-
If Disk Unlock Key passphrase throws a different error, it would be a good idea to meditate on your threat model and what happened to your computer since your last normal default boot.
242
-
243
-
The Disk Unlock Key is sealed in TPM NV memory with PCRs-2-4-5-6-7, which includes external content from the firmware, like your LUKS header measurements.
244
-
187
+
(16): Used for TPM futurecalc of LUKS header when setting up a TPM disk
188
+
encryption key
189
+
190
+
### Some history
191
+
Heads relied on coreboot patches until coreboot 4.8.1 for measured boot
192
+
implementation, since coreboot had none. Heads measured boot scheme
193
+
[changed](https://github.com/osresearch/heads/pull/793) to match coreboot
194
+
4.12's, which for the first time included separated measured boot
195
+
implementation from vboot implementation.
196
+
197
+
Since coreboot 4.12, Heads stopped patching coreboot to implement measured
198
+
boot. coreboot measured boot implementation is the one filling PCR2, above.
199
+
200
+
Heads since then solely extends PCRs of its own (PCRs 4-5-6-7 above) which are
201
+
used when sealing/unsealing.
202
+
203
+
As you can see above, coreboot measures itself from bootblock then other boot
204
+
phases up to its payload in PCR2, in conformity of their
0 commit comments