Add custom metadata fields to Targets metadata
You may want to include extra metadata about your software inside the signed Uptane metadata that OTA Connect delivers to your device. Some reasons you might want to do this include:
-
To provide installation instructions or scripts for an image that cannot or should not be included in the image itself.
-
To add extra tracking fields for internal compliance or auditing.
To accommodate this use case, you can manually manage your Uptane metadata and add custom fields to your targets.json
file.
For more information on additional use cases that require customization of the Targets metadata, see the related section of the Uptane standard. |
Prerequisites
Before you write a custom metadata handler, do the following:
-
Build your own update client using libaktualizr.
To learn how to access custom metadata in the embedded client, see the Doxygen API reference.
-
Rotate your signing keys offline.
The following instructions assume that you have already done this, and know where to find your
targets.json
.
Anatomy of the targets.json
metadata
Your targets.json
file includes:
-
The
signatures
block that contains key IDs and signatures generated over thesigned
block. -
The
signed
block that contains the Uptane fields. -
In the
signed
block, thetargets
block that lists all of your software versions.Target is a term from Uptane. Each Target corresponds to a software version available in your OTA Connect software repository.
Each target is identified by its name and version and contains three objects:
-
hashes
– the SHA256 hash of the software version. -
length
– the length of the target, in bytes. -
custom
– other metadata that aktualizr uses.Example 1. Thecustom
object"custom": { "name": "aegisub-font", "version": "1", "hardwareIds": [ "kmk-docker-debian" ], "targetFormat": null, "uri": null, "createdAt": "2018-08-20T09:28:27Z", "updatedAt": "2018-08-20T09:28:27Z" }
You can add your custom metadata to the
custom
object.
-
Add custom metadata
You can always modify your targets.json
file to include more metadata.
To add custom metadata:
-
In the
targets.json
file, navigate to thecustom
object, and specify any metadata fields that you want to add.Do not modify any of the existing values. We recommend to add a new field namespaced to your organization or some other unique identifier, and then put any custom sub-keys under that field, as in the example below.
Example 2. Custom metadata"custom": { "name": "aegisub-font", "version": "1", "hardwareIds": [ "kmk-docker-debian" ], "targetFormat": null, "uri": null, "createdAt": "2018-08-20T09:28:27Z", "updatedAt": "2018-08-20T09:28:27Z", "acme_inc_metadata": { "application_install_handler": "com.dockerconfig.packager", "build_correlation_id": "2ce4ebaf-b3ca-411b-977f-cd6b98065d88" } }
-
Sign the modified metadata.
garage-sign targets sign --repo myimagerepo --key-name mytargets
-
Upload your customized
targets.json
to OTA Connect.garage-sign targets push --repo myimagerepo
If you want to add custom metadata while bitbaking, modify the IMAGE_CMD_garagesign function in image_types_ostree.bbclass. For more information, see the Yocto Reference Manual.
|
To learn more about the garage-sign
commands and options, see its reference documentation.