diff --git a/README.md b/README.md index 9bf40d70..3c81e553 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,10 @@ see [How to build an Update](./docs/build-an-update.md) for producing that content in the first place. Then follow the [updates](./docs/updates.md) guide for setting this up. +## The Update Framework (TUF) +The update server uses TUF to secure the delivery of update manifests. See +[How TUF Works](./docs/tuf.md) for details. + ## API access Follow the [API](./docs/api.md) to learn how to access and use the REST API. diff --git a/docs/build-an-update.md b/docs/build-an-update.md index 36c09ff4..ff517417 100644 --- a/docs/build-an-update.md +++ b/docs/build-an-update.md @@ -36,6 +36,12 @@ identifies this build: > The first time you build, its recommended to set H_BUILD to your latest > FoundriesFactory target number and add 1. +Next, build lmp-device-register to point at this update server: +``` +echo LMP_DEVICE_API = "https:///v1/devices" >> conf/local.conf +echo LMP_OAUTH_API = "https:///oauth2" >> conf/local.conf +``` + Now build: ``` diff --git a/docs/tuf.md b/docs/tuf.md new file mode 100644 index 00000000..3d3c9d3c --- /dev/null +++ b/docs/tuf.md @@ -0,0 +1,55 @@ +# How TUF Works + +The update server leverages TUF to ensure secure OTA delivery. If you +are unfamiliar with TUF, you can learn more from this +[overview](https://theupdateframework.io/docs/overview/). + +> [!NOTE] +> The [Quick Start](./quick-start.md) shares how to initialize TUF keys +> and metadata. + +Every key generated and used by the update server is encrypted with an +HMAC key. Access to the HMAC key is required for using each of the "online" +keys: Timestamp, Snapshot, and Targets. + +## Root Role + +The update server uses a single Root key under `/tuf/keys/root.key`. +You **must never lose** this key. +A loss of a Root key and/or the HMAC key would make it impossible to add new keys; +in which case there will be no way to sign new Updates after a Root role expires. + +The root role is valid for 20 years (root.json's `signed.expires` attribute). + +> [!WARNING] +> Backup `/tuf/keys/root.key` **and** `/auth/hmac.secret` to +> multiple places including [AWS Secret Manager](https://docs.aws.amazon.com/secretsmanager/), +> and a physical copy on paper stored in a safe. + +You can remove this key from the server once it's been backed up. It is +considered an "offline" key and is not required by the update server for +normal operations. + +## Timestamp Role + +The update server uses a single Timestamp key under `/tuf/keys/timestamp.key`. +Each Update has its own timestamp.json file. This file is signed with a +1-week expiration value. There is a background task running every 4 hours +that will refresh timestamps expiring in the next 24 hours. + +## Snapshot Role + +The update server uses a single Snapshot key under `/tuf/keys/snapshot.key`. +Each Update has its own snapshot.json file. This file is signed with a +expiration value that matches the Targets expiration. + +## Targets Role + +The update server uses a single Targets key under `/tuf/keys/targets.key`. +This key is used during Update creation to sign the generated targets.json +metadata. The metadata is signed with a 90-day expiration. See +[Updates](./updates.md) for more details. + +The Snapshot and Targets expiration values are not automatically refreshed. +It is up to the operator to keep these values fresh for Updates used over +90 days.