From 82951e2290bdb44267074f3005070a83324216d6 Mon Sep 17 00:00:00 2001 From: JT Moree <814771+jtmoree-github-com@users.noreply.github.com> Date: Wed, 27 Jan 2021 17:35:08 -0700 Subject: [PATCH 1/3] clarify wiki - expand sections of contributing to heads wiki - add gitignore for jekyll files --- .gitignore | 2 ++ Development/Contributing-to-Heads-Wiki.md | 37 +++++++++++++++-------- 2 files changed, 27 insertions(+), 12 deletions(-) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..64e3706 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +.jekyll-cache +_site diff --git a/Development/Contributing-to-Heads-Wiki.md b/Development/Contributing-to-Heads-Wiki.md index 4aa90f9..3421c54 100644 --- a/Development/Contributing-to-Heads-Wiki.md +++ b/Development/Contributing-to-Heads-Wiki.md @@ -28,7 +28,7 @@ The Heads wiki is open source and encourages contributions both big and small. -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. @@ -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 @@ -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. From 406e7b2f33c50e17e452ede921d2a8b35d5a2c63 Mon Sep 17 00:00:00 2001 From: JT Moree <814771+jtmoree-github-com@users.noreply.github.com> Date: Thu, 28 Jan 2021 05:47:48 -0700 Subject: [PATCH 2/3] update FAQ with unanswered questions --- About/FAQ.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 131 insertions(+), 1 deletion(-) diff --git a/About/FAQ.md b/About/FAQ.md index b07621d..f29ab34 100644 --- a/About/FAQ.md +++ b/About/FAQ.md @@ -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. + + suspend vs shutdown ---- @@ -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. + +How is TOTP used in heads? TBD +---- + +? Wish I knew. + coreboot vs Linuxboot ---- @@ -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? + + +When do I need to reflash the BIOS? TBD +---- + +To change the default boot +Anything else? + +What secrets are stored in BIOS? TBD +---- + +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? +---- + + 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 \ No newline at end of file From d87d5c3c2be72cbaf94ddf9297229a99a95d9345 Mon Sep 17 00:00:00 2001 From: JT Moree <814771+jtmoree-github-com@users.noreply.github.com> Date: Mon, 1 Feb 2021 07:14:09 -0700 Subject: [PATCH 3/3] replace 'wish i knew' with TBD --- About/FAQ.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/About/FAQ.md b/About/FAQ.md index f29ab34..7f35dca 100644 --- a/About/FAQ.md +++ b/About/FAQ.md @@ -188,15 +188,15 @@ 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 +How is HOTP used in heads? ---- -? Wish I knew. +TBD -How is TOTP used in heads? TBD +How is TOTP used in heads? ---- -? Wish I knew. +TBD coreboot vs Linuxboot ----