Faq refresh

[jtmoree-github-com]

This is a separate pull request because many of the QUESTIONS are unanswered. I hope we can answer the as part of the review of this change. At the very least we can add these questions to the FAQ without answers as some of the others on it also do not have answers yet.

tlaurion edit: Please review https://github.com/osresearch/heads-wiki/issues/25#issuecomment-773485007 and discuss there prior of making this PR go any further.

[tlaurion]

Ok, this becomes practical and I like it. What is the path we take here.

I explain in code, linking to where things are happening from latest commit, in blame mode, so that people see where the code entry happens in links? Should we go with screenshots of gui-init, showing HOTP/TOTP codes, and point to where the calculations are made, where the TOTP/HOTP measurements are used in seal unseal operations?

My biggest challenge, personally, is to switch from the code and documentation perspective. So another approach could be to link the commit to the PR so that custious people could still come to PR for deeper explanations that lead to the FAQ entree?

I need some guidance on creating documentation. This is really, really not my realm.

[Thrilleratplay]

@tlaurion

link the commit to the PR so that curious people could still come to PR for deeper explanations that lead to the FAQ entree?

This is something I think will break down over time. Bug fixes, code clean up, additional features added to the same part of code, the linked PR would not resemble what is currently in the master branch, linking multiple commits would be messy and confusing.

Keep in mind who these "curious" are. Anyone who is legitimately going to review it would be other developers or those who technical enough to follow through fragments of code. Personally, the general wiki should focus on the end users, the developer section could benefit from linking directly to the code. Although, keeping all of that up to date would be challenging. The only thing that comes to mind is a javadoc equivalent for bash, something like shdoc. Where the annotations in the code can generate documentation. This is a much larger undertaking.

[jtmoree-github-com]

I agree with Thrilleratplay that wiki docs are aimed at end users. Even devs have to start with a basic understanding. Reading Code is a slow way to understand how all of the various utilities SHOULD work together even if it details how they DO work together. If we link end user docs to source (maybe not PRs) it allows devs to more quickly dig into the components they are most interested in modifying.

[jtmoree-github-com]

Shall I convert this to draft PR and we work through some questions in this thread or can we approve this PR and fill in the answers later?

[tlaurion]

Draft. No need to push empty questions/answers.

[tlaurion]

My main question would be : Are those really Frequently asked questions? What about answering past documented questions and answers in past issues instead of creating new questions?

[tlaurion]

@jtmoree-github-com

Here is a starter for past QA that should be turned into FAQ and point even to issues instead of redoing everything. If things needs to be more clarified, then diagrams and documentation in code, while FAQ should be aimed at onboarding users and developers with entry points into code. The end user wants to understand grossly what happens from hitting the power button to when booting the OS, while knowing what is actionnable and where.

We also try to move users into using gui-init instead of generic-init which was a PoC, prior of having USB dependencies (HOTP) and mounting external devices (which requires also loading kernel modules which modified PCR5).

So if the user wants to have a working system, gui-init should be better understood, and the user has to understand that going into recovery invalidates measurements and secret. That was documented https://github.com/osresearch/heads/issues/639 and partly at some other place. If this is still unclear, let me know and I will find other discussions that happened on those subjects.

I think the first step of everything is to detail more https://github.com/osresearch/heads-wiki/issues/25#issuecomment-773485007 if not precise enough. Editing OP.

• https://github.com/osresearch/heads/issues?q=+is%3Aissue+label%3Adocumentation+
• https://github.com/osresearch/heads/issues?q=is%3Aissue+label%3Aquestion

[tlaurion]

Really interesting post, on which we might come with smaller PRs with differences material.

Measured boot != Secure boot != Verified boot https://igor-blue.github.io/2021/02/04/secure-boot.html