OS Image Digestor

english | español

HowTo [ID# 187879]  +/-

Cyclists visiting "egg" digesters on Deer Island

The OS Image Digestor is a short shell script which can be used to create OFW Placement Control Files, which are in turn used during system reflash processes. By sending such files back to OLPC's main office for signing, it is possible for deployments to build customized images that can be used in the secure reflash process without requiring that OLPC itself directly manage the system images. This eliminates a critical point of latency in the development process of secure-reflashable customized builds by OLPC's customer base.

OLPC OS Image Digestor

• maintainer: Erik Garrison <erik@laptop.org>
• repository: [1]

 git clone git://dev.laptop.org/users/erik/image-digestor

Objective

To simplify the process of producing a secure-reflash capable build so that any deployment with the infrastructure to modify an existing OS image can easily request the files necessary to securely reflash it without sending OLPC a complete image file.

Summary

Secure reflash is the process of copying a system image onto a laptop with the OLPC security system enabled. The scripts in this repository can be used to create OpenFirmware (OFW) update scripts from images which are destined for use during the secure reflash of OLPC XO laptops. These scripts are signed using OLPC infrastructure to produce a file (fs.zip) which must be included alongside any OS image during the secure reflash process.

Usage

Given an OS image file which contains a jffs2 filesystem:

 $ ./image-digestor.sh <image_file_name>

This produces <image_file_name>.ofw_update_script. For use in secure reflash, the resulting update script must be included as data.img in an OLPC-signed fs.zip. At present this requires contact with OLPC's main office.

The common Linux utilities dd and sha256sum are required. These are present in the 'coreutils' package in Fedora, Ubuntu, and Debian, so this should be no issue on most systems.

Background and definitions

• OFW Placement Control File

A reflash script, the bulk of which is a list of sha256sums (digests) for each erase block (128KiB chunk) of the image to be flashed. During the update process OFW uses the shasums to check the validity of each block as it is copied onto the internal memory (NAND flash) of the XO.

• Secure update procedure

Secure reflash requires that the OFW update script be signed with a secure private key. The results are stored in a file called fs.zip, which contains the update script (data.img), a signature dependent on OLPC's private key and the update script (data.sig), and a file indicating the build version name (version.txt). This file is then placed alongside the image to be flashed on USB flash media, and is read during the reflash process to validate the build. The firmware only continues with the reflash if the signature file matches the update script.

Note that post-boot security is independent from the secure reflash system. On a security-enabled XO, separate checks occur at boot to verify that the kernel and initramfs are valid. Boot will proceed provided the image which has been built contains both the kernel and initramfs signatures (/boot/{runos.zip,runrd.zip}).

Further documentation of firmware-level security systems on the XO can be found at Firmware security.