Documentation

Mistake on this page? Email us

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?
  • 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.
  • 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.

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.