Manifests

For a device to apply an update, the device has to make several decisions about the update:

• Does it trust the author of the update?
• Has the update been corrupted?
• Does the update apply to this device?
• Is the update older than the active payload?
• When should the device apply the update?
• How should the device apply the update?
• What kind of update is it?
• Is the update installed automatically, or does it require user approval?
• Where should it obtain the update from?
• Where should it store the update?

A manifest encodes the information that devices need to make these decisions. The manifest tool uses the following data to create the manifest:

• Private key that signs the manifest and its matching certificate.
• Type of signing and encryption used.
• Current timestamp.
• Manufacturer ID.
• Device Class ID.
• Payload (for example, the firmware). The manifest tool uses this file to create the digest of the payload.
• The payload type. The Update client currently only supports binary payloads, so the payload type is assumed to be binary.
• URL from which the device should fetch the payload.
• Update priority (optional).
• Resume flags.
• Storage identifier for where the device should store the payload.

Note The client always installs the payload immediately. The client does not support the applyImmediately option, which is always assumed to be true. If you specify applyImmediately=false, the manifest tool warns that the option is unsupported. The client also does not support validFrom and validTo.

Manifest delivery

Device Management only delivers new manifests to devices that are idle, or able to receive a manifest:

• If a device is currently processing a manifest, it's marked as busy. The device appears as manifest_received in Device Directory once it finishes downloading the manifest. The service won't send the more manifests while the device is still busy. The device stays busy through the update process.
• Once the update is complete and the device reregisters, the device becomes idle again and can receive new manifests.

If there is a mismatch between the state of the device and its status in Device Management, the service marks the device as failed in the update campaign.

How Device Management uses the manifest

The manifest describes a firmware object and contains all the information a device needs to validate and install a firmware update. For example:

• The target device.
• A (UTC) timestamp of the manifest creation.
• The firmware hash and where to find it.
• One or more signatures.

Firmware authors produce manifests separately from firmware images. This simplifies the distribution of images: Firmware authors can send a single image to disparate devices, regardless of whether the devices require the same metadata or not.

The manifest is signed, so devices can prove they trust the author of the update. The authority, integrity and authenticity of a firmware update is not transport dependent:

• Manifests include a fingerprint of the certificate used to sign them. Update client uses this to determine what, if any, authority it grants to the person that signed the manifest. Currently, the presence of a certificate on a device determines authority: If the certificate is present, the signer has the authority to install firmware.

• The manifest contains a hash of the firmware image. A trusted developer from the previous step signs the manifest, which establishes a chain of trust. This allows the target device to make decisions about whether, when and how to install a firmware update. It also permits distribution of the firmware image over a Content Distribution Network, which does not itself need to be trusted; the metadata establishes trust.

The manifest uses ASN.1 DER encoding.

Resuming firmware download

If a device receives a manifest and begins downloading the new firmware image, Device Management can resume the download from where it left off if the download is interrupted.

This requires the latest bootloader, which is currently available only for firmware updates using Client Lite.

Manifests and campaign priority

Note: Update priority is compatible with Device Management Client 3.4 and later.

When you create a manifest, you can set the priority of the update the manifest is attached to.

This also allows you to determine whether an update is high priority (mandatory) or low priority (which your application can treat as optional). This is not a required step but is suitable for some use cases in which you maintain devices but are not the end user.

For more information on how to implement update priority, see Creating a firmware manifest.

Rejected updates show as failed in detailed campaign metrics. You can also filter by event log codes to track which devices have rejected updates.