Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Faq refresh #67

Closed
wants to merge 3 commits into from
Closed

Faq refresh #67

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
82951e2
clarify wiki
jtmoree-github-com Jan 28, 2021
406e7b2
update FAQ with unanswered questions
jtmoree-github-com Jan 28, 2021
d87d5c3
replace 'wish i knew' with TBD
jtmoree-github-com Feb 1, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
.jekyll-cache
_site
132 changes: 131 additions & 1 deletion About/FAQ.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,12 @@ Should I validate the TPMTOTP on every boot

Probably. I want to make it also do it at S3. [See Heads issue #69](https://github.com/osresearch/heads/issues/69)

How is the TPM used in heads?
----

Stores secret something? Could also have a disk unlock key.
Copy link
Collaborator

@tlaurion tlaurion Feb 9, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.



suspend vs shutdown
----

Expand Down Expand Up @@ -182,6 +188,16 @@ throttling or limiting the number of failed attempted while TOTP is susceptible
to phishing attacks and requires a user to enter the code within a given time
period.

How is HOTP used in heads? TBD
----

? Wish I knew.
jtmoree-github-com marked this conversation as resolved.
Show resolved Hide resolved

How is TOTP used in heads? TBD
----

? Wish I knew.

coreboot vs Linuxboot
----

Expand All @@ -190,4 +206,118 @@ TO BE WRITTEN
What happens if I lose/break my security key
----

TO BE WRITTEN
This depends on whether or not you have backups for the key. If you have no backup you will have lost access to all data that was encrypted using this key. If you have backups you may create a new key from them. The counter on the key will be different but you can reset that in heads. Since you know that something changed you can ignore the tampering warning.

What is the recovery shell?
----

The recovery shell is a minimal unix shell running on top of the heads kernel. It can be used to investigate and configure the heads environment.

What are the limitations of the recovery shell? TBD
----

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?
jtmoree-github-com marked this conversation as resolved.
Show resolved Hide resolved


When do I need to reflash the BIOS? TBD
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

----

To change the default boot
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 \

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Anything else?

What secrets are stored in BIOS? TBD
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

----

LUKS passphrase for disk (optional)


If secrets are wiped out at a drop to the recovery shell, can I safely reflash from there? Do secrets get erased if flashing from the recovery shell?
----

TBD

Can the HOTP/TOTP functions work in the recovery shell if secrets are wiped?
jtmoree-github-com marked this conversation as resolved.
Show resolved Hide resolved
----

TBD

When flashing the BIOS I can choose to keep or erase settings? What settings? Can they be regenerated? Will I lose anything important? TBD
----

The erase choice will remove signatures and settings from boot. /boot/kexec*
? the sigs and hashes can be regenerated. Key is a string such as ‘Librem Key’. What about counter?


What is /tmp/kexec? TBD
----


Assuming heads is running on the system, what are the steps for configuring it using the recovery shell?
----

This likely needs to be a howto ARTICLE but each step is decribed here.

### Set default boot

Heads needs to know which partition to use for bootup. The setting is based on an environment variable which is set in /etc/config.user.

```echo “export CONFIG_BOOT_DEV=’/dev/sdX’” > /etc/config.user```

### Flash current settings into BIOS TBD

This is technical and risky. Perhaps a separate document is best?

### Set tpm owner password TBD

```tpm-reset```

### Sign files in boot

This command will use your security token to sign all files in /boot (except kexec*) and record the sigs in the file kexec_hashes.txt

```kexec-sign-config -p /boot/```

### set hotp/totp TBD

hotp, hotp_verification, hotp_initialize
, totp


What security related files are added to /boot on my system? And what are they for?
----

### kexec.sig TBD

### kexec_hashes.txt

This file holds the signatures of all of the files in /boot. On boot a new signature for the files is generated using your security token. The sigature would not match the file if either the hashes file or the /boot files have changed. Since an attacker will not have your security token they would not be able to modify the files in a way that would pass verification.

### kexec_hotp_counter TBD


### kexec_hotp_key TBD


### kexec_rollback.txt TBD




How do I boot my OS in the recovery shell?
----

Use Kexec-boot to ignore all verification and boot an OS.

```kexec-boot -b /boot -e ‘foo|elf|kernel /vmlinuz|initrd /initrd.img|append root=/dev/whatever’```


Can I use multiple security tokens?
----

Yes with some caveats. If the tokens have the same private key loaded they will perform the same cryptographic functions but the internal counter will always be different on each. This will show as tampering when switching between them. The best use case is to have one as a backup for the other. If the primary is lost the secondary may be used and the counter may be reset on first use.

What if we sign files in heads on two different systems with the same security token? Will the counter always be off?
----

YES?
TBD
37 changes: 25 additions & 12 deletions Development/Contributing-to-Heads-Wiki.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ The Heads wiki is open source and encourages contributions both big and small.
<!-- markdownlint-enable MD033 -->


On GitHub
Small Changes (On GitHub)
---
The simplest way to make a small change to existing pages is directly on GitHub
as it requires no software to be installed.
Expand All @@ -47,22 +47,27 @@ made in your fork.
button at the top of the page.


Locally
Large Changes (Local Files)
---

### Prerequisites

For larger changes, multiple changes and that may require adding new pages, it
is strongly suggested to set up a local Jekyll instance. Please refer to
[Jekyll's installation documentation](https://jekyllrb.com/docs/) to setup it
up on your system.
up on your system. You will need to install ruby and gems.

Additionally, the theme will also need to be installed as the remote theme does
not seem to work with locally severed Jekyll instances. Instructions for
installing the *Just the Docs* theme can be
[found here](https://pmarsceill.github.io/just-the-docs/).

ex. gem install just-the-docs

After installing Jekyll and the Just the Docs theme,
* Start by login into GitHub and forking
### Running Locally

After installing Jekyll and the Just the Docs theme you may run the wiki on your local system for faster testing and development.
* log in to GitHub and fork
[osresearch/heads-wiki](https://github.com/osresearch/heads-wiki). Then clone
your fork locally.
* Navigate to the base of the locally cloned repo and alter `_config.yml` to use
Expand All @@ -80,17 +85,25 @@ $> jekyll serve
This will start the Jekyll development web server and should be viewable in a
web browser at `http://localhost:4000/`

* create a branch in git for your changes
* Make the desired changes, commit them. **BE SURE NOT TO ADD `_config.yml`**
to your changes.
* Push the changes your forked repo.
* To allow you and others to view the changes on GitHub, the GitHub pages
branch may need to be changed. To do this, go to your fork of the heads-wiki on
* Push the changes to your forked repo on github

### Testing Changes on Github

You may use github to render the changes for review by others. To do this, go to your fork of the heads-wiki on
GitHub.com and click *Settings*. This should default you to the *Options* tab,
scroll down to the section "GitHub Pages" and change the source branch to the
name of the branch your changes are on. After a minute of so it should be built
and can be seen under `https://YOUR_USERNAME_HERE.github.io/heads-wiki/`
name of the branch your changes are on. After a minute or so it should be
available at `https://YOUR_USERNAME_HERE.github.io/heads-wiki/`
replacing `YOUR_USERNAME_HERE` with your GitHub username.
* Create a pull request.

** NOTE:** the email account associated with your GitHub account may receive an
error regarding the `CNAME`, this can be ignored.
error regarding the `CNAME`. Please ignore this.

Please note that the URL is similar but NOT the same as the wiki pages feature in your fork in github.

### Pushing Changes Upstream

Create a pull request in the osresearch/heads-wiki project that points to your changes to request review and contribute back to the parent project.