Faq refresh #67
Faq refresh #67
Conversation
- expand sections of contributing to heads wiki - add gitignore for jekyll files
|
Ok, this becomes practical and I like it. I explain in code, linking to where things are happening from latest commit, in blame mode, so that people see where the code entry happens in links? Should we go with screenshots of gui-init, showing HOTP/TOTP codes, and point to where the calculations are made, where the TOTP/HOTP measurements are used in seal unseal operations? My biggest challenge, personally, is to switch from the code and documentation perspective. I need some guidance on creating documentation. This is really, really not my realm. |
This is something I think will break down over time. Bug fixes, code clean up, additional features added to the same part of code, the linked PR would not resemble what is currently in the master branch, linking multiple commits would be messy and confusing. Keep in mind who these "curious" are. Anyone who is legitimately going to review it would be other developers or those who technical enough to follow through fragments of code. Personally, the general wiki should focus on the end users, the developer section could benefit from linking directly to the code. Although, keeping all of that up to date would be challenging. The only thing that comes to mind is a javadoc equivalent for bash, something like shdoc. Where the annotations in the code can generate documentation. This is a much larger undertaking. |
|
I agree with Thrilleratplay that wiki docs are aimed at end users. Even devs have to start with a basic understanding. Reading Code is a slow way to understand how all of the various utilities SHOULD work together even if it details how they DO work together. If we link end user docs to source (maybe not PRs) it allows devs to more quickly dig into the components they are most interested in modifying. |
|
Shall I convert this to draft PR and we work through some questions in this thread or can we approve this PR and fill in the answers later? |
|
Draft. No need to push empty questions/answers. |
| How is the TPM used in heads? | ||
| ---- | ||
|
|
||
| Stores secret something? Could also have a disk unlock key. |
There was a problem hiding this comment.
Originally, Heads base was coreboot 4.8.1 with a measured boot patch applied on top of it.
In newer versions, coreboot integrated measured boot, and that patch was modified to respect the same measuring scheme then coreboot. The PCRs used in Heads extends the ones of coreboot by also measuring the state of the Recovery shell (if going into recovery shell, the measurements are extended and invalidated). The user related files are also measured (GPG public key, config.user overlay). You should refer here to produce this doc and extend the one there or refer to the one there and extend there. Duplicating doc duplicates maintenance of such doc. (kernel modules, config.user, public key, going into recovery to invalidate secret, since going into recovery wipes the precalculated secret in memory, LUKS header)
Heads takes those measurements to calculate a secret, which upon sealing (TOTP/HOTP) is "challenged" against an external device.
In the case of TOTP, this output takes the form of a Qr code, to be scanned on a smartphone to remote attest the firmware state at each boot on that smartphone. This requires the user to verify manually on his phone.
In the case of HOTP against Heads' supported USB Security dongles (Nitrokey Pro, Nitrokey Storage, Librem Key), in presence of a TPM, those measurements are used to challenge the USB Security dongle with that value.
In the case of the user having setuped a Disk Unlock Key (a secondary LUKS header slot) through setting a default boot option, the a TPM defined NV memory region can release a randomized Disk Unlock Key if: the TPM measurements are valid and the passphrase to unlock the TPM NV space is valid. In that case, the TPM will release the Disk Unlock Key, embedded into a initrd additional file which is passed to the OS. The Disk Unlock Key passphrase can be changed by setting a new boot default, and requires the user to type his Disk Recovery Key passphrase and then renew/change his Disk Unlock Key passphrase. This changes /boot content, and will also ask for the GPG User PIN to sign the changes.
| This thread (https://github.com/osresearch/heads/issues/639#issuecomment-570014587) says that the secrets from nvram are wiped before the recovery shell is launched. Does this limit what the recovery shell can do? Can the secrets be recovered using my other security infrastructure for validating that each step of the configuration and boot is working? | ||
|
|
||
|
|
||
| When do I need to reflash the BIOS? TBD |
There was a problem hiding this comment.
Reflashing the bios is kinda the only way to make completey sure of its state. See linuxboot/heads#836
A TPM is not a silver bullet. As stated there, a motivated attacker having access to the TPM chip could implant TPM genie. An attacker having access to the recovery shell could take a backup of your current ROM if linuxboot/heads#361 is not in (it is not. But putting that in as consequences for current codebase. If user looses his USB Security dongle used to authenticate himself, he is just totally locked out? This is why linuxboot/heads#771 is needed... So the user can at least buy another USB Security dongle and reprovision it. Doing it under Heads could be possible, considering that HOTP and TOTP would be invalidated.
See how it gets complicated?
TL;DR: you flash if there is a new official version you want to benefit from the new features.
New GPG. New cryptsetup. Want to install QubesOS 4.1. Want to install other OSes that were not supported prior of a specific commit.
You reflash if in doubt you have been hacked. I personally reflash the same ROM here and there. Reflashing the same rom means having the same coreboot stages measured. If your config/user and public key are the same: the measurements will be the same. Reflashing the same version in terms of flashrom function means you are actually taking a backup out, and reflashing only what changed. No change, no change. And then on reboot, HOTP/TOTP should be the same.
| When do I need to reflash the BIOS? TBD | ||
| ---- | ||
|
|
||
| To change the default boot |
There was a problem hiding this comment.
the heads menu that hosts the default boot option states that any changes are temporary and the BIOS has to be reflashed to save the setting. The default boot is the only meaningful change in that scope.
There was a problem hiding this comment.
No. The default boot option doesn't reflash the BIOS whatsoever.
Changing the boot options prompts the user to save the changes ON DISK. those changes means that defaut boot options changes.
Here is my /boot kexec files:
[user@dom0 ~]$ ls /boot/kexec*
/boot/kexec_default.1.txt /boot/kexec_hotp_counter
/boot/kexec_default.3.txt /boot/kexec_key_devices.txt
/boot/kexec_default_hashes.txt /boot/kexec_rollback.txt
/boot/kexec_hashes.txt /boot/kexec.sig
There, you see interesting files that are covered in specific section already. Please do not mix things up, and simply refer to other documentation sections, non duplicating them. In recap, kexec_hashes.txt contains the current /boot hashes. kexec_default_.#.txt contains the hashes corresponding with the current boot default hashes:
[user@dom0 ~]$ cat /boot/kexec_default.1.txt
Qubes, with Xen hypervisor|xen|kernel /xen-4.8.5-29.fc25.gz placeholder console=none dom0_mem=min:1024M dom0_mem=max:4096M iommu=no-igfx ucode=scan smt=off |module /vmlinuz-5.10.8-1.qubes.x86_64 placeholder root=/dev/mapper/qubes_dom0-root ro rd.luks.uuid=luks-a35bb850-778b-46d7-9814-7a105669960e rd.luks.options=discard rd.lvm.lv=qubes_dom0/root rd.lvm.lv=qubes_dom0/swap i915.alpha_support=1 plymouth.ignore-serial-consoles intel_iommu=igfx_off fromiso=/dev/disk/by-uuid/2f00bca5-dd3c-4a39-98f2-4e0ffeeae9f8/Qubes-R4.0.3-x86_64.iso iso-scan/filename=/Qubes-R4.0.3-x86_64.iso rhgb quiet rd.qubes.hide_all_usb|module /initramfs-5.10.8-1.qubes.x86_64.img
Detach sign routine
Verification routine
The ROM is only modified when flashing, merging user configs so they become persisten, or when adding user public key.
You can look for flash, and underlying flashrom calls into source code.
There was a problem hiding this comment.
https://github.com/osresearch/heads/blob/master/initrd/bin/config-gui.sh Line 18.
--menu "This menu lets you change settings for the current BIOS session.\n\nAll changes will revert after a reboot,\n\nunless you also save them to the running BIOS." 20 90 10 \
Normally, to save things to BIOS requires write access to NVRAM. How about:
--menu "These menu entries changes settings for the current session.\n\nUnless saved, all changes will revert after a reboot." 20 90 10 \
There was a problem hiding this comment.
@jtmoree-github-com This is getting more and more complicated for me to understand. A FAQ means Frequently Asked Questions. Those questions were never asked to me and are linked to implementation details and confusions I don't quite understand the origin.
config-gui.sh:
https://github.com/osresearch/heads/blob/master/initrd/bin/config-gui.sh#L19-L21
'b' ' Change the /boot device' \
's' ' Save the current configuration to the running BIOS' \
'r' ' Clear GPG key(s) and reset all user settings' \
As stated before elsewhere, and this gets really confusing to me, config-gui.sh is proposing to the user the above options.
Basically, creating an overlay (/etc/config.user, so that BOOT_DEV defined in board config (/etc/config) can be modified, as all other board config definitions there and saved back into the ROM. Otherwise THOSE changes are not persistent.
This has nothing to do with saving a new boot default, which is what I explained before.
This happens here and clearly specified to the user: Saving a default will modify the disk. Proceed? (Y/n): , not the ROM, when the user selects a new boot option in the boot menu.
So once again: The ROM gets modified when
- The user upgrades ROM (changes measurments, TOTP/HOTP secret, requires resealing, and setting a Disk Unlock Key from boot options so that TPM NV space releases the secret depending on new firmware measurements + NV passphrase
- When the user modifies /etc/config and wants it to be saved in ROM (new boot device, new ADD or REMOVE kernel arguments to be passed to OS kernel on OS boot)
- When the user generates a new GPG keypair on USB Security dongle, which will prompt to inject the new public key in ROM and will modify the measurements.
Can we check where what things should be understood prior of being documented maybe?
Not sure how to properly handle this while not taking all my time to review all that was already asked and replied in issues everywhere, already, before, but spot on questions that still need explanations. That is why everything is attempted to be answered on github. Let me know how you see this.
There was a problem hiding this comment.
https://github.com/osresearch/heads/blob/master/initrd/bin/config-gui.sh Line 18.
--menu "This menu lets you change settings for the current BIOS session.\n\nAll changes will revert after a reboot,\n\nunless you also save them to the running BIOS." 20 90 10 \Normally, to save things to BIOS requires write access to NVRAM. How about:
--menu "These menu entries changes settings for the current session.\n\nUnless saved, all changes will revert after a reboot." 20 90 10 \
This is 4.2 here #25 (comment)
| To change the default boot | ||
| Anything else? | ||
|
|
||
| What secrets are stored in BIOS? TBD |
There was a problem hiding this comment.
None.
TPM: PCRs are not secrets, but a result of calculations on coreboot stages + some added measurements (kernel modules, config.user, public key, going into recovery to invalidate secret, since going into recovery wipes the precalculated secret in memory, LUKS header).
Bios!=TPM.
Then TPM NV space contains a secret. But as stated before, that secret is released only if measurements are the same + Disk Unlock Key passphrase
|
My main question would be : Are those really Frequently asked questions? |
|
Here is a starter for past QA that should be turned into FAQ and point even to issues instead of redoing everything. We also try to move users into using gui-init instead of generic-init which was a PoC, prior of having USB dependencies (HOTP) and mounting external devices (which requires also loading kernel modules which modified PCR5). So if the user wants to have a working system, gui-init should be better understood, and the user has to understand that going into recovery invalidates measurements and secret. That was documented linuxboot/heads#639 and partly at some other place. If this is still unclear, let me know and I will find other discussions that happened on those subjects. I think the first step of everything is to detail more #25 (comment) if not precise enough. Editing OP. |
|
Really interesting post, on which we might come with smaller PRs with differences material. Measured boot != Secure boot != Verified boot |
This is a separate pull request because many of the QUESTIONS are unanswered. I hope we can answer the as part of the review of this change. At the very least we can add these questions to the FAQ without answers as some of the others on it also do not have answers yet.
tlaurion edit: Please review #25 (comment) and discuss there prior of making this PR go any further.