Manifest tool

The manifest tool makes it easy to create, sign and upload manifests. For more information, please see Installing the manifest tool.

Creating manifests using the manifest tool

The manifest tool creates a manifest using the following sources of information:

1. It parses a JSON input file, which can contain all of the information used to create the manifest.
2. If information is missing from the input file, the manifest tool checks for a file that contains defaults in the current working directory (.manifest_tool.json). The firmware author typically creates this file using manifest-tool init.
3. You can use command-line arguments to override many of the fields the manifest tool uses.

Cryptographical configuration

As Manifests describes, a Device Management Update manifest is a signed document. The manifest tool can perform this signing for you.

Currently, manifests must use SHA256 for hashes, ECDSA signatures on the secp256r1 curve, with no encryption. The manifest tool calls this configuration none-ecc-secp256r1-sha256.

Tip: Future versions of the manifest tool will add support for payload encryption.

Manifest tool operation

In the none-ecc-secp256r1-sha256 encryption mode, the manifest tool creates a signed manifest; the payload is unencrypted. The target device(s) must already have the certificate listed in the manifest, or a way of fetching it.

The manifest tool:

1. Fetches and hashes the payload. The manifest tool loads the payload from a local file.
2. Fetches and fingerprints the certificate from the local file.
3. Creates the inner part of the manifest, containing:
   1. The provided IDs.
   2. The payload URI.
   3. The payload size.
   4. The payload hash.
4. Hashes the inner part of the manifest.
5. Uses the hash and the certificate private key to sign the inner part of the manifest.
6. Wraps the inner part, hash, signature, certificate fingerprint and certificate URI in the outer part of the manifest.

Creating and signing a manifest: summary

The minimum requirements for using the manifest tool to create a manifest with an unencrypted payload are:

• Use the none-ecc-secp256r1-sha256 cryptographic mode.
• Provide the payload URI.
• A certificate for signing the manifest, provided as either a URI or a local file.
• A local file that is the signing key for that certificate.
• One of:
  • The vendor ID and device class ID.
  • The device ID.

For more information about these IDs, see the Update client section.

Uploading a manifest

To upload your manifest, you can use Device Management Portal or the Update service APIs.

The manifest tool provides two convenience commands.

To prepare an update, use manifest-tool update prepare. This:

1. Uploads a firmware to Device Management and retrieves its URI.
2. Creates a manifest for the firmware.
3. Uploads the manifest to Device Management.

To test an update against a single device, use manifest-tool update device. This:

1. Performs the same actions as manifest-tool update prepare.
2. Creates an update campaign targeting a single device, identified by endpoint name.
3. Monitors the campaign.
4. Removes the firmware, manifest and update campaign from Device Management.