ug: offline-update: Add info on bundle signing #702
Conversation
|
Docs for b406c3b are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2648/docs/artifacts/html/index.html |
There was a problem hiding this comment.
I commented a lot about terms and standardization, but I know some of them are already on the page, some are not, and only greping the source code may not be enough to determine whether a term exists.
Other than that, I don't have any comments. The terms confused me a bit, but I think it's because reviewing a text differs from learning from it. So, feel free to ignore my comments.
| It is essential to sign the bundle using one or more TUF targets role keys. | ||
| This ensures the authenticity of an offline update bundle during the update process on a device. | ||
|
|
||
| If the bundle contains CI targets, it is signed by the OTA Lite service using the online TUF targets role key. |
There was a problem hiding this comment.
"online TUF targets role key"
is it role or root?
I'm also confused by the difference between "CI targets" and "TUF targets", would it be Targets? or the general use of target?
There was a problem hiding this comment.
"online TUF targets role key"
is it role or root?
It is a role.
There was a problem hiding this comment.
I'm also confused by the difference between "CI targets" and "TUF targets", would it be Targets? or the general use of target?
"TUF targets role" means the "targets role" as it is defined in the TUF specification.
"CI targets" - can refer either to artifacts produced by a CI build (apps or ostree-repo/commit/fs) or to metadata (json) that refers to these artifacts.
There was a problem hiding this comment.
I guess we already have a link to CI Targets & Production Targets & TUF signing somewhere on this page.
If any of the above is missing, it makes sense to wrap some of the phrases in these new paragraphs into such a link(s).
That would allow a user interested in definitions to find these elsewhere.
| If the bundle contains CI targets, it is signed by the OTA Lite service using the online TUF targets role key. | ||
| Users do not need to take any action in this scenario. | ||
|
|
||
| If the bundle contains production or wave targets, it should be signed using one or more TUF targets offline keys. |
There was a problem hiding this comment.
so, it looks like "production", "wave", "CI" and "TUF" are adjectives for "targets". Would it be the branches they are from? or a propriety?
I think I understand what is said, but I'm trying to avoid creating new terms. If we use "CI Target," then we need to think about having a glossary to explain what exactly a "CI Target" is, but if it happens to be a Target built by CI, it's not a term.
There was a problem hiding this comment.
"CI Target" is, but if it happens to be a Target built by CI, it's not a term.
It is something that is built by CI and can be deployed to devices.
"wave target" - the target to which a given wave refer to.
"production target" - the target that can be deployed only to production devices.
CI build produces "CI target", then a user can make it "wave target" through the "fioctl waves init" command. Once a wave is complete all its targets become "production targets".
"TUF targets" or "TUF targets role" refers to TUF metadata as is defined in https://github.com/theupdateframework/specification/blob/master/tuf-spec.md#targets-role--targets.
There was a problem hiding this comment.
those pages are really complex and I'm not sure they belong to user guide, but at least we are using the same terms, only need to make sure there is a link to the external glossary.
regarding the CI target. Everything is a CI target, until it becomes a wave target or a production target.
Anyway, as I said, all those pages (not only the one in this PR) should be reviewed in the future to try to clean/organize them better. They are starting to become too dense for a user guide, and I think they deserve to go to reference manual. Anyway, it's a future work.
|
|
||
| If the bundle contains production or wave targets, it should be signed using one or more TUF targets offline keys. | ||
| Use ``fioctl targets offline-update sign <bundle-path> --keys <path-to-targets-keys-file>`` command to sign the bundle. | ||
| The number of required signatures is determined by the threshold set in the latest TUF root role metadata, |
There was a problem hiding this comment.
now it's "TUF root role", maybe this is really a new term into the Glossary
There was a problem hiding this comment.
"TUF root role" - The root role as it is defined in the TUF spec.
Add information about signing of the offline update bundle. Specifically, how to do it, and what errors to expect if the signature is invalid. Signed-off-by: Mike Sul <mike.sul@foundries.io>
mike-sul
force-pushed
the
offline-update-bundle-signing
branch
from
b406c3b
to
f460a3e
Compare
|
Docs for f460a3e are browsable at: https://ci.foundries.io/projects/fio-docs/builds/2650/docs/artifacts/html/index.html |
Add information about signing of the offline update bundle. Specifically, how to do it, and what errors to expect if the signature is invalid.
PR Template and Checklist
Please complete as much as possible to speed up the reviewing process.
Readiness and adding reviewers as appropriate is required.
All PRs should be reviewed by a technical writer/documentation team and a peer.
If effecting customers—which is a majority of content changes—a member of Customer Success must also review.
Readiness
Overview
Why merge this PR? What does it solve?
Checklist
make linkcheck.-s, --signoff).-S, --gpg-sign).Comments
Any thing else that a maintainer/reviewer should know.
This could include potential issues, rational for approach, etc.