This repository has been archived by the owner on May 21, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 61
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1752 from advancedtelematic/feat/prep-2020.9
Feat/prep 2020.9
- Loading branch information
Showing
15 changed files
with
200 additions
and
40 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,6 @@ | ||
| name: ota-client | ||
| title: OTA Connect Developer Guide | ||
| version: latest | ||
| display_version: 2020.8 (latest) | ||
| display_version: 2020.9 (latest) | ||
| nav: | ||
| - modules/ROOT/nav.adoc |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
58 changes: 58 additions & 0 deletions
58
docs/ota-client-guide/modules/ROOT/pages/change-signature-thresholds.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| = Change signature thresholds | ||
| ifdef::env-github[] | ||
|
|
||
| [NOTE] | ||
| ==== | ||
| We recommend that you link:https://docs.ota.here.com/ota-client/latest/{docname}.html[view this article in our documentation portal]. Not all of our articles render correctly in GitHub. | ||
| ==== | ||
| endif::[] | ||
|
|
||
| One way you can keep your software repository more secure is by adding extra signing keys, and then setting up *key thresholds* to require metadata to be signed by multiple different keys. By default, each role on the repository has one signing key and a threshold of one. For more security in the Root role, for example, you might want to create 5 different keys, keep them locked up at different locations around the world, and require that at least three of the keys sign off on any change to Root metadata. You can also use key thresholds for delegations. | ||
|
|
||
| *To change the thresholds for signing Root metadata:* | ||
|
|
||
| . Generate a new Root key. | ||
| + | ||
| [source,bash] | ||
| ---- | ||
| garage-sign key generate --repo <localreponame> --name root-key-1 --type rsa | ||
| ---- | ||
|
|
||
| . Add the new Root key to the `root.json` file. | ||
| + | ||
| [source,bash] | ||
| ---- | ||
| garage-sign root key add --repo <localreponame> --key-name </path/to/public-root-key-1> | ||
| ---- | ||
|
|
||
| . If you need more Root keys, repeat steps 1 and 2. | ||
| . In the *Roles* folder of your local software repository, open the *Unsigned* folder, and then open the `root.json` file. | ||
| . Depending on the threshold that you want to change, in the `signed` block, in the `root` subsection, for the `keyids` object, specify the list of valid keys that you want to use for signing. | ||
| + | ||
| You can find the list of all your Root keys in the `keys` subsection. | ||
| + | ||
| NOTE: The new version of Root metadata should be valid according to the rules of the previous and current versions. So you must sign Root metadata with the threshold of keys specified in the previous Root metadata file and the threshold of keys specified in the new Root metadata file. For more information, see the https://uptane.github.io/papers/uptane-standard.1.0.1.html#rfc.section.5.4.4.3[related section] of the Uptane standard. | ||
|
|
||
| . For the `version` object, specify the version number of the new Root metadata. | ||
| . Sign the `root.json` file with the same number of valid signatures that you specified in the Root key threshold. | ||
| + | ||
| [source,bash] | ||
| ---- | ||
| garage-sign root sign \ | ||
| --repo <localreponame> \ | ||
| -k </path/to/public-root-key-1> \ | ||
| -k </path/to/public-root-key-2> \ | ||
| --expires <root-metadata-expiry-date> | ||
| ---- | ||
|
|
||
| . Push the modified `root.json` file to OTA Connect. | ||
| + | ||
| [source,bash] | ||
| ---- | ||
| garage-sign root push \ | ||
| --repo <localreponame> | ||
| ---- | ||
|
|
||
| To change the threshold of delegations, modify the .json file with the delegation metadata in the same way as the `root.json` file. | ||
|
|
||
| To learn more about the `garage-sign` commands and options, see its xref:garage-sign-reference.adoc[reference] documentation. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
31 changes: 31 additions & 0 deletions
31
docs/ota-client-guide/modules/ROOT/pages/keep-local-repo-on-external-storage.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| = Keep your repository on external storage | ||
| ifdef::env-github[] | ||
|
|
||
| [NOTE] | ||
| ==== | ||
| We recommend that you link:https://docs.ota.here.com/ota-client/latest/{docname}.html[view this article in our documentation portal]. Not all of our articles render correctly in GitHub. | ||
| ==== | ||
| endif::[] | ||
|
|
||
| Your software repository contains information on your software images and packages, as well as your Root and Targets keys. | ||
| For safety reasons, we recommend keeping your keys offline on an external storage device, and for convenience, we recommend to simply keep the entire repository structure (with the keys included) on external storage. This external device should be kept offline, in a securely locked location, and only plugged into a computer when you need to make changes to the repository. | ||
|
|
||
| *To get a copy of a software repository on external storage:* | ||
|
|
||
| . Connect the external storage to your computer. | ||
| . Make sure you have the link:https://tuf-cli-releases.ota.here.com/index.html[latest version,window="_blank"] of the `garage-sign` tool. | ||
| . Get the .zip file with your provisioning credentials and save it to your external storage. | ||
| + | ||
| For instructions, see the xref:ota-client::generating-provisioning-credentials.adoc[related] section in this guide. | ||
| . In the folder of your external storage, initialize a local repository. | ||
| + | ||
| [source, bash] | ||
| ---- | ||
| garage-sign init \ | ||
| --repo <localreponame> \ | ||
| --credentials </path/to/credentials.zip> | ||
| ---- | ||
|
|
||
| Work with your local repository only on the external storage. | ||
|
|
||
| To learn more about the `garage-sign` commands and options, see its xref:garage-sign-reference.adoc[reference] documentation. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
38 changes: 38 additions & 0 deletions
38
docs/ota-client-guide/modules/ROOT/pages/remove-sw-version.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| = Remove a software version | ||
| ifdef::env-github[] | ||
|
|
||
| [NOTE] | ||
| ==== | ||
| We recommend that you link:https://docs.ota.here.com/ota-client/latest/{docname}.html[view this article in our documentation portal]. Not all of our articles render correctly in GitHub. | ||
| ==== | ||
| endif::[] | ||
|
|
||
| To remove a software version, you need to delete a target in the Targets metadata file. | ||
| include::garage-sign-reference.adoc[tags=target-term] | ||
|
|
||
| Once you delete a target, you can no longer install it on devices. | ||
|
|
||
| *To delete a target:* | ||
|
|
||
| include::upload-large-binary.adoc[tags=gs-initialize] | ||
|
|
||
| include::upload-large-binary.adoc[tags=gs-pull-targets] | ||
|
|
||
| . To delete the target, depending on the type of image, specify the target name and version in one of the following forms: | ||
|
|
||
| ** For OSTree images, `<name>_<version>` | ||
| ** For binary images, `<name>-<version>` | ||
| + | ||
| [source,bash] | ||
| ---- | ||
| garage-sign targets delete \ | ||
| --filename <name>-<version> | ||
| ---- | ||
|
|
||
| include::upload-large-binary.adoc[tags=gs-sign-targets] | ||
|
|
||
| include::upload-large-binary.adoc[tags=gs-push-targets] | ||
|
|
||
| You can no longer see the deleted software version in your portal software repository. | ||
|
|
||
| To learn more about the `garage-sign` commands and options, see its xref:garage-sign-reference.adoc[reference] documentation. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.