Wiki needs improvements

[ThatLurker]

The entire install section should be redone as its really hard to follow and understand.

we could "merge" the content from the current guide with this as base https://github.com/mfc/flashing-docs/blob/master/walkthrough%20for%20flashing%20heads%20on%20an%20x230.md

[tlaurion]

@pahakalle : This guide is unfortunately obsolete.

Can you clarify which section was harder to understand?

If there is one guide I would merge, it would be the one from @merge and promote a simple external programmer for users to use and order which, with flashrom compiled can be used from a secondary computer with: sudo ~/flashrom/flashrom --programmer ch341a_spi -w ~/heads/build/x230-flash/x230-flash.rom -c MX25L3273E

[ThatLurker]

The instructions mainly line 35 (Ok, now comes the time to write the 4MB...) are a bit hard to follow/read beacause its just a lot of text.

The guide merge has on skulls is a actually really good and with small modifications could just replace the one here

[GittCatt]

Well, I think the wiki still needs improvements, but for me the worst part is configuring TPM — there just isn't anything useful there. Are the appropriate sections from the outdated guide quoted by @pahakalle still applicable, maybe?

[tlaurion]

@Freewolny : using a board config enforcing gui-init instead of generic-gui is not covered at all by the current wiki pages, which still covers everything from the command line and per generic-init usage, and where most command line commands were replaced by simpler ones or by the GUI which manages those tasks easily and manage error situations automatically.

(see x230 board config or x230-hotp-verification, which later requires a Nitrokey Storage/Nitrokey Pro v2/ Librem Key to enforce HOTP verification ).

Following last link: screenshots, instructions etc should take into consideration whiptail usage that is applicable with/without beautiful graphic enforced by FBWhiptail (which is unusable in remote terminal).

For example, the kgpe-d16 PR enforces gui-init without fbwhiptail for servers while enforcing graphical interface with FBWhiptail for the workstation. So that even on compatible server platforms, gui-init can be used instead of currently documented generic-init under wiki, which became kinda deprecated.

Meanwhile this beginner's page was created, which doesn't cover configuration and Heads daily usage.

Any help welcome redoing the wiki pages.... Is there volunteers?

[GittCatt]

Well, when I manage to do everything myself – reflashing the boards in X230, installing Heads and so on, I'll gladly edit the wiki to make it work for complete newbies like me… but I have a feeling that before this happens, I will need a ton of support myself, unfortunately.

[tlaurion]

@Freewolny please read last link of my previous reply. Your concerns are answered there.

[GittCatt]

One more question – is it currently possible to have an additional keyfile for LUKS encryption stored in TPM?

[tlaurion]

@Freewolny yes. Its called a Disk Unlock Key and is enforced by setting a boot default under Heads on all boards having a TPM, but Purism ones, by default.

TPM NVRAM space releases the key on good Disk Unlock Key passphrase if LUKS header and firmware measurements are valid.

When setting a new boot default, the Disk Revovery Key (key slot 0) is required to be typed to renew/change Disk Unlock Key passphrase (slot 1).

[GittCatt]

But from what I understand, in the solution described by you, the TPM is in possession of the whole decryption key, but releases it only after I authenticate myself to it. So if there was a way to extract the key from the TPM, the attacker would only need my laptop and would have the whole disk decrypted. Admittedly, if the attacker is able to do it, he can probably also employ an evil maid attack and sniff my decryption password, but it's still more effort, as I see it.

I'm looking more for a solution described here:

If an attacker is able to capture the user's keystrokes (hidden camera, electromagnetic leaks), the attacker doesn't need Evil Maid attack anymore, and so doesn't need to bother with compromising the system boot anymore. This is because the attacker can just sniff the disk decryption password, and then steal the laptop and will get full access to all user data.

In order to prevent such a “keystroke sniffing” attack, one can use an additional sealed secret on the Anti Evil Maid stick that would be used as a keyfile for LUKS (in addition to passphrase). In this case the knowledge of the sniffed LUKS passphrase would not be enough for the attacker to decrypt the disk. This has not been implemented, although would be a simple modification to dracut-antievilmaid module. If you decided to use this approach, don't forget to also create a backup passphrase that doesn't need a keyfile, so that you don't lock yourself from access to your data in case you lose your stick, or upgrade your BIOS, or something! You have been warned, anyway.

[tlaurion]

The threat model adressed currently through Heads is the evil maid able to capture the passphrase typed at boot and expecting to be able to clone the disk while owner is away and be able to decrypt the content at their leisure.

What you are looking for is some kind of 2fa or more specifically the part where you need an external device (something you own) to be able to boot the device.

This is not currently implemented, while when QubesOS will upgrade their Dom0, changes having been merged into cryptsetup and some additional changes inside of Heads could permit what you are looking for. Another option would be to have to have the USB security dongle combined and make the user sign with the dongle prior of permitting boot.

Those implementations have risks themselves.

1. If the user looses his external device (boot device/USB security dongle), he can't boot his system anymore

The mitigation are to:

1. Never leave the computer unattended after having unlocked the computer when roaming in unknown space. Or set a new boot default as often as desired when having doubts of having been eavesdrop. The Disk Recovery Key passphrase should only be typed in safe space (slot 0) while the Disk Unlock Key, released by the TPM, should be changed following your threat model.
2. Have your hard drive separated from your computer when roaming.

[tlaurion]

@Freewolny : basically, you are talking about something like this https://docs.puri.sm/PureBoot/LibremKeyLUKS.html

If it is the case, please open an issue under Heads, not heads-wiki.

[Thrilleratplay]

I recently built and installed heads for the first time. Had I not been familiar with coreboot, I would have been very confused by the wiki. Some details are glossed over, some are found on other pages and others are duplicated in different sections, some are wrong (x220 does not have a 4mb chip, only an 8mb). With https://github.com/osresearch/heads/pull/703, portions of the wiki could theoretically be simplified. In the meantime, I attempted to unify the documentation but am in over my head.....over my heads?....nope, head, no puns here. I am too new to know where the project has been or where it is going nor arrogant enough to start rewriting large portions of the wiki.

This is what I came up with when trying to reorganize it. Ignore the theme; I repurposed a flatdoc theme made a few years ago. I wanted to focus on the content and not waste time setting up Jekyll. Also, it really should not be one large page, but sections should be consolidated and easily navigable.

A few things to note:

• The Heads FAQ page was copied to the wiki instead of link to an external page. Those not familiar with project and osresearch my not understand why they are being linked to a page on trmm.net. It is a little difficult to preach security when sending potential users to seemingly unrelated sites.
• Created a list of the devices that are supported, should they link to the product pages? It makes sense for Purism products but does it make sense for old Lenovo laptops?
• The build guide gives vague suggestions on the libraries required to build but these will different from platform to platform. What about creating an official docker image, similar to coreboot, for building Heads on? I modified my coreboot-builder-scripts for Heads but have not published them yet (need more testing).
• There is a lot of overlap between this and Skull's flashing guide. Perhaps @merge is open to the idea of creating a unified set of documentation for flashing that can be project agnostic.
• I have been planning on creating abstract scripts to automate certain tasks like creating backups of the original rom via flashrom by running it in a loop until hash matched set is created and rename with a timestamp or flash scripts that create backups first with unique names in case an update goes wrong. Little helper scripts may simplify the wiki even more.

Again, I am new to this project so I may be way off base or out of line with some of these suggests. If so, just mock me and tell me off.

[tlaurion]

@Thrilleratplay : I love the live version sitting at https://thrilleratplay.github.io/heads-wiki/ Consequently of #44. I would be agreeing with the reordering and removing trmm.net links, while most of the screen captures are linked to generic-init instead of #40, with some miseading information here and and there (Xen is not included in Heads since a while, there is no Read only FS under QubesOS, x220 flash is not 4mb... All those should be removed. Generic user guide should be taken out of https://docs.puri.sm/PureBoot.html (CC by SA) and manually republished upstream.

• The Heads FAQ page was copied to the wiki instead of link to an external page. Those not familiar with project and osresearch my not understand why they are being linked to a page on trmm.net. It is a little difficult to preach security when sending potential users to seemingly unrelated sites.

Agreed. Cannot take this decision myself though. @osresearch : docs should be self contained.

• Created a list of the devices that are supported, should they link to the product pages? It makes sense for Purism products but does it make sense for old Lenovo laptops?

Coreboot pages should be referred instead?

• The build guide gives vague suggestions on the libraries required to build but these will different from platform to platform. What about creating an official docker image, similar to coreboot, for building Heads on? I modified my coreboot-builder-scripts for Heads but have not published them yet (need more testing).

The point here would then be: how to recreate those docker images. I modified the instructions to point to CircleCI and GitlabCI instructions recently. I'm not convinced that a docker image would be the solution to reproducibility, and would lead to unmaintained docker images too. I'm ready to debate the idea though, since maintaining CIs is actually not a so easy task which I underestimated.

• There is a lot of overlap between this and Skull's flashing guide. Perhaps @merge is open to the idea of creating a unified set of documentation for flashing that can be project agnostic.

Agreed. That was a really long debate. The solution proposed is https://github.com/osresearch/heads/issues/571 Where, as of right now, each commit on Heads github is linked to roms produced on CircleCI (with issue https://github.com/osresearch/heads/issues/768) with reused cache.

• I have been planning on creating abstract scripts to automate certain tasks like creating backups of the original rom via flashrom by running it in a loop until hash matched set is created and rename with a timestamp or flash scripts that create backups first with unique names in case an update goes wrong. Little helper scripts may simplify the wiki even more.

-v does exactly that. Looping it is not so good idea since if backup and verify fails, that would mean the clip needs to be manually replaced.

[Thrilleratplay]

@tlaurion

• Created a list of the devices that are supported, should they link to the product pages? It makes sense for Purism products but does it make sense for old Lenovo laptops? Coreboot pages should be referred instead?

That is a good option for the Lenovo's. I am not sure if that would be confusing to new users, shrugs probably could be fixed with it explicit saying it is going to the coreboot docs.

Looping it is not so good idea since if backup and verify fails, that would mean the clip needs to be manually replaced.

Not necessarily, the Raspberry Pi bus speed can introduce enough variance to alter a checksum. I ran into this a few times before switching to a Ch341A. My issue with -v is it requires specifying a file, if a file is not specified, it would be nice if it would read a second time, create a temporary file to verify against then remove it if they match. Originally, I thought the specific chips Lenovo used was buried in the official BIOS upgrade software; I found it then forgot where I saw it but found it again and posted it [heads #716](in https://github.com/osresearch/heads/issues/716). If the specific chips where known, it could be hard coded in said script. Sadly, this isn't the case. Oh well.

The point here would then be: how to recreate those docker images.

It depends on how you would want to approach it.

1. Unless I am mistaken, the goal of reproducible builds is to create the same file regardless of environment. An official Docker image could be similar to coreboot-sdk where the docker environment is used in the reproducible build CI; moving the package dependency maintenance to the container. If published on docker hub, a user could simply pull the image instead of trying to figure out all of the individual packages build packages for their flavor of Linux. This does not need to be limited to a single distro, something similar to this could be heads-debian-sdk and a similar one could be created using Fedora as a base.
2. A Docker image can be reproduced using the same method that verified Docker images are recreated, building from a SHA256 named compressed file containing the image. Here is an example of one of Debian's. Theoretically, these could be created with the cross compiler already built, making testing and local builds much faster.

EDIT: Of course a few hours after I write this I run into an issue. The head-builder-scripts currently work with x230 and qemu-coreboot but there is an issue with the version of gawk when trying to build qemu-linuxboot. This may actually be another use case for using docker images as gawk is a fairly standard utility in Linux and is a specific version is needed.

I noticed the open issues regarding CircleCi builds, using Guix and a few other build related things. If docker images were to compartmentalize build environment dependencies and referenced in the documentation, it may save a lot of headaches trying to help debug different issues across an infinite possible of users environments. It may also make it worse, I am not familiar enough the range of issues that occur.

As for shared flashing documentation across different projects. That may just be a pipe dream. It is difficult enough with different devices and programmers but the same device can have different chips and there are so many variations of CH341A programmers as well as different RPi and BusPirate versions. This is bad enough when dealing with just answering questions of coreboot users on Reddit, then trying to mix this across with different projects whose user backgrounds and technical experience will vary. Just to add more wrenches, how about translations? This is an issue that should be addressed but is beyond the scope of this issue.

[tlaurion]

@Thrill

The build guide gives vague suggestions on the libraries required to build but these will different from platform to platform. What about creating an official docker image, similar to coreboot, for building Heads on? I modified my coreboot-builder-scripts for Heads but have not published them yet (need more testing).

Interesting. Looking into this to troubleshoot https://github.com/osresearch/heads/issues/608

Edit: refacing the problem of having docker inside of QubesOS. digging it as a first step, will update later. edit 2: found that I wrote something in the past. replaying https://gist.github.com/tlaurion/9113983bbdead492735c8438cd14d6cd/48a9ce8c536d14d1bf9578ce9055581a9c46b851

[Thrilleratplay]

@tlaurion I knew I was forgetting to do something today. I made an edit in the comment above regarding gawk version issues, it likely won't impact the debugging you are doing but did want to call it out.

[tlaurion]

@Thrilleratplay https://github.com/osresearch/heads/pull/811 was merged no?

Docker inside of QubesOS instructions updated https://gist.github.com/tlaurion/9113983bbdead492735c8438cd14d6cd

Running your script user@coreboot-native:~/coreboot-builder-scripts$ ./build.sh -t 4.12 x230

[Thrilleratplay]

@tlaurion Yeah, I assumed osresearch/heads#811 was the cause. I need to take steps to try to remove gawk from the heads builder docker image. It is only impacting the qemu-linuxboot build. I will try to take a look at it later but also need to clear off space, I didn't keep an eye on the space all of the different heads builds, among other projects, were using and ran out of space on my laptop. I am running Arch on my coreboot x230 and forgot about docker having issues on Qubes. That would be a good item to have in the wiki as well.

[tlaurion]

@Thrilleratplay

about docker having issues on Qubes

https://gist.github.com/tlaurion/9113983bbdead492735c8438cd14d6cd just reproduced and working.

(still downloading coreboot/coreboot-sdk:1.53' locally which seems to be heavy for my damn slow internet link)

[jtmoree-github-com]

I am reworking the Wiki pages to move OS specifics into subfolders, add recovery shell page, and a few other cleanups. Though I have a first pass (https://github.com/jtmoree-github-com/heads-wiki/tree/docs-refresh) in a fork I think there are syntax problems. I'm attempting to setup the environment to test locally based on this page: https://docs.github.com/en/github/working-with-github-pages/testing-your-github-pages-site-locally-with-jekyll

Am I overthinking this? Is there an easier way to test the docs?

[Thrilleratplay]

@jtmoree-github-com http://osresearch.net/Contributing-to-Heads-wiki/

[jtmoree-github-com]

I have re-organized and heavily edited the wiki in a fork. It has a few issues I'd like to clean up before a PR. https://github.com/jtmoree-github-com/heads-wiki

1. the submenu in the Installing OS refuses to show up. I don't know what I"m doing wrong
2. tpm sections are still sparse. I dont understand heads+tpm enough
3. totp/hotp sections are still sparse. dont understand them yet either
4. recovery shell doc is a WIP.

Any feedback appreciated. Not sure there is an easy way for any of you to see this given that the wiki is hosted outside of github. Likely you would need to pull my fork, edit _config.yml, and run jekyll serve.

[Thrilleratplay]

@jtmoree-github-com Can you set the Github pages branch for your fork to docs-refresh so it will be visible on https://jtmoree-github-com.github.io/heads-wiki?

[jtmoree-github-com]

@Thrilleratplay Not so far. I'm assuming there is a reason that the heads wiki is hosted outside of github. After an hour of trying it does not render correctly. If someone can give me the proper _config.yml settings I'll be happy to apply them to my fork.

[jtmoree-github-com]

I created a second branch for the FAQ since it is just one document. If we answer all of the questions in it I will have better source material for the rest of the wiki. This is the branch https://github.com/jtmoree-github-com/heads-wiki/tree/faq and this is the link to the file itself https://github.com/jtmoree-github-com/heads-wiki/blob/faq/About/FAQ.md

I am happy to post all of the questions somewhere else to facilitate collaboration. Just let me know what would be the best method for this. An alternative would be to pull request which would allow reviewers to answer the questions and suggest changes. Once I integrate all of that a second PR would finish the process.

[Thrilleratplay]

@jtmoree-github-com The wiki is hosted on github but uses the domain name of osresearch.net. If you go to https://osresearch.github.io/heads-wiki/ it will redirect you to the domain due to the repo settings. Alternatively, if you went to my fork, https://thrilleratplay.github.io/heads-wiki/, you can see wiki built for [the master branch of my fork( https://github.com/Thrilleratplay/heads-wiki) but with the "Heads on GitHub" in the header and the edit links at the bottom of each page pointed to osresearch's repo as these are setting in the _config.yml. It is all a little bit of smoke and mirrors and easily missed for anyone not familiar with Github, Github pages and Jekyll being integrated with Github pages.

By default, the Github pages branch, I believe, is set to none. Change this to docs-refresh and it should build your changes in your fork the way it they will ultimately look on osresearch.net. It makes it easier to check formatting, links are rendered correctly, etc. As this is a pull request, it must be set up to be merged directly into osresearch/heads-wiki, while tempting, do not make commit any changes to _config.yml. We know the edit links at the bottom of the pages will not point to the correct repo now but they will. You will also likely get an email about an error with CNAME, ignore this.

[jtmoree-github-com]

easily missed for anyone not familiar with Github, Github pages and Jekyll being integrated with Github pages.

Yes, I am unfamiliar with github + jekyll.

If I cannot commit and push _config.yml how do I make changes to it on github so that it will render the way we want?

Are you using both the 'forked repo' and the 'wiki repo in the fork'?

Is there ssh/scp access so that I can upload the file? How would that integrate with the git repo?

I will document in the Development section once I know how this works.

[Thrilleratplay]

@jtmoree-github-com On Github, in your fork, there will be a link along the top "Settings". Under Settings->Options->Github Pages change the source branch to docs-refresh, the default path should be / (root). Don't worry about the theme. The build time can vary depending on the load of the servers, but it will likely be ready in under a minute.

When ready, create a pull request for it to be reviewed.

[jtmoree-github-com]

I started over (saved my changes) by deleting and forking heads-wiki again. I am following the instructions on this page: http://osresearch.net/Contributing-to-Heads-wiki/. I have NOT changed anything in the fork so it should match the current repo exactly.

After the fork, I immediately went to settings, turned on the wiki, changed the Github pages to the master branch and click save. I got the email about the CNAME but the wiki doesn't show the content. https://github.com/jtmoree-github-com/heads-wiki or https://github.com/jtmoree-github-com/heads-wiki/wiki. I have also turned the wiki off and tried it that way since the instructions don't mention the Wiki setting.

Appreciate the help. Thank you,

[Thrilleratplay]

@jtmoree-github-com It built, but you are looking at the wrong address. Check out https://jtmoree-github-com.github.io/heads-wiki

I noticed last night and amended my last comment as not to spam the issue. When ready, create a pull request for it to be reviewed. The PR is where all comments on a change are made.

[jtmoree-github-com]

I'm reviewing the Generic OS installation page. http://osresearch.net/InstallingOS/

For certian OSes , the Heads boot process supports standard OS bootable media where the USB drive contains the installation media. This is generally created using dd or unetbootin etc.

I have booted quite a few different USB installers that are not listed at the link referenced in this statement. (https://github.com/osresearch/heads/tree/master/initrd/etc/distro/keys) Is the gui-init still checking keys the way generic-init is documented on this page?

[tlaurion]

@jtmoree-github-com if you did dd copy of disk image, the iso detached signature is not checking anything. The checking mechanism happens by:

1-generic-init: https://github.com/osresearch/heads/blob/master/initrd/bin/generic-init#L22 https://github.com/osresearch/heads/blob/master/initrd/bin/generic-init#L42-L44

1-gui-init: https://github.com/osresearch/heads/blob/master/initrd/bin/gui-init#L25-L33 https://github.com/osresearch/heads/blob/master/initrd/bin/gui-init#L44-L46

calls 2-usb-init https://github.com/osresearch/heads/blob/master/initrd/bin/usb-init#L12

3- usb-scan 3.1 ISO boot with detached signature verification (authenticity/integrity validation) https://github.com/osresearch/heads/blob/master/initrd/bin/usb-scan#L20-L80 3.2 Direct mounting and booting from media https://github.com/osresearch/heads/blob/master/initrd/bin/usb-scan#L82-L88

And for 3.1, the distro key integration happens really early in init: https://github.com/osresearch/heads/blob/master/initrd/init#L54-L57 key-init: https://github.com/osresearch/heads/blob/master/initrd/bin/key-init#L7-L17

Hope that answers your questions.

[jtmoree-github-com]

Heads also supports booting directly from verified ISOs on a plain old partition.

Each ISO is verified before booting so that you can be sure Live distros and installation media are not tampered with, so this route is preferred when available. You can also sign the ISO with your own key:

[Update: The previous statement in the docs is misleading. Please ignore next paragraph] In this scenario heads will check the ISO against a corresponding signature in the same location. This does not prevent an attacker from modifying the ISO and the signature. In that case Heads will not be able to detect tampering. Is this correct?

Signing with my own key would detect tampering since an attacker would not have access to my private key.

For example, if the USB drive has a single partition,

Does this only work if the USB has a single partition? If there are more partitions are they ignored or does the boot process do something different?

[tlaurion]

@jtmoree-github-com

Heads also supports booting directly from verified ISOs on a plain old partition.

In this scenario heads will check the ISO against a corresponding signature in the same location.

A detached signature is what is in play here. To detach sign, you need to sign that something with your private key (and GPG User PIN of USB Security dongle) to create the signature file that will accompany the file you are signing. The result for signing file.type is file.type.asc/file.type.sig, and when applying the detached signature validation, the public key associated with that private key needs to exist in local keychain to be able to validate the detached signed file and verify autnenticity/integrity of the file that was detached signed.

This does not prevent an attacker from modifying the ISO and the signature. In that case Heads will not be able to detect tampering. Is this correct?

You change one bit in your ISO, the detached signature, signed with your private key, won't match the content of the file that was signed. If the public key in your Heads keyring (user files have a special type 50 in cbfs are measured under PCR7) doesn't match the one in your keyring, the verification will fail.

TL;DR: no, you cannot modify the ISO, nor the detached signed file, without also requiring to add that valid valid public key inside of either /etc/distro (ROM) or adding a public key in ROM (measured cbfs type 50 file, added in preserve_rom in flash logic). Changing the rom would invalidate measurements,specifically invalidating PCR7, TOTP+HOTP, Disk Unlock Key not being able to be released by TPM, etc. The same logic of adding public key can be seen on the GPG option counterpart of Heads in GUI mode (generic-init users need those tasks to be done from command line).

Documentation is here: https://osresearch.net/InstallingOS/#boot-config-files

As for the distro keys, the logic is the same as for local keyring, while the distro key's private key is not owned, only the public key is inside of a distinct keyring inside of heads, having Tails, QubesOS (and non functional Fedora public key, since they do not publish detached signed iso anymore, not sure why but there is an issue about it).

And for 3.1, the distro key integration happens really early in init: https://github.com/osresearch/heads/blob/master/initrd/init#L54-L57 key-init: https://github.com/osresearch/heads/blob/master/initrd/bin/key-init#L7-L17

So basically, if you do not intend to boot from QubesOS/Tails, you will have to

1- mount-usb rw 2- cd /media 3- gpg --card-status 4- gpg --detach-sign my.iso 5- mount -o remount,ro /media 6- usb-scan (or reboot and go from gui)

To boot from an iso not being QubesOS/Tails for which public key is in ROM and for which downloaded bootable.iso.asc/bootable.iso.sig file sits beside bootable.iso.

The code responsible to boot ISO is kexec-iso-init https://github.com/osresearch/heads/blob/master/initrd/bin/usb-scan#L76 which does the validation against keyrings existing in memory https://github.com/osresearch/heads/blob/master/initrd/bin/kexec-iso-init#L11-L21

Again:

And for 3.1, the distro key integration happens really early in init: https://github.com/osresearch/heads/blob/master/initrd/init#L54-L57 key-init: https://github.com/osresearch/heads/blob/master/initrd/bin/key-init#L7-L17

Let's remember that the last line of kexec-init is taking user's keyring and appends it in what is considered distro keys to verify ISO's here: https://github.com/osresearch/heads/blob/master/initrd/bin/key-init#L16-L17 (exported and imported under /etc/distro gpg keyring to verify iso "ditro keys", here including user's own keyring as ultimately trusted) so that all "trusted" public keys are validated to verify detached signature (bootable.iso.sig or bootable.iso.asc accompanying the iso found in path)

For example, if the USB drive has a single partition,

Does this only work if the USB has a single partition? If there are more partitions are they ignored or does the boot process do something different?

in 3.1 and 3.2 above, usb-scan calls mount_usb https://github.com/osresearch/heads/blob/master/initrd/bin/usb-scan#L14-L18 mount_usb (not mount-usb): https://github.com/osresearch/heads/blob/master/initrd/etc/gui_functions#L4-L71 Which calls mount-usb if nothing is already mounted under /media https://github.com/osresearch/heads/blob/master/initrd/bin/mount-usb#L24-L114

Giving you the possibility to pick the partition from which to boot your detached signed ISO, or boot insecurely from a USB disk as a fallback.

TODO: This should also be safeguarded by https://github.com/osresearch/heads/issues/356 from something like https://github.com/osresearch/heads/pull/361

[tlaurion]

I think there should be maybe more time invested into documenting how to dig code, then to write doc for code that is still changing.

Not sure how to do that.

More comment in code instead of external documentation seems more interesting to me. The maintainership problem once again. We see it already, the documentation is way behind the code base as of now. Way behind. And duplicating documentation out of code actually is the cause of that. Lazyness of reading code is one thing, having it too cryptic is another. But my recommendation seeing the new flow of questions coming in for the Heads project is that maybe a general flow of operations in flow chart should be created (more stable) with clickable links into code, where code is more commented and external documentation is maintained to be as minimalist as possible. Otherwise, I bang my head on the walls everytime I surf around and read comments on Reddit and elsewhere, pointing to old docs, bad understanding of what is happening, simply, in my opinion, because of lack of actual code documentation, and outdated external documentation.

@Thrilleratplay ?

[tlaurion]

Silly idea here, but:

• screenshots of menu, where clicking on it would point to commit version of that code in blame mode would point to where the code lies. And then code should document what happens there. High level, and where functions being external (gui_functions, functions, mount_usb not being mount-usb) should be clarified or simply recentralized for easier comprehension.

What you think? User/Dev/documentarist perspectives welcome.

[GittCatt]

That is an absolutely awesome idea (as a user who might be able to dig into code to some extent, but on a day-to-day basis codes something completely different). If the code would really be well documented, that could be a great help in order to grasp a better understanding of some of the internals.

pt., 29 sty 2021, 17:44 użytkownik tlaurion notifications@github.com napisał:

Silly idea here, but:

• screenshots of menu, where clicking on it would point to commit version of that code in blame mode would point to where the code lies. And then code should document what happens there. High level, and where functions being external (gui_functions, functions, mount_usb not being mount-usb) should be clarified or simply recentralized for easier comprehension.

What you think? User/Dev/documentarist perspectives welcome.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/osresearch/heads-wiki/issues/25#issuecomment-769916817, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACFKALGLREWEXXFJ4ANTSQTS4LQXBANCNFSM4GRHYM3A .

[Thrilleratplay]

@tlaurion I am not sure myself. This is part of the reason I made mostly structural changes to the wiki. I started to fall into the trap I think @jtmoree-github-com is approaching.

This is personal perspective, Heads is tantalizing to people worried about security but usually attract those who think naive about encryption, security and open source development. The project itself is brilliant but fragmented. There is a lot of hostility from newbies who think this will be a drop in upgrade and are quickly overwhelmed with the complexity. The poor documentation is usually the biggest complaint.

The idiom "those who can't do, teach", something I never understood until college, becomes the catch 22 with Heads documentation. If you don't know enough about Heads, you start to dive through the code to understand it, becoming to familiar with the code, it is difficult to explain it in a high enough level for those who are brand new can understand and abstract enough where it is not immediately obsolete. This is the trap I feel into, I became so familiar with the code, the wiki makes no sense to me.

A few ideas:

• I need to get back to Heads #885. initrd contains a hodgepodge of different scripts with inconsistent styles and, where there is shared code, the usage is not well documented. I believe this is the source of a lot of bugs and grief whenever an update is made. My goal is to create a shared, well documented, fully unit tested framework of functions similar to initrd/etc/functions and initrd/etc/gui_functions but broken down into manageable and identifiable .sh files (a basic example is in the ticket). Any Heads related command/script would be stripped down to only a call to some of these framework functions and a usage function. So, for example, if kexec-boot were executed in the rescue shell, it would print a description of what it does and all of the available options, the script itself would have no logic (other than maybe arg parsing and basic error checking), and simply calls the function that assembles kexec execution. Documentation can be generated by executing the usages of each of these end user facing scripts.

• 64 On the front page of the wiki, there should be diagram explaining the ring of trust the exists between the Heads Rom, TPM and the physical encryption key. Other diagrams, like where do the different keys reside, would also be helpful...to me in particular...as I am constantly getting those wrong when answer questions.

• 63 A glossary to the wiki, as some terms are easy to mix up. I would love it if glossary terms were automatically annotated/tool-tips so when a user is reading through, if they are confused on a term they could mouse over and be reminded what it is without loosing there spot. This would require some development with Jekyll plugins and HTML templates for the theme.

[jtmoree-github-com]

I like the idea of linking wiki docs to source code to supplement high level documentation. I have been updating the docs as I figure out how heads works and waiting for feedback before creating PRs. I just posted 2 more.

https://github.com/osresearch/heads-wiki/pull/67 is for new questions to the FAQ. These are questions I have as a new user to heads. Many are still unanswered. Hopefully we can fill more in during the review process.

https://github.com/osresearch/heads-wiki/pull/66 is for a bit of re-org on the wiki and new pages for recovery shell and OS installs.

[jtmoree-github-com]

64 On the front page of the wiki, there should be diagram explaining the ring of trust the exists between the Heads Rom, TPM and the physical encryption key. Other diagrams, like where do the different keys reside, would also be helpful...to me in particular...as I am constantly getting those wrong when answer questions.

I would create such a diagram but I don't understand enough to do so. Is there one I can use for reference anywhere? Or can someone create a crude text version of it in this thread that I can turn into an image?

[tlaurion]

I can go iteratively and answer questions as we go.

0. build system is another discussion.

Runtime:

1. coreboot Depending of coreboot version and coreboot support for board, measurements happens in bootblock or in romstage. 1.1 Under coreboot 4.8.1, its easier to track because it was a patch applied to coreboot itself: https://github.com/osresearch/heads/blob/master/patches/coreboot-4.8.1/0000-measuredboot.patch 1.2 On 4.9+ the codebase was added into VBOOT codebase (references needed) 1.3 under coreboot 4.12(?) TPM_MEASURED_BOOT was added, relying not relying on the VBOOT+measured boot codebase, to do the measurements. The documentation here should answer questions: https://doc.coreboot.org/security/vboot/measured_boot.html Coreboot 4.8.1 patch was modified to push all measurements under PCR2 so that measurement schemes of Heads are the same across VBOOT+measured boot or TPM_MEASURED_BOOT, where Heads uses additional PCRs to measure additional stuff and states: https://osresearch.net/Keys/#tpm-pcrs

2. Heads fires up (which is basically a linux kernel and an initrd. Heads scripts and binaries are included in the initrd) A decompression example is here if someone wants to reverse what is built inside of Heads Makefile: https://github.com/osresearch/heads/issues/590#issuecomment-623143332

3. initrd is decompressed, Linux kernel is booted. We enter Heads from init: https://github.com/osresearch/heads/blob/master/initrd/init

4. Measurements from coreboot, depending on TPM patches/TPM_MEASURED_BOOT are taken. (use of tpm internal binary from heads tpmtotp module: https://github.com/osresearch/heads/blob/master/modules/tpmtotp, used as a base for HOTP operations, from https://github.com/osresearch/heads/blob/master/modules/hotp-verification) Then: 4.1 cbfs-init if coreboot as explained above to use what was saved as user file to be measured inside of PCR7(? from memory here) https://github.com/osresearch/heads/blob/master/initrd/init#L47-L49 4.2 combination of /etc/config.user if found in cbfs from cbfs-init https://github.com/osresearch/heads/blob/master/initrd/init#L92-L93 4.2.1 which calls combine_configs https://github.com/osresearch/heads/blob/master/initrd/etc/functions#L266-L268 4.3 Then booting of board configured bootscript: https://github.com/osresearch/heads/blob/master/initrd/init#L57 Then we split up between generic-init (legacy) and gui-init scenario (or even network-init-recovery): 4.3.1 https://github.com/osresearch/heads/blob/master/initrd/bin/gui-init 4.3.2 https://github.com/osresearch/heads/blob/master/initrd/bin/generic-init 4.3.3 https://github.com/osresearch/heads/blob/master/initrd/bin/network-init-recovery

5. Then if we concentrate only on gui-init 5.1 for usb boot was explained here: https://github.com/osresearch/heads-wiki/issues/25#issuecomment-769364795 5.2 default boot when /boot detached sign is verified, HOTP remote attestation based on TPM measurements leads to: 5.2.1 generation of /boot digest, verification of integrity against detached signed version of it 5.2.1.1 failing codepath 5.2.1.2 sucessful codepath 5.2.2 HOTP sucess/fail codepath 5.2.3 TPM unsealing of Disk unlock key codepath 5.2.3.1 extraction of LUKS header 5.2.3.2 unsealing of TPM nv region with firmware measurements + LUKS header + Disk Unlock Key passphrase input from user 5.2.4 kexec call to OS with/without Disk Unlock Key passed to OS as kernel additional initrd

@ jtmoree-github-com Please ask questions on precedent points.

[jtmoree-github-com]

Started a glossary as I work through some diagrams. All can be reviewed here: https://drive.google.com/drive/folders/14TSM4U0fNYlQpzQEDnpZGCc8eAGDZhSl?usp=sharing

Still early on the diagrams but if you start with HEADS OVERVIEW you will get the idea of where I am going with this.

[tlaurion]

I would have lots of comments and corrections to propose for each diagram.

Can those images be in a shared doc with shared writing access? A pad, or a PR, or a cryptpad.fr?

[jtmoree-github-com]

You should be able to comment now. I can add individual gmail accounts as editors too.

[tlaurion]

I will try to find time in the next coming days and post comments here in regard of filenames on google drive.

[tlaurion]

@jtmoree-github-com A PR with those graphics that will change with Q&A flow would be helpful. Otherwise, I see involvement in all PRs and issues closed will really be time consuming correcting misconceptions... clarified in code.

[tlaurion]

At this point, I belive you should just branch the current master of the PR, and ask question in code. Reviewing the diagrams and current state of https://docs.google.com/document/d/1F7SeHrgYFbbhdBT0fsvddIDvkv0DlnTvjtbTQA00wec/edit#heading=h.5h6usohk6neg as a start doesnt feel like a Frequently Asked Questions at all, but personal questions torward the code, in which I could probably invest 10 hours or more explaining everything. Who is the audience?

[tlaurion]

First review directly on drawings and texts directly

[tlaurion]

I can go iteratively and answer questions as we go.

1. build system is another discussion.

Runtime:

1. coreboot
   Depending of coreboot version and coreboot support for board,  measurements happens in bootblock or in romstage.
   1.1 Under coreboot 4.8.1, its easier to track because it was a patch applied to coreboot itself: https://github.com/osresearch/heads/blob/master/patches/coreboot-4.8.1/0000-measuredboot.patch
   1.2 On 4.9+ the codebase was added into VBOOT codebase (references needed)
   1.3 under coreboot 4.12(?) [TPM_MEASURED_BOOT](https://github.com/coreboot/coreboot/commit/c79e96b4eb310db9d44e36e2dff072c01469c380) was added, relying not relying on the VBOOT+measured boot codebase, to do the measurements.
   The documentation here should answer questions: https://doc.coreboot.org/security/vboot/measured_boot.html
   Coreboot 4.8.1 patch was modified to push all measurements under PCR2 so that measurement schemes of Heads are the same across VBOOT+measured boot or TPM_MEASURED_BOOT, where Heads uses additional PCRs to measure additional stuff and states: https://osresearch.net/Keys/#tpm-pcrs

2. Heads fires up (which is basically a linux kernel and an initrd. Heads scripts and binaries are included in the initrd)
   A decompression example is here if someone wants to reverse what is built inside of Heads Makefile:
   [osresearch/heads#590 (comment)](https://github.com/osresearch/heads/issues/590#issuecomment-623143332)

3. initrd is decompressed, Linux kernel is booted.
   We enter Heads from init:
   https://github.com/osresearch/heads/blob/master/initrd/init

4. Measurements from coreboot, depending on TPM patches/TPM_MEASURED_BOOT are taken.
   (use of tpm internal binary from heads tpmtotp module: https://github.com/osresearch/heads/blob/master/modules/tpmtotp, used as a base for HOTP operations, from https://github.com/osresearch/heads/blob/master/modules/hotp-verification)
   Then:
   4.1  cbfs-init if coreboot as explained above to use what was saved as user file to be measured inside of PCR7(? from memory here)
   https://github.com/osresearch/heads/blob/master/initrd/init#L47-L49
   4.2 combination of /etc/config.user if found in cbfs from cbfs-init
   https://github.com/osresearch/heads/blob/master/initrd/init#L92-L93
   4.3 Then booting of board configured bootscript:
   https://github.com/osresearch/heads/blob/master/initrd/init#L57
   Then we split up between generic-init (legacy) and gui-init scenario (or even network-init-recovery):
   4.3.1 https://github.com/osresearch/heads/blob/master/initrd/bin/gui-init
   4.3.2 https://github.com/osresearch/heads/blob/master/initrd/bin/generic-init
   4.3.3 https://github.com/osresearch/heads/blob/master/initrd/bin/network-init-recovery

5. Then if we concentrate only on gui-init
   5.1 for usb boot was explained here: [#25 (comment)](https://github.com/osresearch/heads-wiki/issues/25#issuecomment-769364795)
   5.2 default boot when /boot detached sign is verified, HOTP remote attestation based on TPM measurements leads to:
   5.2.1 generation of /boot digest, verification of integrity against detached signed version of it
   5.2.1.1 failing codepath
   5.2.1.2 sucessful codepath
   5.2.2 HOTP sucess/fail codepath
   5.2.3 TPM unsealing of Disk unlock key codepath
   5.2.3.1 extraction of LUKS header
   5.2.3.2 unsealing of TPM nv region with firmware measurements + LUKS header + Disk Unlock Key passphrase input from user
   5.2.4 kexec call to OS with/without Disk Unlock Key passed to OS as kernel additional initrd

@ jtmoree-github-com Please ask questions on precedent points.

@jtmoree-github-com want to ask questions on the precedent points prior of going forward so I can modify precedent post and address questions? Edited with TPM_MEASURED_BOOT implementation change directly from coreboot merge.

[jtmoree-github-com]

At this point, I belive you should just branch the current master of the PR, and ask question in code. Reviewing the diagrams and current state of https://docs.google.com/document/d/1F7SeHrgYFbbhdBT0fsvddIDvkv0DlnTvjtbTQA00wec/edit#heading=h.5h6usohk6neg as a start doesnt feel like a Frequently Asked Questions at all, but personal questions torward the code, in which I could probably invest 10 hours or more explaining everything. Who is the audience?

Documenting all in code is difficult because a specific file in source code is only one part of a larger system. The wiki and FAQ address higher level concepts which link to specific implementations in source.

If I have questions after looking at docs AND code then other people might have the same questions. As the questions are answered I am curating the FAQ to small answers with links to wiki and--as discussed--our goal is that the wiki links to github source code.

The diagrams are incomplete as we just started discussing this. It will take some time to flesh those out especially since I am still understanding the workflows and using the FAQ process to do so which takes time as well.

I think I can grant public access to edit the diagrams but that seems like a bad idea given that I am posting the link to this public forum. I'm open to using a different diagramming tool to make collaboration easier. (cryptpad.fr seems lacking in drawing features. perhaps draw.io or lucidcharts?)