OS Image Digestor

Jump to: navigation, search
  english | español HowTo [ID# 256545]  +/-  

This tool is no longer relevant; the responsibility for signing images is generally now placed on deployments. See Build system.

Stop hand.png WARNING:
The content of this section is considered
It is preserved for historical or documenting reasons.

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


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.


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 Open Firmware (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.


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

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