Manifests

In order 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 in order 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).
• 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.

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 suitable for some use cases where 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.

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 that devices can prove that 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.