Firmware security

  This page is monitored by the OLPC team.

Please copy/paste "{{Translationlist | xx | origlang=en | translated={{{translated}}}}}" (where xx is ISO 639 language code for your translation) to Firmware security/translations

HowTo [ID# 61321]  +/-

NOTE: The contents of this page are not set in stone, and are subject to change! This page is a draft in active flux ... Please leave suggestions on the talk page.

Scope

This page describes the role of Open Firmware in BitFrost security on XO.

Goals

1. Run recovery firmware if primary firmware is bad
2. No access to ok prompt without developer key
3. Firmware update images must be signed
4. Boot images must be signed
5. Unactivated laptops will only boot the activation image
6. Boot alternate OS image if primary OS image is bad

Files

The files listed below are on NAND FLASH in JFFS2. The zip archives listed below must be created without compression (-n option) and without paths (-j option). Implementation notes and rationale are in italics.

• Primary images are in /boot, secondary images are in /boot-alt

  At the start of an upgrade process, boot is copied to boot-alt; this doesn't need to be atomic. When upgrade is complete and validated, the upgraded files will be moved atomically to /boot. The atomic substitution requires /boot to be a symlink to the 'real' boot directory. See Early Boot for more details on the upgrade process.

• The activation lease is named "/security/lease".

  The activation lease is in the firmware activation lease format

• The developer key is named "/security/develop.key".

  The developer key is in the firmware developer key format

  Once the developer key has been read for the first time, it is copied by firmware into reserved space in the flash.

• The normal OS image is in "/boot/runos.zip", containing "os.img" and "os.key", and "/boot/runrd.zip", containing "rd.img" and "rd.key". An activation OS image is in "/boot/actos.zip", containing "os.img" and "os.key", and "/boot/actrd.zip", containing "rd.img" and "rd.key".
  • os.img is one of the load formats that OFW supports, e.g. Linux bzImage
  • os.key is in the firmware key format
  • rd.img is a ramdisk image in a format supported by the kernel in os.img (typically initramfs)
  • rd.key is in the firmware key format
  • runrd.zip/actrd.zip may be omitted, in which case runos.zip/actos.zip is booted without a ramdisk.

    Rationale: The ramdisk is only used during activation and certain upgrades. As an optimization, we can skip authenticating and loading the ramdisk when it is not needed in order to simplify and speed up boot. In practice runrd.zip is likely to be a symlink which can be easily deleted and recreated when needed.

• The new firmware image is "/boot/bootfw.zip", containing "bootfw.img" and "bootfw.key"
  • bootfw.img is the usual OFW image format
  • bootfw.key is in the firmware key format
• The backup files in /boot-alt have the same names and are in the same formats as /boot.

On USB disk or SD card, the files are as follows:

• Only one directory, /boot, containing runos.zip, bootfw.zip, and an optional runrd.zip as before

  Security dictates that we boot from an authenticated filesystem. Rather than have OFW authenticate the full USB/SD contents, we'll boot from an authenticated ramdisk, which can then authenticate whatever other files it needs (if any) from the USB/SD disk. For this reason, there should always be a ramdisk, but it may be monolithic with the kernel in runos.zip rather than in a separate runrd.zip file.

  We should be careful to ensure that the files are authenticated after they have been loaded into memory, to prevent attacks involving switching files between authentication and later use.

Process

1. If OFW fails to come up correctly, a firmware recovery procedure is attempted - details TBD.
2. In the following, the "primary" images are the files in /boot, and the "secondary" images are the files in /boot-alt, unless the "O" gamepad key is held down during boot, in which case the roles reverse: the primary files come from /boot-alt, and the secondary files come from /boot.
3. If the SPI FLASH lockout latch is already set (as with a warm boot), OFW skips to step 7.
4. OFW checks for a new firmware image in the /boot directory on an attached USB, then SD, device. If one exists and verifies, OFW reflashes itself and reboots.

   Upgrade USB keys may contain firmware-only upgrades.

5. OFW checks for a new firmware image in the primary directory in the NAND flash. If one exists and verifies, OFW reflashes itself and reboots.
6. OFW locks out further SPI FLASH writing with the hardware lock.
7. If a valid developer key is present, OFW enters non-secure mode, where it behaves as it currently does. Otherwise ...
8. If the activation key is present and valid, the boot filenames will be runos.zip and (if present) runrd.zip. Otherwise, the boot filenames will be actos.zip and (if present) actrd.zip.
9. If the activation key is present and valid, we will attempt to verify and boot from the boot files in /boot on an attached USB, then SD, device.
10. OFW verifies and boots from the boot files in the primary directory.
11. OFW verifies and boots from the boot files in the secondary directory.
12. If none of the above booting steps succeed, OFW displays an error screen and halts.
13. During OS startup, the OS should check the firmware version and if it matches or is greater than the version in the new firmware image file on disk, the OS should delete or rename that file so the firmware won't see it the next time.

Usage notes

• After boot, userland can determine the source from the OFW device tree - /ofw/chosen/bootpath is the OFW device specifier of the kernel file, /ofw/chosen/ramdisk is the device specifier of the initrd file (if any), and /ofw/chosen/bootargs is the cmdline. This can be used to determine whether activation is needed (actos.zip) or whether booting is being performed from the secondary source (boot-alt/*).
• Although outside the scope of this spec, there are primary and secondary filesystem roots in /run/a and /run/b corresponding to the kernels in /boot and /boot-alt. /boot/runrd.img will typically be absent to speed boot. However, /boot-alt/runrd.img will typically be required in order to switch to /run/b so that kernel and userland match. When we clone /boot into /boot-alt at the beginning of an upgrade, we link in an appropriate /boot-alt/runrd.img (See Early Boot for more information.)
• When the alternate kernel is booted and we've switched into /run/b, we can either:
  1. add a /boot/runrd.zip link so that if we reboot into the primary we can switch the filesystem back /run/a, or
  2. Swap /boot and /boot-alt, making future boots start this kernel. This option is preferred. We should ensure that we've done another upgrade before we try to boot into a different kernel again.
• We will typically use hard or soft links to avoid storing multiple os and ramdisk images. The current plan is to actually have only one kernel and one ramdisk image; the ramdisk will look at how it was invoked to determine whether this is an upgrade, activation, or alternate boot.

Summary

Plan of record

Case	File	Expiry	Signed Object	Signature (ASCII)	Computation	Key	Effect on Success
OS/Ramdisk Images	/boot{,-alt}/ {run,act}{os,rd}.zip	-	{os,rd}.img in .zip	{os,rd}.key in .zip	sha256->rsa256	OLPC_OS_Key	Load image
Firmware Images	/boot/bootfw.zip	-	bootfw.img in .zip	bootfw.key in .zip (x2)	sha256->rsa256, whirl->rsa256	OLPC_FW_Key	Update firmware
Developer	/security/develop.key	-	<SN>:<UU>:Time0	keydata on sig line	rsa256	OLPC_FW_Key	Unlock firmware
Lease	/security/lease	time on sig line	<SN>:<UU>:<Expiry>	keydata on sig line	rsa256, check time	OLPC_OS_Key	Use runos not actos

---

Alternative Plan

Case	File	Expiry	Signed Object	Signature (ASCII)	Computation	Key	Effect on Success
OS/Ramdisk Images	/boot{,-alt}/ {run,act}{os,rd}.zip	-	data.img in .zip	data.sig in .zip	sha256->rsa256	OLPC_OS_Key	Load image
Firmware Images	/boot/bootfw.zip	-	data.img in .zip	data.sig in .zip (2 lines)	sha256->rsa256, whirl->rsa256	OLPC_FW_Key	Update firmware
Developer	/security/develop.sig	-	<SN>:<UU>:Time0	keydata on sig line	rsa256	OLPC_FW_Key	Unlock firmware
Lease	/security/lease.sig	time on sig line	<SN>:<UU>:<Expiry>	keydata on sig line	rsa256, check time	OLPC_OS_Key	Use runos not actos

Rationale:

• .sig, not .key, because it contains signatures, not keys
• no need to reiterate the name for the .img file; it just complicates the code
• I'm still thinking through this, so don't be surprised if I change my mind (wmb)

---

Plan 3 from Outer Space

Case	File	Expiry	Signed Object	Signature (binary)	Computation	Key	Effect on Success
OS/Ramdisk Images	/boot{,-alt}/ {run,act}{os,rd}.zip	-	data.img in .zip	data_sha256.rsa in .zip	sha256->rsa256	OLPC_OS_Key	Load image
Firmware Images	/boot/bootfw.zip	-	data.img in .zip	data_sha256.rsa and data_whirlpool.rsa in .zip (2 files)	sha256->rsa256, whirl->rsa256	OLPC_FW_Key	Update firmware
Developer	/security/develop.zip	-	<SN>:<UU>:Time0	<SN>.rsa	rsa256	OLPC_FW_Key	Unlock firmware
Lease	/security/lease.zip	<SN>.tim in .zip	<SN>:<UU>:<Expiry>	<SN>.rsa	rsa256, check time	OLPC_OS_Key	Use runos not actos

Rationale:

• The only "package" format is .zip; the archive member name describes the item
• The signature files are in binary, the extension identifes the format as rsa, the base name identifies what is signed and its hash if any
• The <SN> in the <SN>.rsa files permits there to be signatures for multiple machines in one .zip file.

Notes

• I am assuming that the primary use of USB/SD boot is to do OS, firmware, or activity upgrades where bandwidth is a limitation. These can easily be done with the mechanism provided by just sticking a (properly signed) "magic upgrade key" into the USB port and power-cycling.
• USB probing is time-consuming and perilous (although SD is not). At some point (after manufacturing processes are fixed) we'll only try to boot from USB if the 'X' game key is pressed during boot.
• We could be more user-friendly by detecting "failed boot after linux kernel invocation" in some way, and automatically booting from the backup in this case. This seems like post-FRS work.
• Firmware RTC *must be UTC*. Quanta must set the RTC to UTC at the factory; antitheft server must sync to UTC during antitheft interaction.