Uptane IEEE-ISTO Standard for Design and Implementation
uptane-standard-design

Abstract

This document describes a framework for securing ground vehicle software update systems.


Table of Contents

1. Introduction

Uptane is a secure software update framework for ground vehicles. This document describes procedures to enable programmers for OEMs and suppliers to securely design and implement this framework in a manner that better protects connected units on ground vehicles. Integrating Uptane as outlined in the sections that follow can reduce the ability of attackers to compromise critical systems. It also assures a faster and easier recovery process should a compromise occur.

These instructions specify the components necessary for a compliant implementation. Individual implementors can make their own technological choices within those requirements. This flexibility makes Uptane adaptable to the many customized update solutions used by manufacturers. If implementors wish to have compatible formats, they may use profiles. Profiles contain a description of implementation choices as well as data binding formats. An implementor who follows a profile as well as the Uptane standard will be able to interoperate with other implementations using that profile.

2. Terminology

2.1. Conformance Terminology

The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in [RFC2119].

In order to be considered “Uptane-compliant,” an implementation MUST follow all of these rules as specified in the document.

2.2. Terminology

Bundle: A set of images released by the repository that is meant to be installed by one or more target ECUs on a vehicle at the same time.

Bus: An internal communications network that interconnects components within a vehicle. A vehicle can have a number of buses that will vary in terms of power, speed and resources.

Image: File containing software for an ECU to install. May contain a binary image to flash, installation instructions, and other necessary information for the ECU to properly apply the update. Each ECU typically holds only one image, although this may vary in some cases.

Primary/Secondary ECUs: Terms used to describe the control units within a ground vehicle. A primary ECU downloads from a repository and verifies update images and metadata for itself and for secondary ECUs, and distributes images and metadata to secondaries. Thus, it requires extra storage space and a connection to the internet. Secondary ECUs receive their update images and metadata from the primary, and only need to verify and install their own metadata and images.

Profile: A document that contains information about a specific Uptane implementation. The profile contains decisions about SHOULDs and MAYs in an implementation, as well as descriptions of data binding formats. Profiles MAY be used to create compatible Uptane implementations.

Repository: A server containing metadata about images. May also contain the images themselves. Other data may be stored on the repository to be accessed by ECUs during the update process.

Suppliers: Independent companies to which auto manufacturers may outsource the production of ECUs. Tier-1 suppliers directly serve the manufacturers. Tier-2 suppliers are those that perform outsourced work for Tier-1 suppliers.

Vehicle Version Manifest: A compilation of all ECU version manifests on a vehicle. It serves as a master list of all images currently running on all ECUs in the vehicle.

2.3. Uptane Role Terminology

These terms are defined in greater detail in Section 5.1.

Delegations: A process by which the responsibility of signing metadata about images is assigned to another party.
Role: A party (human or machine) responsible for signing a certain type of metadata. The role controls keys and is responsible for signing metadata entrusted to it with these keys. The roles mechanism of Uptane allows the system to distribute signing responsibilities so that the compromise of one key does not necessarily impact the security of the entire system.

2.4. Acronyms and Abbreviations

CAN Bus: Controller Area Network bus standard

ECUs: Electronic Control Units, the computing units on a vehicle

LIN Bus: Local Interconnect Bus

SOTA: Software Updates Over-the-Air

VIN: Vehicle Identification Number

3. Rationale for and Scope of Uptane Standards

This Standards document clarifies the essential components and best practices for the secure design, implementation and deployment of Uptane by OEMs and suppliers. These practices contribute to compromise resilience, or the ability to minimize the extent of the threat posed by any given attack.

However, this specification is intended as an implementation guide, not as a detailed technical argument about the security properties that Uptane provides. Readers interested in such documentation should refer to published papers that cover this topic. [UPTANEESCAR]

3.1. Why Uptane requires standards

A standards document that can guide the safe design, integration and deployment of Uptane in vehicles is needed at this time because:

3.2. Scope of Standards Coverage

This document sets guidelines for implementing Uptane in most systems capable of updating software on connected units in ground vehicles, including passenger vehicles, light-duty trucks, heavy-duty trucks, and motorcycles. Uptane could potentially also be applied to other ground vehicles such as automated shuttles, recreational vehicles, and military ground vehicles, and Uptane could even be applied to domains such as IoT devices, medical devices, and UAVs. In this section, we define the scope of that applicability by providing sample use cases and possible exceptions, aspects of update security that are not applicable to Uptane, and the design requirements governing the preparation of these standards.

3.2.1. Assumptions

We assume the following system preconditions for Uptane:

It is important that any bugs detected in Uptane implementations be patched promptly. Failure to do so could interfere wth the effectiveness of Uptane’s operations.

3.2.2. Use Cases

The following use cases provide a number of scenarios illustrating the manner in which software updates could be accomplished using Uptane.

3.2.2.1. OEMs initializing Uptane at the factory using SOTA

An OEM plans to install Uptane on new vehicles. This entails the following components: code to perform full and partial verification, the latest copy of the relevant metadata, the public keys, and the latest time, signed by the time server (if implemented). The OEM then either requires its tier-1 suppliers to provide these materials to the suppliers’ assembly lines, or can choose to add the materials later at the OEM’s assembly lines. The OEM’s implementation is Uptane-compliant if:

  1. all primaries perform full verification;
  2. all secondaries that are updated via OTA perform full or partial verification; and
  3. all other ECUs that do not perform verification cannot be updated via OTA.

3.2.2.2. Updating one ECU with a complete image

A tier-1 supplier completes work on a revised image for an electronic brake control module. This module will control the brakes on all models of an SUV produced by the OEM mentioned above. Each tier-1 supplier digitally signs the image, then delivers the signature and all of its metadata, including delegations, and associated images to the OEM. The OEM adds these metadata and images to its image repository, along with information about any dependencies and conflicts between this image and those on other ECUs used in the OEM’s vehicles. The OEM also updates the inventory database, so that the director repository can instruct the ECU on how to install these updated images.

3.2.2.3. Updating individual ECUs on demand

An OEM has issued a recall to address a problem with a keyless entry device that has been locking people out of their cars. The OEM prepares an updated flash image in the manner described above. The OEM then ships USB flash drives to vehicle owners and dealerships that allow those parties to update the firmware of their vehicles.

3.2.2.4. Update one ECU with multiple deltas

The OEM wants to use delta updates to save over-the-air bytes. The delta images contain only the code and/or data that has changed from the previous image version. To do so, the OEM must first modify the director repository, using the vehicle version manifest and dependency resolution to determine the differences between the previous and latest images. The OEM then adds the following to the custom targets metadata used by the director repository: (1) the algorithm used to apply a delta image, and (2) the targets metadata about the delta image. The OEM will also check whether the delta images match the targets metadata from the director repository.

3.3. Exceptions

There are a number of factors that could impede the completion of the above scenarios:

3.4. Out of Scope

The following topics will not be addressed in this document, as they represent threats outside the scope of Uptane:

3.5. Design Requirements

The design requirements for this document are governed by the following principal parameters:

4. Threat Model and Attack Strategies

The overarching goal of Uptane is to provide a system that is resilient in the face of various types of compromise. In this section, we describe the goals that an attacker may have (Section 4.1) and the capabilities they may have or could develop (Section 4.2). We then describe and classify types of attacks on the system according to the attacker’s goals (Section 4.3).

4.1. Attacker goals

We assume that attackers may want to achieve one or more of the following goals, in increasing order of severity:

4.2. Attacker capabilities

Uptane is designed with resilience to compromise in mind. We assume that attackers may develop one or more of the following capabilities:

4.3. Description of threats

Uptane’s threat model includes the following types of attacks, organized according to the attacker goals listed in Section 4.1.

4.3.1. Read updates

4.3.2. Deny installation of updates

An attacker seeking to deny installation of updates may attempt one or more of the following strategies, among others:

4.3.3. Interfere with ECU functionality

Attackers seeking to interfere with the functionality of vehicle ECUs in order to cause an operational failure or unexpected behavior may do so in one of the following ways:

4.3.4. Control an ECU or vehicle

Full control of a vehicle, or one or more ECUs within a vehicle, is the most severe threat.

5. Detailed Design of Uptane

Uptane is a secure software update framework for automobiles. We do not specify implementation details. Instead, we describe the components necessary for a compliant implementation, and leave it up to individual implementors to make their own technological choices within those requirements.

At a high level, Uptane requires:

5.1. Roles on repositories

A repository contains images and metadata. Each role has a particular type of metadata associated with it, as described in Section 5.2.

5.1.1. The Root role

A repository’s Root role SHALL be responsible for a Certificate Authority as defined in [RFC3647]. A repository’s Root role SHALL produce and sign Root metadata as described in Section 5.2.2. A repository’s Root role SHALL sign the public keys used to verify the metadata produced by the Timestamp, Snapshot, and Targets roles. A repository’s Root role SHALL revoke keys for the other roles, in case of compromise.

5.1.2. The Targets role

A repository’s Targets role SHALL produce and sign metadata about images and delegations as described in Section 5.2.3.

5.1.2.1. Delegations

The Targets role on the Image repository MAY delegate the responsibility of signing metadata to other, custom-defined roles referred to as delegated targets. If it does, it MUST do so as specified in Section 5.2.3.2.

Responsibility for signing images or a subset of images MAY be delegated to more than one role and therefore it is possible for two different roles to be trusted for signing a particular image. For this reason, delegations MUST be prioritized.

A particular delegation for a subset of images MAY be designated as terminating. For terminating delegations, the client SHALL NOT search any further if it does not find validly signed metadata about those images in the terminating delegation. Delegations SHOULD NOT be terminating by default; terminating delegations SHOULD only be used when there is a compelling technical reason to do so.

A delegation for a subset of images MAY be a multi-role delegation [TAP-3]. A multi-role delegation indicates that multiple roles are needed to sign a particular image and so each of the delegatee roles MUST sign the same metadata.

Delegations only apply to the Image repository. The Targets role on the Director repository MUST NOT delegate metadata signing responsibility.

5.1.3. The Snapshot role

A repository’s Snapshot role SHALL produce and sign metadata about all Targets metadata the repository releases, including the current version number of the top-level Targets metadata, and the version numbers of all delegated targets metadata, as described in Section 5.2.4.

5.1.4. The Timestamp role

A repository’s Timestamp role SHALL produce and sign metadata indicating whether there are new metadata or images on the repository. It MUST do so by signing the metadata about the Snapshot metadata file.

5.2. Metadata structures

Uptane’s security guarantees all rely on properly created metadata that follow a designated structure. The Uptane standard does not mandate any particular format or encoding for the metadata as a whole. ASN.1 (with any encoding scheme like BER, DER, XER, etc.), JSON, XML, or any other encoding format that is capable of providing the required structure MAY be used.

However, string comparison is required as part of metadata verification. To ensure an accurate basis for comparing strings, all strings MUST be encoded in the Unicode Format for Network Interchange as defined in [RFC5198], including normalization into Unicode Normalization Form C ([NFC]).

In the Deployment Considerations document, the Uptane Alliance provides some examples of compliant metadata structures in ASN.1 and JSON.

5.2.1. Common Metadata Structures

Every public key MUST be represented using a public key identifier. A public key identifier is EITHER all of the following:

OR a secure hash over at least the above components (such as the keyid mechanism in TUF).

All four Uptane roles (Root, Targets, Snapshot, and Timestamp) share a common structure. They SHALL contain the following two attributes:

The payload differs depending on the role. However, the payload for all roles shares a common structure. It SHALL contain the following four attributes:

The following sections describe the role-specific metadata. All roles SHALL follow the common structures described here.

5.2.2. Root Metadata

A repository’s Root metadata distributes the public keys of the top-level Root, Targets, Snapshot, and Timestamp roles, as well as revocations of those keys. It SHALL contain two attributes:

Additionally, it MAY contain a mapping of roles to a list of valid URLs from which the role metadata can be downloaded. If this mapping of URLs is used, the implementer SHOULD implement this functionality following [TAP-5] to avoid adding unforeseen security risks.

5.2.3. Targets Metadata

Targets metadata, whether for the top-level Targets role or for any delegated targets role, MAY contain metadata about images on a repository. It MAY also contain metadata about delegations of signing authority.

5.2.3.1. Metadata about Images

To be available to install on clients, all images on the repository MUST have their metadata listed in a targets role. Each targets role MAY provide a list of some images on the repository. This list MUST provide, at a minimum, the following information about each image:

5.2.3.1.1. Custom metadata about images

In addition to the required metadata, the Targets metadata file MAY contain extra metadata for each image on the repository. This metadata can be customized for a particular use case. Examples of use cases for different types of custom metadata can be found in the Deployment Considerations document. However, there are a few important pieces of custom metadata that SHOULD be present in most implementations. In addition, there is one element in the custom metadata that MUST be present in the targets metadata from the director.

Custom metadata also MAY contain a field or section that is demarcated as custom metadata that MUST match whenever two pieces of metadata are checked against each other–most commonly, when targets metadata from the Director and Image repositories are checked against each other.

The following information SHOULD be provided for each image on both the Image repository and the Director repository, and SHOULD be included in the “MUST match” section, if it is implemented:

The following information is CONDITIONALLY REQUIRED for each image on the Director repository IF that image is encrypted:

The following information MUST be provided for each image in the targets metadata from the Director repository:

The Director repository MAY provide a download URL for the image file. This may be useful, for example, when the image is on a public CDN and the director wishes to provide a signed URL.

5.2.3.2. Metadata about Delegations

A Targets metadata file on the Image repository (but not the Director repository) MAY delegate signing authority to other entities–for example, it could delegate signing authority for a particular ECU’s firmware to that ECU’s supplier. A metadata file MAY contain more than one delegation, and MUST keep the delegations in prioritized order.

A list of delegations MUST provide the following information:

Note that any targets metadata file may contain delegations, and that delegations can be in chains of arbitrary length.

5.2.3.3. Metadata about Time Server

If a Time Server Section 5.3.3 is implemented AND partial-verification secondaries will be used, the following metadata is CONDITIONALLY REQUIRED in the Director repository’s Targets metadata:

Listing the public key of the Time Server in Director targets metadata is necessary to allow partial-verification secondaries to perform time server key rotation.

5.2.4. Snapshot Metadata

The Snapshot metadata lists version numbers and filenames of all Targets metadata files. It protects against mix-and-match attacks if a delegated supplier key is compromised.

For each Targets metadata file on the repository, the Snapshot metadata SHALL contain the following information:

The Snapshot metadata MAY also list the root metadata filename and version number. This is not required, particularly for implementations of [TAP-5], but MAY be included in all cases for backwards compatibility.

5.2.5. Timestamp Metadata

The Timestamp metadata SHALL contain the following information:

5.2.6. Repository mapping metadata

Repository mapping metadata informs a primary ECU about which repositories to trust for images or image paths. Repository mapping metadata MUST be present on all primary ECUs, and MUST contain the following information:

For example, in the most basic Uptane case, the repository mapping metadata would contain:

However, more complex repository mapping metadata can permit more complicated use cases. For example:

The Deployment Considerations document gives more guidance on how to implement repository mapping metadata for these use cases. It also discusses strategies for updating repository mapping metadata, if required. [TAP-4] also contains detailed guidance on repository mapping metadata implementation.

Note that repository mapping metadata might not be a file, and MAY be expressed in a different format than the repository roles metadata. For example, it could be part of the primary ECU’s Uptane client configuration. As long as the client has access to the required information, the repository mapping metadata requirements are met.

5.2.7. Rules for filenames in repositories and metadata

There is a difference between the file name in a metadata file or an ECU, and the file name on a repository. This difference exists in order to avoid race conditions, where metadata and images are read from, and written to, at the same time. For more details, the reader should read the TUF specification [TUF-spec] and PEP 458 [PEP-458].

Unless stated otherwise, all files SHALL be written to repositories in accordance with following two rules:

  1. Metadata filenames SHALL be qualified with version numbers. If a metadata file A is specified as FILENAME.EXT in another metadata file B, then it SHALL be written as VERSION.FILENAME.EXT, where VERSION is A’s version number, as defined in Section 5.2.1, with one exception: If the version number of the Timestamp metadata file might not be known in advance by a client, it MAY be read from, and written to, a repository using a filename without a version number qualification, i.e. FILENAME.EXT.
  2. If an image is specified in a targets metadata file as FILENAME.EXT, it SHALL be written to the repository as HASH.FILENAME.EXT, where HASH is one of the hash digests of the file, as specified in Section 5.2.3.1. The file MUST be written to the repository using n different filenames, one for each hash digest listed in its corresponding targets metadata.

For example:

5.3. Server / repository implementation requirements

An Uptane implementation SHALL make the following services available to vehicles:

Additionally, an Uptane implementation requires ECUs to have a secure way to know the current time. This SHOULD be accomplished using a time server (Section 5.3.3), but MAY be implemented in other ways.

5.3.1. Image Repository

The Image repository exists to allow an OEM and/or its suppliers to upload images and their associated metadata. It makes these images and their metadata available to vehicles. The Image repository is designed to be primarily controlled by human actors, and updated relatively infrequently.

The Image repository SHALL expose an interface permitting the download of metadata and images. This interface SHOULD be public.

The Image repository SHALL require authorization for writing metadata and images.

The Image repository SHALL provide a method for authorized users to upload images and their associated metadata. It SHALL check that a user writing metadata and images is authorized to do so for that specific image by checking the chain of delegations as described in Section 5.2.3.2.

The Image repository SHALL implement storage which permits authorized users to write an image file using a unique filename, and later read the same file using the same name. It MAY use any filesystem, key-value store, or database that fulfills this requirement.

The Image repository MAY require authentication for read access.

5.3.2. Director Repository

The Director repository instructs ECUs as to which images should be installed by producing signed metadata on demand. Unlike the Image repository, it is mostly controlled by automated, online processes. It also consults a private inventory database containing information on vehicles, ECUs, and software revisions.

The Director repository SHALL expose an interface for primaries to upload vehicle version manifests (Section 5.4.2.1.1) and download metadata. This interface SHOULD be public. The Director MAY encrypt images for ECUs that require them, either by encrypting on-the-fly or by storing encrypted images in the repository.

The Director repository SHALL implement storage which permits an automated service to write generated metadata files. It MAY use any filesystem, key-value store, or database that fulfills this requirement.

5.3.2.1. Directing installation of images on vehicles

A Director repository MUST conform to the following six-step process for directing the installation of software images on a vehicle.

  1. When the Director receives a vehicle version manifest sent by a primary (as described in Section 5.4.2.1), it decodes the manifest, and determines the unique vehicle identifier.
  2. Using the vehicle identifier, the Director queries its inventory database (as described in Section 5.3.2.2) for relevant information about each ECU in the vehicle.
  3. The Director checks the manifest for accuracy compared to the information in the inventory database. If any of the required checks fail, the Director drops the request. An implementor MAY make whatever additional checks they wish. At a minimum, the Director SHALL check the following:
  4. The Director extracts information about currently installed images from the vehicle version manifest. Using this information, it determines if the vehicle is already up-to-date, and if not, determines a set of images that should be installed. The exact process by which this determination takes place is out of scope of this standard. However, the Director MUST take into account dependencies and conflicts between images, and SHOULD consult well-established techniques for dependency resolution.
  5. The Director MAY encrypt images for ECUs that require it.
  6. The Director generates new metadata representing the desired set of images to be installed on the vehicle, based on the dependency resolution in step 4. This includes targets (Section 5.2.3), snapshot (Section 5.2.4), and timestamp (Section 5.2.5) metadata. It then sends this metadata to the primary as described in Section 5.4.2.3.

5.3.2.2. Inventory Database

The Director SHALL use a private inventory database to store information about ECUs and vehicles. An implementor MAY use any durable database for this purpose.

The inventory database MUST record the following pieces of information:

The inventory database MAY record other information about ECUs and vehicles. It SHOULD record a hardware identifier for each ECU, to protect against the possibility of directing the ECU to install an incompatible firmware.

5.3.3. Time Server

The Time Server exists to inform vehicles about the current time in a cryptographically secure way, since many ECUs in a vehicle will not have a reliable source of time. It receives lists of tokens from vehicles, and returns back a signed sequence that includes the token and the current time.

An Uptane implementation SHOULD include a time server, but MAY use another secure source of time. If the time server is used, it MUST conform to the following requirements:

When the Time Server receives a sequence of tokens from a vehicle, it SHALL provide one or more signed responses, containing the time along with these tokens. It MAY produce either one signed time attestation containing the current time and all tokens, or multiple time attestations each containing the current time and one or more tokens.

The Time Server SHALL expose a public interface allowing primaries to communicate with it. This communication MAY occur over FTP, FTPS, SFTP, HTTP, or HTTPS.

Rotation of the The Time Server’s key is performed by listing the new key in the Director’s Root metadata, in the same manner as other role keys are listed, and also in the Director’s Targets metadata (for partial verification secondaries).

5.4. In-vehicle implementation requirements

An Uptane-compliant ECU SHALL be able to download and verify the time, metadata, and image binaries before installing a new image.

Each ECU in a vehicle receiving over-the-air updates is either a primary or a secondary ECU. A primary ECU collects and delivers to the Director vehicle manifests (Section 5.4.2.1.1) containing information about which images have been installed on ECUs in the vehicle. It also downloads and verifies the latest time, metadata, and images for itself and for its secondaries. A secondary ECU downloads and verifies the latest time, metadata, and images for itself from its associated primary ECU. It also sends signed information about its installed images to its associated primary.

All ECUs MUST verify image metadata as specified in Section 5.4.4 before installing an image or making it available to other ECUs. A primary ECU MUST perform full verification (Section 5.4.4.2). A secondary ECU SHOULD perform full verification if possible. See Uptane Deployment Considerations for a discussion of how to choose between partial and full verification.

5.4.1. Build-time prerequisite requirements for ECUs

For an ECU to be capable of receiving Uptane-secured updates, it MUST have the following data provisioned at the time it is manufactured or installed in the vehicle:

  1. A sufficiently recent copy of required Uptane metadata at the time of manufacture or install. See Uptane Deployment Considerations for more information.
  2. The public key(s) of the time server (if the time server is implemented).
  3. The current time. This SHOULD be in the form of an attestation of time downloaded from the time server, but MAY come from another source if the time server is not implemented.
  4. An ECU key. This is a private key, unique to the ECU, used to sign ECU version manifests and decrypt images. An ECU key MAY be either a symmetric key or an asymmetric key. If it is an asymmetric key, there MAY be separate keys for encryption and signing. For the purposes of this standard, the set of private keys that an ECU uses is referred to as the ECU key (singular), even if it is actually multiple keys used for different purposes.

5.4.2. What the primary does

A primary downloads, verifies, and distributes the latest time, metadata and images. To do so, it SHALL perform the following seven steps:

  1. Construct and send vehicle version manifest (Section 5.4.2.1)
  2. Download and check current time (Section 5.4.2.2)
  3. Download and verify metadata (Section 5.4.2.3)
  4. Download and verify images (Section 5.4.2.4)
  5. Send latest time to secondaries (Section 5.4.2.5)
  6. Send metadata to secondaries (Section 5.4.2.6)
  7. Send images to secondaries (Section 5.4.2.7)

5.4.2.1. Construct and send vehicle version manifest

The primary SHALL build a vehicle version manifest as described in Section 5.4.2.1.1.

Once it has the complete manifest built, it MAY send the manifest to the Director repository. However, it is not strictly required that the primary send the manifest until step three.

Secondaries MAY send their version report at any time, so that it is already stored on the primary when it wishes to check for updates. Alternatively, the primary MAY request a version report from each secondary at the time of the update check.

5.4.2.1.1. Vehicle version manifest

The vehicle version manifest is a metadata structure that MUST contain the following information:

Note that one of the ECU version reports should be the version report for the primary itself.

5.4.2.1.2. ECU version report

An ECU version report is a metadata structure that MUST contain the following information:

5.4.2.2. Download and check current time

The primary SHALL load the current time from a secure source. This secure source SHOULD be a time server as described in Section 5.3.3.

If the time server is implemented, the primary SHALL use the following procedure to verify the time:

  1. Gather the tokens from each secondary ECU’s version report (Section 5.4.2.1.2).
  2. Send the list of tokens to the time server to fetch the current time. The time server responds as described in Section 5.3.3, providing a cryptographic attestation of the last known time.
  3. If the time server’s response meets the criteria below, update the primary ECU’s clock and retain the time server’s response for distribution to secondary ECUs, otherwise discard it and proceed without an updated time. The criteria for checking the time server’s response are: - The signature over the time server’s response is valid. - The tokens provided to the time server have been included in the response. - The time in the time server’s response is later than the last time verified in this manner.

5.4.2.3. Download and verify metadata

The primary SHALL download metadata for all targets and perform a full verification on it as specified in Section 5.4.4.2.

5.4.2.4. Download and verify images

The primary SHALL download and verify images for itself and for all of its associated secondaries. Images SHALL be verified by checking that the hash of the image file matches the hash specified in the director’s targets metadata for that image.

There may be several different filenames that all refer to the same image binary, as described in Section 5.2.3. The primary SHALL associate each image binary with each of its possible filenames.

5.4.2.5. Send latest time to secondaries

The primary SHOULD send the time to each ECU. The secondary will verify the time message, then overwrite its current time with the received time.

5.4.2.6. Send metadata to secondaries

The primary SHALL send its latest downloaded metadata to all of its associated secondaries. The metadata it sends to each secondary MUST include all of the metadata required for verification on that secondary. For full verification secondaries, this includes the metadata for all four roles from both repositories, plus any delegated targets metadata files the secondary will recurse through to find the proper delegation. For partial verification secondaries, this includes only the targets metadata file from the director repository.

The primary SHOULD determine the minimal set of metadata files to send to each secondary, by performing delegation resolution as described in Section 5.4.4.2.

Each secondary SHALL store the latest copy of all metadata required for its own verification.

5.4.2.7. Send images to secondaries

The primary SHALL send the latest image to each of its associated secondaries that have storage to receive it.

For secondaries without storage, the primary SHOULD wait for a request from the secondary to stream the new image file to it. The secondary will send the request once it has verified the metadata sent in the previous step.

5.4.3. Installing images on primary or secondary ECUs

Before installing a new image, an ECU SHALL perform the following five steps:

  1. Verify latest attested time (Section 5.4.3.1)
  2. Verify metadata (Section 5.4.3.2)
  3. Download latest image (Section 5.4.3.3)
  4. Verify image (Section 5.4.3.4)
  5. Create and send version report (Section 5.4.3.5)

5.4.3.1. Load and verify the latest attested time

The ECU SHOULD load and verify the current time, or the most recent time from the time server if it is implemented.

If an Uptane time server (Section 5.3.3) is implemented, the ECU SHALL:

  1. Verify that the signatures on the downloaded time are valid.
  2. Verify that the list of nonces/tokens in the downloaded time includes the token that the ECU sent in its previous version report.
  3. Verify that the time downloaded is greater than the previous time.

If all three steps complete without error, the ECU SHALL overwrite its current attested time with the time it has just downloaded, and generate a new nonce/token for the next request to the time server.

If any check fails, the ECU SHALL NOT overwrite its current attested time, and SHALL jump to the fifth step (Section 5.4.3.5), and report the error. The ECU MUST reuse its previous token for the next request to the time server.

5.4.3.2. Verify metadata

The ECU SHALL verify the latest downloaded metadata (Section 5.4.4) using either full or partial verification. If the metadata verification fails for any reason, the ECU SHALL jump to the fifth step (Section 5.4.3.5).

5.4.3.3. Download latest image

If the ECU does not have secondary storage, i.e. buffer storage to temporarily store the latest image before installing it, it SHALL download the latest image from the primary. (If the ECU has secondary storage, it will already have the latest image in its secondary storage as specified in Section 5.4.2.7, and should skip to the next step.) The ECU MAY first create a backup of its previous working image and store it elsewhere (e.g., the primary).

The filename used to identify the latest known image (i.e., the file to request from the primary) SHALL be determined as follows:

  1. Load the Targets metadata file from the Director repository.
  2. Find the Targets metadata associated with this ECU identifier.
  3. Construct the Image filename using the rule in Section 5.2.7, or use the download URL specified in the Director metadata.
  4. If there is no Targets metadata about this image, abort the update cycle and report that there is no such image. Otherwise, download the image (up to the number of bytes specified in the Targets metadata), and verify that its hashes match the Targets metadata.

When the primary responds to the download request, the ECU SHALL overwrite its current image with the downloaded image from the primary.

If any part of this step fails, the ECU SHALL jump to the fifth step (Section 5.4.3.5).

5.4.3.4. Verify image

The ECU SHALL verify that the latest image matches the latest metadata as follows:

  1. Load the latest Targets metadata file from the director.
  2. Find the Targets metadata associated with this ECU identifier.
  3. Check that the hardware identifier in the metadata matches the ECUs hardware identifier.
  4. Check that the image filename is valid for this ECU. This MAY be a comparison against a wildcard path, and restricts the ECUs a delegation applies to.
  5. Check that the release counter of the image in the previous metadata, if it exists, is less than or equal to the release counter in the latest metadata.
  6. If the image is encrypted, decrypt the image with a decryption key to be chosen as follows:
  7. Check that the hash of the image matches the hash in the metadata.

If the ECU has secondary storage, the checks SHOULD be performed on the image in secondary storage, before it is installed.

If any step fails, the ECU SHALL jump to the fifth step (Section 5.4.3.5). If a step fails and the ECU does not have secondary storage, and the ECU has created a backup of its previous working image, the ECU SHOULD now install the backup image.

5.4.3.5. Create and send version report

The ECU SHALL create a version report as described in Section 5.4.2.1.2, and send it to the primary (or simply save it to disk, if the ECU is a primary). The primary SHOULD write the version reports it receives to disk and associate them with the secondaries that sent them.

5.4.4. Metadata verification procedures

A primary ECU MUST perform full verification of metadata. A secondary ECU SHOULD perform full verification of metadata, but MAY perform partial verification instead.

If a step in the following workflows does not succeed (e.g., the update is aborted because a new metadata file was not signed), an ECU SHOULD still be able to update again in the future. Errors raised during the update process SHOULD NOT leave ECUs in an unrecoverable state.

5.4.4.1. Partial verification

In order to perform partial verification, an ECU SHALL perform the following steps:

  1. Load the latest attested time from the time server, if implemented.
  2. Download and check the Targets metadata file from the Director repository, following the procedure in Section 5.4.4.6.

5.4.4.2. Full verification

Full verification of metadata means that the ECU checks that the Targets metadata about images from the Director repository matches the Targets metadata about the same images from the Image repository. This provides resilience to a key compromise in the system.

Full verification MAY be performed by either primary or secondary ECUs. The procedure is the same, except that secondary ECUs receive their metadata from the primary instead of downloading it directly. In the following instructions, whenever an ECU is directed to download metadata, it applies only to primary ECUs.

If [TAP-5] is supported, a primary ECU SHALL download metadata and images following the rules specified in that TAP. If [TAP-5] is not supported, the download should follow the [TUF-spec] and the metadata file renaming rules specified in Section 5.2.7.

In order to perform full verification, an ECU SHALL perform the following steps:

  1. Load the repository mapping metadata (Section 5.2.6), and use the information therein to determine from where metadata should be downloaded.
  2. Load the latest attested time from the time server, if implemented.
  3. Download and check the Root metadata file from the Director repository, following the procedure in Section 5.4.4.3.
  4. Download and check the Timestamp metadata file from the Director repository, following the procedure in Section 5.4.4.4.
  5. Download and check the Snapshot metadata file from the Director repository, following the procedure in Section 5.4.4.5.
  6. Download and check the Targets metadata file from the Director repository, following the procedure in Section 5.4.4.6.
  7. Download and check the Root metadata file from the Image repository, following the procedure in Section 5.4.4.3.
  8. Download and check the Timestamp metadata file from the Image repository, following the procedure in Section 5.4.4.4.
  9. Download and check the Snapshot metadata file from the Image repository, following the procedure in Section 5.4.4.5.
  10. Download and check the top-level Targets metadata file from the Image repository, following the procedure in Section 5.4.4.6.
  11. Verify that Targets metadata from the Director and Image repositories match. A primary ECU MUST perform this check on metadata for all images listed in the Targets metadata file from the Director repository downloaded in step 6. A secondary ECU MAY elect to perform this check only on the metadata for the image it will install. (That is, the target metadata from the Director that contains the ECU identifier of the current ECU.) To check that the metadata for an image matches, complete the following procedure:
    1. Locate and download a Targets metadata file from the Image repository that contains an image with exactly the same file name listed in the Director metadata, following the procedure in Section 5.4.4.7.
    2. Check that the Targets metadata from the Image repository matches the Targets metadata from the Director repository:
      1. Check that the non-custom metadata (i.e., length and hashes) of the unencrypted image are the same in both sets of metadata.
      2. Check that all “MUST match” custom metadata (e.g., hardware identifier and release counter) are the same in both sets of metadata.
      3. Check that the release counter in the previous targets metadata file is less than or equal to the release counter in this targets metadata file.

If any step fails, the ECU MUST return an error code indicating the failure. If a check for a specific type of security attack fails (e.g. rollback, freeze, arbitrary software, etc.), the ECU SHOULD return an error code that indicates the type of attack.

If the ECU performing the verification is the primary ECU, it SHOULD also ensure that the targets metadata from the director repository doesn’t contain any ECU identifiers for ECUs not actually present in the vehicle.

5.4.4.3. How to check Root metadata

  1. Load the previous Root metadata file.
  2. Update to the latest Root metadata file.
    1. Let N denote the version number of the latest Root metadata file (which at first could be the same as the previous root metadata file).
    2. Try downloading a new version N+1 of the Root metadata file, up to some X number of bytes. The value for X is set by the implementor. For example, X may be tens of kilobytes. The filename used to download the root metadata file is of the fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is not available, the current Root metadata file is the latest; continue with step 3.
    3. Version N+1 of the Root metadata file MUST have been signed by: (1) a threshold of keys specified in the latest Root metadata file (version N), and (2) a threshold of keys specified in the new Root metadata file being validated (version N+1). If version N+1 is not signed as required, discard it, abort the update cycle, and report the signature failure. On the next update cycle, begin at version N of the root metadata file. (Checks for an arbitrary software attack.)
    4. The version number of the latest Root metadata file (version N) must be less than or equal to the version number of the new Root metadata file (version N+1). Effectively, this means checking that the version number signed in the new Root metadata file is indeed N+1. If the version of the new Root metadata file is less than the latest metadata file, discard it, abort the update cycle, and report the rollback attack. On the next update cycle, begin at step 0 and version N of the Root metadata file. (Checks for a rollback attack.)
    5. Set the latest Root metadata file to the new Root metadata file.
    6. Repeat steps 2.1 to 2.6.
  3. If the Timeserver key is listed in the Root metadata and has been rotated, reset the clock used to determine the expiration of metadata to a minimal value (e.g. zero, or any time that is guaranteed to not be in the future based on other evidence). It will be updated in the next cycle.
  4. Check that the latest attested time is lower than the expiration timestamp in the latest Root metadata file. (Checks for a freeze attack.)
  5. If the Timestamp and / or Snapshot keys have been rotated, delete the previous Timestamp and Snapshot metadata files. (Checks for recovery from fast-forward attacks [MERCURY].)

5.4.4.4. How to check Timestamp metadata

  1. Download up to Y number of bytes. The value for Y is set by the implementor. For example, Y may be tens of kilobytes. The filename used to download the Timestamp metadata file is of the fixed form FILENAME.EXT (e.g., timestamp.json).
  2. Check that it has been signed by the threshold of keys specified in the latest Root metadata file. If the new timestamp metadata file is not properly signed, discard it, abort the update cycle, and report the signature failure. (Checks for an arbitrary software attack.)
  3. Check that the version number of the previous Timestamp metadata file, if any, is less than or equal to the version number of this Timestamp metadata file. If the new Timestamp metadata file is older than the trusted Timestamp metadata file, discard it, abort the update cycle, and report the potential rollback attack. (Checks for a rollback attack.)
  4. Check that the latest attested time is lower than the expiration timestamp in this Timestamp metadata file. If the new Timestamp metadata file has expired, discard it, abort the update cycle, and report the potential freeze attack. (Checks for a freeze attack.)

5.4.4.5. How to check Snapshot metadata

  1. Download up to the number of bytes specified in the Timestamp metadata file, constructing the metadata filename as defined in Section 5.2.7.
  2. The hashes and version number of the new Snapshot metadata file MUST match the hashes and version number listed in Timestamp metadata. If the hashes and version number do not match, discard the new Snapshot metadata, abort the update cycle, and report the failure. (Checks for a mix-and-match attack.)
  3. Check that it has been signed by the threshold of keys specified in the latest Root metadata file. If the new Snapshot metadata file is not signed as required, discard it, abort the update cycle, and report the signature failure. (Checks for an arbitrary software attack.)
  4. Check that the version number of the previous Snapshot metadata file, if any, is less than or equal to the version number of this Snapshot metadata file. If this Snapshot metadata file is older than the previous Snapshot metadata file, discard it, abort the update cycle, and report the potential rollback attack. (Checks for a rollback attack.)
  5. Check that the version number listed by the previous Snapshot metadata file for each Targets metadata file is less than or equal to the its version number in this Snapshot metadata file. If this condition is not met, discard the new Snapshot metadata file, abort the update cycle, and report the failure. (Checks for a rollback attack.)
  6. Check that each Targets metadata filename listed in the previous Snapshot metadata file is also listed in this Snapshot metadata file. If this condition is not met, discard the new Snapshot metadata file, abort the update cycle, and report the failure. (Checks for a rollback attack.)
  7. Check that the latest attested time is lower than the expiration timestamp in this Snapshot metadata file. If the new Snapshot metadata file is expired, discard it, abort the update cycle, and report the potential freeze attack. (Checks for a freeze attack.)

5.4.4.6. How to check Targets metadata

  1. Download up to Z number of bytes, constructing the metadata filename as defined in Section 5.2.7. The value for Z is set by the implementor. For example, Z may be tens of kilobytes.
  2. The version number of the new Targets metadata file MUST match the version number listed in the latest Snapshot metadata. If the version number does not match, discard it, abort the update cycle, and report the failure. (Checks for a mix-and-match attack.) Skip this step if checking Targets metadata on a partial-verification ECU; partial-verification ECUs will not have Snapshot metadata.
  3. Check that it has been signed by the threshold of keys specified in the relevant metadata file (Checks for an arbitrary software attack):
    1. If checking top-level targets metadata, the threshold of keys is specified in the Root metadata.
    2. If checking delegated targets metadata, the threshold of keys is specified in the targets metadata file that delegated authority to this role.
  4. Check that the version number of the previous Targets metadata file, if any, is less than or equal to the version number of this Targets metadata file. (Checks for a rollback attack.)
  5. If this Targets metadata file indicates that the Timeserver key should be rotated, then reset the clock used to determine the expiration of metadata to a minimal value (e.g. zero, or any time that is guaranteed to not be in the future based on other evidence). It will be updated in the next cycle.
  6. Check that the latest attested time is lower than the expiration timestamp in this Targets metadata file. (Checks for a freeze attack.)
  7. If checking targets metadata from the Director repository, verify that there are no delegations.
  8. If checking targets metadata from the Director repository, check that no ECU identifier is represented more than once.

5.4.4.7. How to resolve delegations

To properly check targets metadata for an image, an ECU MUST locate the metadata file(s) for the role (or roles) that have the authority to sign the image. This metadata might be located in the top-level targets metadata, but it also may be delegated to another role–or to multiple roles. Therefore, all delegations MUST be resolved using the following recursive procedure, beginning with the top-level targets metadata file.

  1. Download the current metadata file, and check it following the procedure in Section 5.4.4.6. If the file cannot be loaded, or if any verification step fails, abort the delegation resolution, and indicate that image metadata cannot be found because of a missing or invalid role.
  2. If the current metadata file contains signed metadata about the image, end the delegation resolution and return the metadata to be checked.
  3. If the current metadata file was reached via a terminating delegation and does not contain signed metadata about the image, abort the delegation resolution for this image and return an error indicating that image metadata could not be found.
  4. Search the list of delegations, in listed order. For each delegation:
    1. Check if the delegation applies to the image being processed. For the delegation to apply, it MUST include the hardware identifier of the target, and the target name must match one of the delegation’s image paths. If either of these tests fail, move on to the next delegation in the list.
    2. If the delegation is a multi-role delegation, follow the procedure described in Section 5.4.4.8. If the multi-role delegation is terminating and no valid image metadata is found, abort the delegation resolution and return an error indicating that image metadata could not be found.
    3. If the delegation is a normal delegation, perform delegation resolution, starting at step 1. Note that this may recurse an arbitrary number of levels deep. If a delegation that applies to the image is found but no image metadata is found in the delegated roles or any of its sub-delegations, simply continue on with the next delegation in the list. The search is only completed/aborted if image metadata or a terminating delegation that applies to the image is found.
  5. If the end of the list of delegations in the top-level metadata is reached without finding valid image metadata, return an error indicating that image metadata could not be found.

5.4.4.8. Multi-role delegations

It is possible to delegate signing authority to multiple delegated roles as described in [TAP-3]. Each multi-role delegation effectively contains a list of ordinary delegations, plus a threshold of those roles that must be in agreement about the non-custom metadata for the image. All multi-role delegations MUST be resolved using the following procedure. Note that there may be sub-delegations inside multi-role delegations.

  1. For each of the roles in the delegation, find and load the image metadata (or error) following the procedure in Section 5.4.4.7.
  2. Inspect the non-custom part of the metadata loaded in step 1:
    1. Locate all sets of roles which have agreeing (i.e. identical) non-custom metadata and “MUST match” custom metadata. Discard any set of roles with a size smaller than the threshold of roles that must be in agreement for this delegation.
    2. Check for a conflict. A conflict exists if there remains more than one agreeing set of roles, each set having different metadata. If a conflict is found, choose and return the metadata from the set of roles which includes the earliest role in the multi-delegation list.
    3. If there is no conflict, check if there is any single set of roles with matching non-custom metadata. If there is, choose and return the metadata from this set.
    4. If no agreeing set can be found that meets the agreement threshold, return an error indicating that image metadata could not be found.

6. References

6.1. Normative References

[NFC] Davis, M. and M. Duerst, "Unicode Standard Annex #15: Unicode Normalization Forms", October 2018.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, DOI 10.17487/RFC2616, June 1999.
[RFC3280] Housley, R., Polk, W., Ford, W. and D. Solo, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 3280, DOI 10.17487/RFC3280, April 2002.
[RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 2003.
[RFC3647] Chokhani, S., Ford, W., Sabett, R., Merrill, C. and S. Wu, "Internet X.509 Public Key Infrastructure Certificate Policy and Certification Practices Framework", RFC 3647, DOI 10.17487/RFC3647, November 2003.
[RFC4634] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms (SHA and HMAC-SHA)", RFC 4634, DOI 10.17487/RFC4634, July 2006.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006.
[RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008.
[RFC5756] Turner, S., Brown, D., Yiu, K., Housley, R. and T. Polk, "Updates for RSAES-OAEP and RSASSA-PSS Algorithm Parameters", RFC 5756, DOI 10.17487/RFC5756, January 2010.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014.
[TAP-3] Kuppusamy, T., Awwad, S., Cordell, E., Diaz, V., Moshenko, J. and J. Cappos, "The Update Framework TAP 3 - Multi-role delegations", January 2018.
[TAP-4] Kuppusamy, T., Awwad, S., Cordell, E., Diaz, V., Moshenko, J. and J. Cappos, "The Update Framework TAP 4 - Multiple repository consensus on entrusted targets", December 2017.
[TAP-5] Kuppusamy, T., Awwad, S., Cordell, E., Diaz, V., Moshenko, J. and J. Cappos, "The Update Framework TAP 5 - Setting URLs for roles in the root metadata file", January 2018.
[TUF-spec] Samuel, J., Mathewson, N., Condra, G., Diaz, V., Kuppusamy, T., Awwad, S., Tobias, S., Wright, J., Mehnert, H., Tryzelaar, E., Cappos, J. and R. Dingledine, "The Update Framework Specification", September 2018.

6.2. Informative References

[CR-OTA] Barry, K., "Automakers Embrace Over-the-Air Updates, but Can We Trust Digital Car Repair?", April 2018.
[DEPLOY] "Uptane Deployment Guidelines", n.d..
[ED25519] Bernstein, D., Duif, N., Lange, T., Schwabe, P. and B-Y. Yang, ""High-Speed High-Security Signatures", Journal of Cryptographic Engineering, Vol. 2", September 2011.
[IN-TOTO] "in-toto: A framework to secure the integrity of software supply chains", October 2018.
[MERCURY] Kuppusamy, T., Diaz, V. and J. Cappos, "Mercury: Bandwidth-Effective Prevention of Rollback Attacks Against Community Repositories", ISBN 978-1-931971-38-6, July 2017.
[PEP-458] Kuppusamy, T., Diaz, V., Stufft, D. and J. Cappos, "PEP 458 -- Surviving a Compromise of PyPI", September 2013.
[RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, DOI 10.17487/RFC1321, April 1992.
[UPTANEESCAR] Kuppusamy, T., Brown, A., Awwad, S., McCoy, D., Bielawski, R., Mott, C., Lauzon, S., Weimerskirch, A. and J. Cappos, "Securing Software Updates for Automobiles", October 2016.
[USATODAY] O'Donnell, B., "Your average car is a lot more code-driven than you think", June 2016.

Author's Address

Uptane Alliance Community Uptane Alliance (c/o Prof. Justin Cappos) 6 MetroTech Brooklyn, NY 11201 USA EMail: uptane-standards@googlegroups.com