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.

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

Docs refresh of OS install #66

Closed

Conversation

jtmoree-github-com
Copy link
Contributor

re-organized OS installations. Add PUREOS. split qubes and generic into separate pages. update and clarify generic instructions.

* move OS installs into subfolder
* move qubes and generic installs to separate files
* re-org and expand Generic OS install
* add install for PureOS
* move prereqs to separate page
* add overview to index page
@jtmoree-github-com
Copy link
Contributor Author

media before using it. Check your ISO downloads against the signatures
provided by vendors.

### Alternative Options
Copy link
Collaborator

Choose a reason for hiding this comment

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

this text refers to booting to verified ISOs with the link you posted in previous section For certian OSes,

The upper section is the non secure boot, where media could be tampered with and booted into without verification. Here, the distro signing keys are in the ROM, and are used to verify detached signed iso.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

WIP I reworded a little based on what I think you are saying but please review. I'm not sure I fully grasp all of the aspects on this. Will push in a few minutes with everything else on this PR.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I reworked this again after review. I think I see how I was confused. I also moved the content up to the index page rather than in the Generic OS page. There was duplicate content on both pages.


### Using TPM for decryption of drives

You may seal your Disk Unlock Key using the TPM allowing you to use ensure only a boot passphrase and the proper PCR state can access the disk.
Copy link
Collaborator

Choose a reason for hiding this comment

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

You may release a Disk Unlock Key by the TPM by setting a default boot option and asking to change the changes to disk, while accepting to setup a Disk Unlock Key passphrase.

This passphrase will release the Disk Unlock Key to unlock LUKs on its second slot, if the measurements in PCRs are matching the ones when setting up the Disk Unlock Key for that boot option. This is the most secured option, since going into recovery will modify the PCR, having different kernel modules will invalidaate the measurements. The TPM will release the Disk Unlock key only if the measurements are coherent and if provided with the TPM NV space defined passphrase (The Disk Unlock Key passphrase), and rate limits attempts, preventing bruteforce. Consequently, someone cloning drive and trying to unlock drive with eavesdropped passphrase will fail, this passphrase being only valid on your laptop with your firmware and measured files...

This comment was marked as outdated.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

having different kernel modules will invalidaate the measurements.

Is this just the files in /boot or does heads measure any currently running modules?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I pushed a new version of this section but github says my latest commits dont belong to any branch in this repo--which makes no sense to me. Will let you know when I figure out what is going on. 9b569ff

Copy link
Contributor Author

Choose a reason for hiding this comment

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

This was also reworked and moved to OS/index where there was a duplicate section on TPM disk key.

Installing-and-Configuring/OS/Generic.md Outdated Show resolved Hide resolved
Installing-and-Configuring/OS/PureOS.md Outdated Show resolved Hide resolved
Installing-and-Configuring/OS/PureOS.md Outdated Show resolved Hide resolved
Installing-and-Configuring/RecoveryShell.md Outdated Show resolved Hide resolved
Installing-and-Configuring/RecoveryShell.md Outdated Show resolved Hide resolved
encryption key. Be sure you have your TPM owner's password and your
disk encryption recovery key or passphrase available since, by design,
the disk key is not accessible to the recovery shell.
This will require generating a new TPM TOTP token. If you stored the decryption key for your drive in the TPM it will be lost. Be sure you have your TPM owner's password and your disk encryption recovery key or passphrase available since the disk key is not accessible to the recovery shell. This is by design.
Copy link
Collaborator

@tlaurion tlaurion Feb 11, 2021

Choose a reason for hiding this comment

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

Disk Unlock Key will need to be renewed since not valid in TPM NV memory space. Reseal HOTP/TOTP, sign /boot and setup a new boot default and you will be good to go.
Do it from the menus. not the shell.

Please remove fear langage and replace by proper instructions on what should be done, not what should not be done.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

WIP reworded. will be pushed in a few minutes.

Copy link
Collaborator

Choose a reason for hiding this comment

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

Disk Recovery Key is the key that was setuped at OS installation with relative passphrase, this setuped slot 0.

Disk Unlock Key was setuped randomly in Heads when setuping a boot default on boards having a TPM and not having deactivated the option in board config. The Disk Unlock Key passphrase unseals the TPM Disk Unlock Key if NV regions Disk Unlock Key passphrase is valid and measurements are coherent with same modules and measured content in PCRs then when the secret was sealed.

The user can setup and change the Disk Unlock Key passphrase but setting a new boot default anytime, and providing Disk Recovery Key passphrase, new Disk Unlock Key passphrase and typing GPG User PIN to detach sign new boot config.

That process should be redo everytime boot content is changed. Meaning the user should reboot after updating dom0 under Qubesos or OS under monolitic OSes to attest boot related changes ( kernel initrd xen grub)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

reworded to use original text with a few clarifications and consistent terminology

Installing-and-Configuring/Upgrading.md Outdated Show resolved Hide resolved
Installing-and-Configuring/Upgrading.md Outdated Show resolved Hide resolved
@jtmoree-github-com jtmoree-github-com marked this pull request as draft February 15, 2021 16:36
- separate boot options from generic OS guide
linuxboot#66
- update TPM section
- move some generic info that was duplicate to OS/index
- clarify ISO signature boot process
@tlaurion
Copy link
Collaborator

@jtmoree-github-com I will repass on all the text and propose direct textual changes replacement for each changes, otherwise I don't know how to handle those PRs.

@jtmoree-github-com
Copy link
Contributor Author

@jtmoree-github-com I will repass on all the text and propose direct textual changes replacement for each changes, otherwise I don't know how to handle those PRs.

Please do.

Comment on lines 69 to 73
If there is no persistent `kexec_menu.txt`, the boot directory will be searched
for grub/syslinux-like configurations and it will be generated dynamicly (for
any of the HD/USB/USB-ISO locations). Creating a persistent
`kexec_menu.txt` can be useful to limit the options displayed or to make
persistent alterations to xen or kernel params.
Copy link
Collaborator

Choose a reason for hiding this comment

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

If there is no persistent kexec_menu.txt generated from GUI menu option Default boot while /boot content detached signed digest is verified as valid, the boot directory will be searched
for grub/syslinux-like configurations and it will be generated dynamically (for
any of the HD/USB/USB-ISO locations). Creating a persistent
kexec_menu.txt can be useful to limit the options displayed or to make
persistent alterations to xen or kernel params.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

incorporated new content but separated into two sentences. Will push in a few minutes.


heads currently requires a separate boot partition which is a common configuration for Linux. The heads model leaves the /boot partition unencrypted. This is safe because heads will verify files at boot to detect tampering.

When you partition storage make sure to create /boot or have the OS installer do it for you. Generally, the boot partition is much smaller than the other OS partition(s). You may keep everything else on 1 partition to make it easier to manage but the kernel and initrd on the boot partition can mount any number of others--encrypted or not.
Copy link
Collaborator

Choose a reason for hiding this comment

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

You may keep everything else on one additional partition to make it easier to manage, but the kernel and initrd is required to be under the seperated boot partition. Linux initrd will normally have the ability to mount the other partitions--encrypted or not.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

reworded. I had a typo in the original text which made it confusing. I combined your text with mine. push in a few...

Installing-and-Configuring/OS/index.md Outdated Show resolved Hide resolved
Installing-and-Configuring/OS/index.md Outdated Show resolved Hide resolved
Installing-and-Configuring/OS/index.md Outdated Show resolved Hide resolved
Installing-and-Configuring/OS/index.md Outdated Show resolved Hide resolved
@@ -79,17 +79,34 @@ This feature may be turned off during configuration of heads. The following wil

### Using only a LUKS passphrase

In this model heads is not responsible for any of the encryption of data on disk. The linux kernel decrypts and mounts LUKS containers by asking the user for a passphrase. The correct passphrases allows boot to finish.
In this model heads is not responsible for any of the decryption of data on disk. The linux kernel decrypts and mounts LUKS containers by asking the user for a passphrase. The correct passphrases allows boot to finish.
Copy link
Collaborator

Choose a reason for hiding this comment

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

In this model heads is not responsible for any of the decryption of data on disk. The linux kernel decrypts and mounts LUKS containers by asking the user for a passphrase. The correct passphrases allows boot to finish.

WRONG

Under the previous Disk Unlock Key scenario, Heads is not responsible to unlock Disk Unlock Key. It actually creates an additional initrd file pushed to QubesOS so that the OS is using that key to decrypt content without further user interaction.

In the Disk Recovery Key scenario, Heads doesn't attempt to release the Disk Unlock Key. It simply relies on OS mechanisms to prompt the user for the Disk Recovery Key passphrase at standard OS prompt.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

WIP

I would argue that since heads creates the key and initrd which is used by Qubes to decrypt data that heads is responsible even though it doesn't do the decryption step itself. What if I add a section for Disk REcovery Key and rephrase this section ?

push in a minute

Copy link
Contributor Author

Choose a reason for hiding this comment

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

This has been rewritten and needs review. I'm not certain what exactly was WRONG with the first draft. It now starts at line 86 in OS/index

Installing-and-Configuring/OS/index.md Outdated Show resolved Hide resolved
@tlaurion
Copy link
Collaborator

tlaurion commented Apr 6, 2021

@jtmoree-github-com rest is without comment, liking it. For future PR, please keep scope smaller. As we can see here with 92 comments, this is becoming complicated and would not even know if Heads community would agree with proposed changeset/commit log, having been refused merge for less then that. For sure, nobody else will review.. And there is where the problem lies.

I personally have no problem for the changelog (even less in the heads-wiki) but preferably, a change should be targeting only one feature or required change for a feature/point, limiting the number of files targeted and more importantly, the number of commits linked to the change. This is now targeting 13 files. Nobody else will review this i'm pretty sure. Changes NEED to be smaller, that is for sure. As of right now, If I was merging this as is, it would be all 22 commits in this PR, Developers don't like this. Normally, developers like to see one commit per file/feature. Personally, I do not know how to handle properly documentation change, and have nothing against giving you ownership of the changes (otherwise, I would have to "squash" the changes, giving me ownership of the changes, linking to this PR. In the developer world, squashing gives credit to the merger, not the commiter. I do not mind, where Heeads community developers have insisted many times that commit logs should be the smallest possible. But hat removes the trace of commits linked to editions. I would permit this this time, since its documentatio nand not code contribution, but would not permit this in the future., this case being used as a reference of why this is not working).

For next documentation changes, I would suggest cryptpad/riseup pad (ethereal) so changes are more dynamic and only the consequences results into a PR.

https://pad.riseup.net/ would be a good place to discuss changeset on specific files (22 commits? Really? (I hear others staying) ). Free, spontaneous. Anonymous. Then the result could be from you, claiming ownership for the changes, which I would not have anything against.

@kylerankin
Copy link
Collaborator

kylerankin commented Apr 6, 2021 via email

@tlaurion
Copy link
Collaborator

tlaurion commented Apr 6, 2021

@jtmoree-github-com following @kylerankin comment #66 (comment) please link to documentation and delete everything else. I think we made ourselves clear multiple times in this PR discussions.

@jtmoree-github-com
Copy link
Contributor Author

heads is responsible for booting operating systems. As such, documentation that discusses operating systems and how heads may or may not be involved is in scope of heads. I am perfectly happy to create pages outside of the heads wiki with this content and link to it. That will take some time. I will push updates when that is done.

SPECIFICALLY. The objection seems to be that heads should document NONE of the OS components? To that end I will remove almost all of the content on the OS index page, the PureOS page, and leave the Generic and Qubes pages which are based on the current wiki.

@jtmoree-github-com
Copy link
Contributor Author

We have both stated that a PR is a poor place to manage changes to documentation. In the future I will use https://pad.riseup.net/ to collaborate.

@tlaurion
Copy link
Collaborator

tlaurion commented Apr 7, 2021

heads is responsible for booting operating systems. As such, documentation that discusses operating systems and how heads may or may not be involved is in scope of heads. I am perfectly happy to create pages outside of the heads wiki with this content and link to it. That will take some time. I will push updates when that is done.

SPECIFICALLY. The objection seems to be that heads should document NONE of the OS components? To that end I will remove almost all of the content on the OS index page, the PureOS page, and leave the Generic and Qubes pages which are based on the current wiki.

@jtmoree-github-com I'm not sure how to properly give better direction.

The original articles inside of Heads wiki were aimed at differences in ways different Linux Operating Systems needed some tweaking depending on certain Linux flavors to properly boot. Those generic advice are in the scope of what Heads should give in the scope of user documentation, in my opinion. The best example of that is how different Linux flavor require different options to be able to boot from ISO. This is relevant to Heads, since those tweaks may need to be added to be able to properly boot the desired operating system. The same applies to the ways LUKS keys need to be passed to OS, which varies from QubesOS (fedora base) from a debian base. Differences in how to properly install guix with a seperate /boot partition would be welcome, for example, since guix considers having everything under /, which Heads doesn't play with, since it requires a distinct /boot partition. That fact is relevant for Heads. Having screen captures for all different operating systems isn't.

Covering in details some operating system installation opens the door for other PRs to be proposed by users wanting other OS being documented, and the goal of the docs is to be as minimal possible, to pass the buck to Operating Systems installation instructions where necessary, only specifying the changes that applies when using Heads.

In my opinion, general instructions, as for the QubesOS instructions, were aimed at creating originally a different partitioning scheme in the goal of having QubesOS installation mostly in read only, where dmverity could be used inside of Heads to measure the disk content in between templates upgrades, but that never happened officially. The idea was there, the documentation was partial, waiting for upstream changes that never happened. The QubesOS installation page was then kept, but the perks leading to those required perks were removed, leaving the guide with instructions.... which actually guide the user through a normal installation. I personally do not see any added value into having this inside of the documentation. But this is only my opinion. In this case, like others, those documentation pages require changes over time, which most of the time are not done in time and become deprecated. This is why minimal, required, user documentation, seems to be the best fit for Heads project.

I would disagree about removing everything and my goal here is not to discourage contributions. But the scope needs to be more limited for next PRs. Adding X and having only X in a PR, where limited files being touched by a PR in the scope of X. I think that the removal of other pages should be in another PR. Collaboration can also happens inside of the heads slack channel.

I prefer personally to discuss changes that are planned to be done in issues, then once agreement there, create related PR which closes an issue. If there is matter for debate, or uncertainty, that debate/discussion should happen over slack.

I like etherpad for drafting and direct collaboration.

@jtmoree-github-com following @kylerankin comment #66 (comment) please link to documentation and delete everything else. I think we made ourselves clear multiple times in this PR discussions.

My comment here was not to delete everything. But following kyle replies (2), there is disagreement also from his side of documenting what should be documented on their website. Maybe what is missing should be included in an issue? We tend to like things being fixed upstream instead of patching what will need to be removed later on.

@jtmoree-github-com
Copy link
Contributor Author

@tlaurion @kylerankin I just reviewed the official PureOS install guide (linked in this PR) and docs.puri.sm. Neither addresses installation of PureOS while using heads. PureOS install guide doesn't mention heads/Pureboot and Pureboot instructions ignore installation of PureOS (assuming due to factory installation). I have attempted to get Purism to improve content within those resources and will continue to do so.
In the mean time the PureOS page in this PR has

  1. content not available anywhere else
  2. information specific to heads and installing PureOS
  3. NO screenshots or extra information that is out of scope for heads

@jtmoree-github-com
Copy link
Contributor Author

jtmoree-github-com commented Apr 8, 2021

I can understand having documentation that discusses unlocking disks with help from the TPM, as that's a feature that is in Heads. Anything outside of that (unlocking LUKS via normal means, via a smart card, or anything else) seems out of scope for Heads documentation, in my opinion.

This point of view seems to discourage any text/copy/information in the wiki which would compare the use of the heads+TPM for unlocking disk with other methods such as using a smart card. If this is the intention of the heads project I will migrate those comparisons to an external site and reference in the wiki. The OS/index page is where this heads vs other methods content sits in the PR.

Copy link
Collaborator

@tlaurion tlaurion left a comment

Choose a reason for hiding this comment

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

Propositions

Installing-and-Configuring/OS/index.md Outdated Show resolved Hide resolved
Installing-and-Configuring/OS/index.md Outdated Show resolved Hide resolved
Installing-and-Configuring/OS/index.md Outdated Show resolved Hide resolved
Installing-and-Configuring/OS/index.md Outdated Show resolved Hide resolved
Installing-and-Configuring/OS/index.md Outdated Show resolved Hide resolved
Installing-and-Configuring/OS/index.md Outdated Show resolved Hide resolved
@@ -77,9 +83,11 @@ This feature may be turned off during configuration of heads. The following wil
CONFIG_TPM_NO_LUKS_DISK_UNLOCK=y


### Using only a LUKS passphrase
### Using the LUKS Disk Recovery Key / Using only a LUKS passphrase
Copy link
Collaborator

@tlaurion tlaurion Apr 9, 2021

Choose a reason for hiding this comment

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

Not sure I understand this title.
LUKS Disk Recovery Key results from LUKS OS prompted passphrase at OS installation. What is Using only a LUKS passphrase?

OS defined LUKS Key passphrase = Disk Recovery Key passphrase.
OS defined Key = Disk Recovery Key

Copy link
Contributor Author

Choose a reason for hiding this comment

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

WIP
This section was originally stating that the user can have heads ignore the disk encryption. Then it became a combination of that and the disk recovery key scenario because--as you pointed out--they are the same process.

I understand that the new heading has made this confusing which I think has led to repeating information. The propositions in the next two sections can be integrated into the sections above (with links) or we can ignore them as repeated information. I will ignore them and separate the two different workflows again for my next commit. In addition, I have added (not heads) to appropriate headings to clarify.

I understand that this section has been the most difficult to collaborate on and the source of much frustration but it is important for the intent of this page which is to show how heads may or may not be involved in OS bootup using different methods of LUKS decryption. If the heads project does not want these two (not heads) sections to be in the wiki I will move them to an external site. This could also apply to the section 'Security Dongle Vs TPM. IMHO they all fit into this larger context of heads handoff to OS for decryption.

### Using only a LUKS passphrase
### Using the LUKS Disk Recovery Key / Using only a LUKS passphrase

In this model heads is not involved in processes related to the decryption of data on disk. The OS manages keys and access to the LUKS containers by asking the user for a passphrase on boot.
Copy link
Collaborator

Choose a reason for hiding this comment

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

In this model heads is not involved in processes related to the decryption of data on disk. The OS manages keys and access to the LUKS containers by asking the user for a passphrase on boot.

Technical clarification here, as clarified in counter proposition to your text block above. Pick, but do not modify. I feel we have been through this multiple times which is why i'm now linking in code. I do not see the point in documenting wrongly what is in code. So let's try by another angle here again:

The Disk unlock Key, per se, is generated under Heads from random number generator to create a 128 characters key at the moment of renewing/changing Disk Unlock Key and Disk Unlock Key passphrase upon requirement of defining a new boot default when /boot integrity changed, which changes happens at core OS upgrades (under Qubes, when updating dom0 hyperviser boot related files, being Xen, kernel, initrd and grub config. Other Operating Systems could change those files at any automatic upgrade, so inspecting the upgrade log and rebooting accordingly is advised.)

This randomized key is used to generate LUKS slot1 key, injecting it by having the right Disk Recovery Key passphrase to unlock the LUKS container.
Then, that key is sealed under TPM nv memory

Installing-and-Configuring/OS/index.md Outdated Show resolved Hide resolved
@jtmoree-github-com
Copy link
Contributor Author

I split the changes into two groups. The OS portions are the ones we have had the most 'challenges'. To that end I created a new branch that excludes those changes. You can see what would be pulled into a PR here master...jtmoree-github-com:docs-refresh2.

I did not create a PR because we have no agreement on how to merge these changes. I offer this as another approach. If we can get that merged I will then do the same for the OS folder which also replaces install-os.md.

Copy link
Collaborator

@tlaurion tlaurion left a comment

Choose a reason for hiding this comment

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

corrections

@tlaurion
Copy link
Collaborator

@jtmoree-github-com There is a lot of repetition under current documentation, since I explained on the spot each things that were invalid in individual text changes in the past 25 commits.

I see you opened another branch #66 (comment)

My concerns were about information being technically right. I think we are at that point now. But the content is long and repetitive, not sure users would read it all.

What are the next steps here/there? Please tag me in, else I do not automatically see where PR are updated.

@jtmoree-github-com
Copy link
Contributor Author

@tlaurion I made the outstanding changes. I made a second branch to clean up the commit history.

Where to go from here depends on how much cleaning we want. We can merge this branch but it's a mess of multiple edits on edits. If we merge the other 'clean' branch then I will create another one with just the OS sections that is also cleaner.

jtmoree-github-com added a commit to jtmoree-github-com/heads-wiki that referenced this pull request Aug 3, 2021
- based on work in PR 66 which now has conflicts
linuxboot#66
- re-org OS pages to use subfolder
- add pureOS page with current info not on Purism site
- change link to OS page in parent index
@jtmoree-github-com
Copy link
Contributor Author

Closing this PR as it was messy and split into two other branches. The first replacement was merged as PR 67 and the second is in the works.

@jtmoree-github-com jtmoree-github-com mentioned this pull request Aug 3, 2021
@jtmoree-github-com jtmoree-github-com deleted the docs-refresh branch September 29, 2021 03:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants