Skip to main content
Version: Torizon OS 7.x.y

First Steps with Secure Offline Updates

Introduction​

In this article you will learn the basics about Secure Offline Updates with Torizon. This article will also direct you through the steps to use the feature.

What is the Torizon Secure Offline Updates Feature?​

Secure Offline Updates is a feature of Torizon. It supplements Torizon Remote Updates, using the same technology stack: OSTree and Aktualizr. Offline Updates brings the capability to perform secure updates to Torizon OS based devices that may not be able to update remotely. For example, devices that rarely have an internet connection, have limited bandwidth, have no network connection at all, or are permanently on an airgapped network.

You can learn more about updates with Torizon on our overview article, and for more in depth knowledge, read the Torizon Remote Updates Technical Overview.

Main Features​

With the Offline Updates feature it is possible to:

  • Execute full-stack, secure and reliable updates on devices without an internet connection
  • Automatically trigger the update on a device with an update medium - USB, SD Card, or network volumes.
  • Perform synchronous updates - both the OS and the Application as a single component
  • Automatically rollback to the last working version of the OS or the application in case the update fails
  • Block updates from happening from the application’s side, in case you have a critical application that cannot stop for an update to take place
  • Create a single Lockbox for multiple devices with different hardware

Terminology​

Many of the names and technologies used in Remote Updates are also used in Offline Updates. However, we introduce some new terminology to talk about offline updates and how they are secured:

Lockbox​

The Lockbox is the main thing to understand when using Offline Updates. When you deliver an update using Torizon Remote Updates, it's a bit like sending an electronic funds transfer: you use the Torizon Cloud to order the device to update to a particular software version, and then we take care of the rest, using secured communications channels (mTLS) and signed metadata that ensures the device can validate the software and installation instructions it receives. For offline updates, there's no direct communication between the platform and the device, so we need an alternate mechanism to provide the same security guarantees: that's what we call the Lockbox.

A Lockbox is a collection of binary files, installation instructions, and software repository metadata. You can put it on a USB stick and carry it to a device, and the device will have everything it needs to make sure that the contents of that Lockbox haven't been tampered with. Lockboxes derive from Uptane PURE-2, designed for securing updates of safety-critical automotive software.

First Steps​

Prerequisites​

In order to perform your first steps with offline updates, you should satisfy all of the following prerequisites:

The Update Process​

The update processes of a device with Offline Updates and Remote Updates are similar since both are based on the same technology stack. You can see the workflow in the diagram below:

Offline Update Workflow

Creating the Packages​

The first step is to upload your OS Image and/or Application to the Torizon Cloud. Learn how Torizon manages Software Packages reading the Feature Overview

You can create a Torizon Application Package from the web UI, TorizonCore Builder or an IDE with Extension for Torizon:

Remember that you will also have to push your application to a docker registry, so the device can download it.

To create a Torizon OS Package, you should use TorizonCore Builder to push images built by you or other collaborators. Remember, you can always use Toradex's provided images out-of-the-box.

info

If you want to deploy simultaneously the OS and application with Torizon Cloud, you should use the synchronous update feature of our Torizon Cloud, instead of customizing your image to bundle containers to a Torizon OS image, since its bundled containers are not capable of being deployed without Toradex Easy Installer.

caution

To be compatible with Secure Offline Updates, it must be canonicalized, which can be done using the --canonicalize argument.

If a name for the package is explicitly specified with --package-name, then it should also end with .lock.yml or .lock.yaml. Moreover, due to some known limitations, the package name must only employ basic ASCII characters excluding control ones and those in the set \/:*?" ><|, otherwise the Lockbox generation may fail later.

Defining the Lockbox​

The next step is to define the Lockbox in the Torizon Cloud Web UI. This is the step where you decide exactly what software will go into the Lockbox, so that the Torizon Cloud can generate signed install instructions allowing your devices to trust the update.

To define a Lockbox you have to:

  1. Select the desired OS and/or application packages
  2. Give it a name, so you can refer to it in future steps

Creating the Lockbox​

Once the Lockbox has been defined, you are ready to use TorizonCore Builder to download the files, metadata, and signatures that the device uses for validation. Use TorizonCore Builder for this step, and all the required files will be downloaded onto your workstation.

You can then copy the files onto a storage medium of your choice.

Deploying the Offline Update​

Now that you have the update medium, you can take it to the device and deploy the update:

  1. Insert the update medium (loaded with the Lockbox) into the device
  2. Wait for the update to finish
  3. Remove the update medium. At this point, the device is updated
info

The update process is fully automated and no user intervention is required at any time. If you are performing an OS or synchronous update, the board will automatically reboot once.

tip

Your device must be configured for offline updates for this to work. You'll need to follow the detailed instructions on configuration, to make sure the path to the storage medium's mount location is correct.

Webinars​

Toradex has presented webinars about Secure Offline and Online Updates and you can watch them on demand.

Secure Offline and Online Updates for Linux Devices​

Learn more about this webinar on the landing page, or watch it below:



Send Feedback!