Flesh out armory transparency story (#169)

Author: AlCutter

binary_transparency/firmware/cmd/usb_armory/image_builder/build.sh

@@ -0,0 +1,89 @@
+# Copyright 2020 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# build.sh is a utility to create ext4 filesystem images for use in the
+# firmware partition of SD Cards created for USB Armory devices.
+
+#!/bin/bash
+usage() {
+    echo "Usage: $0 -u <path_to_unikernel> -o <output_file>" 1>&2
+    exit 1
+}
+
+clean() {
+    if [ ! -z "${MNT}" ]; then
+    fusermount -u ${MNT}
+    rmdir ${MNT}
+    fi
+}
+
+
+while getopts ":u:o:f" opt; do
+case ${opt} in
+    u )
+    u=${OPTARG}
+    ;;
+    o )
+    o=${OPTARG}
+    ;;
+    f )
+    f=1
+    ;;
+    * )
+    usage
+    ;;
+esac
+done
+shift $((OPTIND - 1))
+
+if [ -z "${u}" ] || [ -z "${o}" ]; then
+    usage
+fi
+
+if [ -f  "${o}" ] && [ -z "${f}" ]; then
+    echo "Output file ${o} already exists, use -f to force overwrite"
+    if [ -z ${f} ]; then
+        exit 2
+    fi
+fi
+
+trap clean EXIT
+
+set -e
+MNT=$(mktemp --directory /tmp/build_image-XXXXX)
+
+SIZE=$(stat --format='%s' ${u})
+OVERHEAD=2560000
+let BLOCKS=(${SIZE}+${OVERHEAD})/1024
+
+mkfs.ext4 ${o} -q -b 1024 -L firmware ${BLOCKS}
+fuse2fs -o fakeroot ${o} ${MNT}
+
+mkdir ${MNT}/boot
+cp ${u} ${MNT}/boot/unikernel
+h=$(sha256sum ${u} | awk '{print $1}')
+sed -- "s/@HASH@/${h}/" > ${MNT}/boot/armory-boot.conf <<EOF
+{
+    "unikernel": [
+        "/boot/unikernel",
+        "@HASH@"
+    ]
+}
+EOF
+
+fusermount -u ${MNT}
+unset MNT
+
+echo "Created image in ${o}:"
+ls -lh ${o}

binary_transparency/firmware/devices/usb_armory/README.md

@@ -39,8 +39,8 @@ The on-disk partition layout will be:
 index | name       | size    | format | notes
 ------|------------|---------|--------|-----------------------------------------------
 1     | boot       | 10M     | raw    | Must cover disk bytes 1024 onwards as we'll directly write the bootloader here.
-2     | proof      | 512KB   | ext4   | EXT4 filesytem for storing a serialised proof bundle
-3     | firmware   | 64MB+   | ext4   | EXT4 filesystem containing the bootable firmware  image, armory boot config, and DTD file.
+2     | proof      | 512KB   | ext4   | EXT4 filesystem for storing a serialised proof bundle
+3     | firmware   | 64MB+   | ext4   | EXT4 filesystem containing the bootable firmware image, armory boot config, etc.
 
 ### Preparing the SD Card
 
@@ -80,7 +80,7 @@ Model: Generic- Micro SD/M2 (scsi)
 Disk /dev/sdc: 15931539456B
 Sector size (logical/physical): 512B/512B
 Partition Table: msdos
-Disk Flags: 
+Disk Flags:
 
 Number  Start      End         Size       Type     File system  Flags
  1      512B       10240511B   10240000B  primary               lba
@@ -108,9 +108,9 @@ To compile the bootloader itself, run the following command in the `bootloader`
 directory:
 
 ```bash
-# Note that START_KERNEL corresponds to the offset of the firmware partition, 
+# Note that START_KERNEL corresponds to the offset of the firmware partition,
 # and START_PROOF is the offset of the proof partition
-make CROSS_COMPILE=arm-none-eabi- TARGET=usbarmory imx BOOT=uSD START_KERNEL=10753536 START_PROOF=10240512 LEN_KERNEL=89246720 
+make CROSS_COMPILE=arm-none-eabi- TARGET=usbarmory imx BOOT=uSD START_KERNEL=10753536 START_PROOF=10240512 LEN_KERNEL=89246720
 ```
 
 If successful, this will create a few files - the one we're interested in is
@@ -130,7 +130,8 @@ $ sudo dd if=armory-boot.imx of=/dev/myscard bs=512 seek=2 conv=fsync,notrunc
 Firmware images
 ---------------
 
-Currently, the bootloader can only chain to a Linux kernel.
+Currently, the bootloader can only chain to either a Linux kernel, or a
+bare-metal ELF unikernel (only tested with tamago-example thus far).
 
 There are some invariants which must hold for this chain to work:
 1. The `firmware` partition MUST be located at the precise offset mentioned
@@ -140,18 +141,45 @@ There are some invariants which must hold for this chain to work:
     following contents:
     * `armory-boot.conf` - a JSON file which tells the bootloader which files
       to load
-    * a valid ARM linux Kernel image
-    * a valid DTB file
-   Note that the `armory-boot.conf` file also contains SHA256 hashes of the
-   kernel and DTB files, and these MUST be correct.
+    * Either:
+        * to boot a Linux Kernel:
+           * a valid ARM linux Kernel image
+           * a valid DTB file
+        * to boot ELF unikernel:
+           * a valid ARM bare-metal ELF binary/unikernel
 
+   Note that the `armory-boot.conf` file also contains SHA256 hashes of
+   all files referenced, and these MUST be correct.
+
+To aid in the creation of valid firmware images, use the
+`[cmd/usb_armory/image_builder/build.sh](/binary_transparency/firmware/cmd/usb_armory/image_builder/build.sh)`
+script, e.g.:
+
+```bash
+$ ./cmd/usb_armory/image_builder/build.sh -u ./testdata/firmware/usb_armory/example/tamago-example -o /tmp/armory.ext4
+
+/tmp/armory.ext4: Writing to the journal is not supported.
+Created image in /tmp/armory.ext4:
+-rw-rw-r-- 1 al al 13M Nov 30 10:39 /tmp/armory.ext4
+
+```
+
+For now, this image can be written to the target partition using `dd`, e.g.:
+
+```bash
+$ sudo dd if=/tmp/armory.ext of=/dev/my_sdcard3 bs=1M conf=fsync
+```
+
+TODO(al): consider updating `flash_tool` with support for writing these images.
+
+### Linux
 
 > :frog: The [Armory Debian Base Image](https://github.com/f-secure-foundry/usbarmory-debian-base_image/releases)
 > is a good source for the kernel (zImage) and dtb files.
 >
 > You can decompress and mount the image to access the files like so:
 > ```bash
-> # decompress image 
+> # decompress image
 > $ xz -d usbarmory-mark-two-usd-debian_buster-base_image-20200714.raw.xz
 > # mount image with loopback:
 > # note the offset parameter below - the raw file is a complete disk image, this
@@ -170,7 +198,7 @@ There are some invariants which must hold for this chain to work:
 > -rwxr-xr-x 1 root root 6726952 Oct 20 17:13 zImage-5.4.72-0-usbarmory
 > ```
 
-An example `armory-boot.conf` file is:
+An example `armory-boot.conf` file configured to boot a Linux kernel is:
 
 ```json
 {
@@ -188,6 +216,24 @@ An example `armory-boot.conf` file is:
 
 TODO(al): Consider wrapping this up into a script.
 
+### ELF unikernel
+
+> :frog: A good sample unikernel is the
+> [tamago-example](https://github.com/f-secure-foundry/tamago-example)
+> application.
+
+An example `armory-boot.conf` file configured to boot an ELF unikernel is:
+
+```json
+{
+  "unikernel": [
+    "/boot/tamago-example",
+    "aceb3514d5ba6ac591a7d5f2cad680e83a9f848d19763563da8024f003e927c7"
+  ]
+}
+```
+
+
 Booting
 -------
 
@@ -211,3 +257,12 @@ Dentry cache hash table entries: 65536 (order: 6, 262144 bytes, linear)
 ...
 ```
 
+
+Firmware Measurement
+--------------------
+
+The 'firmware measurement' hash for the USB Armory is defined to be the SHA256
+hash of the raw bytes of the `ext4` **filesystem image** stored in the
+'firmware' partition of the SD Card.
+
+Note that this _may well_ be a different size than the partition itself.

binary_transparency/firmware/devices/usb_armory/bootloader/Makefile

@@ -25,7 +25,7 @@ endif
 APP := armory-boot
 GOENV := GO_EXTLINK_ENABLED=0 CGO_ENABLED=0 GOOS=tamago GOARM=7 GOARCH=arm
 TEXT_START := 0x90010000 # ramStart (defined in imx6/imx6ul/memory.go) + 0x10000
-GOFLAGS := -tags ${BUILD_TAGS} -ldflags "-s -w -T $(TEXT_START) -E _rt0_arm_tamago -R 0x1000 -X 'main.Build=${BUILD}' -X 'main.Revision=${REV}' -X 'main.Boot=${BOOT}' -X 'main.StartKernel=${START_KERNEL}' -X 'main.StartProof=${START_PROOF}' -X 'main.LenKernel=${LEN_KERNEL}' -X 'main.PublicKeyStr=${PUBLIC_KEY}'"
+GOFLAGS := -tags ${BUILD_TAGS} -ldflags "-s -w -T $(TEXT_START) -E _rt0_arm_tamago -R 0x1000 -X 'main.Build=${BUILD}' -X 'main.Revision=${REV}' -X 'main.Boot=${BOOT}' -X 'main.StartKernel=${START_KERNEL}' -X 'main.StartProof=${START_PROOF}' -X 'main.PublicKeyStr=${PUBLIC_KEY}'"
 
 .PHONY: clean
 

binary_transparency/firmware/devices/usb_armory/bootloader/boot.go

@@ -64,7 +64,6 @@ func bootKernel(kernel []byte, dtb []byte, cmdline string) {
 // This function implements a _very_ simple ELF loader which is suitable for
 // loading bare-metal ELF files like those produced by TamaGo.
 func bootELFUnikernel(img []byte) {
-	dma.Init(dmaStart, dmaSize)
 	mem, _ := dma.Reserve(dmaSize, 0)
 
 	f, err := elf.NewFile(bytes.NewReader(img))

binary_transparency/firmware/devices/usb_armory/bootloader/ext4.go

@@ -28,6 +28,24 @@ type Partition struct {
 	_offset int64
 }
 
+// GetExt4FilesystemSize returns the size in bytes of the ext4 filesystem stored
+// in the partition.
+// Note that this may not be the same as the size of the disk partition which
+// contains the filesystem.
+func (d *Partition) GetExt4FilesystemSize() (uint64, error) {
+	_, err := d.Seek(ext4.Superblock0Offset, io.SeekStart)
+	if err != nil {
+		return 0, err
+	}
+
+	sb, err := ext4.NewSuperblockWithReader(d)
+	if err != nil {
+		return 0, err
+	}
+
+	return uint64(sb.BlockSize()) * sb.BlockCount(), nil
+}
+
 func (d *Partition) getBlockGroupDescriptor(inode int) (bgd *ext4.BlockGroupDescriptor, err error) {
 	_, err = d.Seek(ext4.Superblock0Offset, io.SeekStart)
 

binary_transparency/firmware/devices/usb_armory/bootloader/ft.go

@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"log"
 	"time"
 
 	"github.com/f-secure-foundry/tamago/soc/imx6/dcp"
@@ -33,14 +34,20 @@ func loadBundle(p *Partition) (api.ProofBundle, error) {
 	return bundle, nil
 }
 
-// hashPartition calculates the SHA256 of the first numBytes of the partition.
-func hashPartition(numBytes int64, p *Partition) ([]byte, error) {
-	fmt.Println("Reading partition at offset %d...", p.Offset)
+// hashPartition calculates the SHA256 of the whole partition.
+func hashPartition(p *Partition) ([]byte, error) {
+	log.Printf("Reading partition at offset %d...\n", p.Offset)
+	numBytes, err := p.GetExtFilesystemSize()
+	if err != nil {
+		return nil, fmt.Errorf("failed to get partition size: %w", err)
+	}
+	log.Printf("Partition size %d bytes\n", numBytes)
+
 	if _, err := p.Seek(0, io.SeekStart); err != nil {
 		return nil, fmt.Errorf("failed to seek: %w", err)
 	}
 
-	bs := int64(1<<20)
+	bs := uint64(1 << 16)
 	rc := make(chan []byte, 10)
 	hc := make(chan []byte)
 
@@ -50,7 +57,7 @@ func hashPartition(numBytes int64, p *Partition) ([]byte, error) {
 		if err != nil {
 			panic(fmt.Sprintf("Failed to created hasher: %q", err))
 		}
-		for b := range(rc) {
+		for b := range rc {
 			if _, err := h.Write(b); err != nil {
 				panic(fmt.Errorf("failed to hash: %w", err))
 			}
@@ -72,14 +79,13 @@ func hashPartition(numBytes int64, p *Partition) ([]byte, error) {
 		if err != nil {
 			return nil, fmt.Errorf("failed to read: %w", err)
 		}
-		rc<-b[:bc]
+		rc <- b[:bc]
 
-		numBytes -= int64(bc)
+		numBytes -= uint64(bc)
 	}
 	close(rc)
 
-	fmt.Printf("Finished reading, hashing in %s\n", time.Now().Sub(start))
+	log.Printf("Finished reading, hashing in %s\n", time.Now().Sub(start))
 	hash := <-hc
 	return hash[:], nil
 }
-

binary_transparency/firmware/devices/usb_armory/bootloader/main.go

@@ -12,7 +12,6 @@ package main
 
 import (
 	"fmt"
-	"log"
 	"strconv"
 
 	"github.com/f-secure-foundry/tamago/board/f-secure/usbarmory/mark-two"
@@ -26,12 +25,9 @@ var Revision string
 
 var Boot string
 var StartKernel string
-var LenKernel string
 var StartProof string
 
 func init() {
-	log.SetFlags(0)
-
 	if err := imx6.SetARMFreq(900); err != nil {
 		panic(fmt.Sprintf("WARNING: error setting ARM frequency: %v\n", err))
 	}
@@ -63,15 +59,10 @@ func main() {
 	if err != nil {
 		panic(fmt.Sprintf("invalid kernel partition start offset: %v\n", err))
 	}
-	kernelLen, err := strconv.ParseInt(LenKernel, 10, 64)
-	if err != nil {
-		panic(fmt.Sprintf("invalid kernel partition length : %v\n", err))
-	}
 	proofOffset, err := strconv.ParseInt(StartProof, 10, 64)
 	if err != nil {
 		panic(fmt.Sprintf("invalid proof partition start offset: %v\n", err))
 	}
-
 	partition := &Partition{
 		Card:   card,
 		Offset: kernelOffset,
@@ -80,7 +71,7 @@ func main() {
 		panic(fmt.Sprintf("invalid configuration: %v\n", err))
 	}
 
-	h, err := hashPartition(kernelLen, partition)
+	h, err := hashPartition(partition)
 	if err != nil {
 		panic(fmt.Sprintf("failed to hash kernelPart: %w\n", err))
 	}
@@ -110,7 +101,7 @@ func main() {
 
 	switch {
 	case len(conf.Kernel) > 0:
-		fmt.Println("Loaded kernel config")
+		fmt.Printf("Loaded kernel config\n")
 		kernel, err := partition.ReadAll(conf.Kernel[0])
 		if err != nil {
 			panic(fmt.Sprintf("invalid kernel path: %v\n", err))
@@ -140,7 +131,7 @@ func main() {
 		bootKernel(kernel, dtb, conf.CmdLine)
 
 	case len(conf.Unikernel) > 0:
-		fmt.Println("Loaded unikernel config")
+		fmt.Printf("Loaded unikernel config\n")
 		unikernel, err := partition.ReadAll(conf.Unikernel[0])
 		if err != nil {
 			panic(fmt.Sprintf("invalid unikernel path: %v\n", err))

binary_transparency/firmware/testdata/firmware/usbarmory/example/tamago-example

@@ -12,7 +12,7 @@ require (
 	github.com/dsoprea/go-ext4 v0.0.0-20190528173430-c13b09fc0ff8
 	github.com/dsoprea/go-logging v0.0.0-20200710184922-b02d349568dd // indirect
 	github.com/ethereum/go-ethereum v1.9.24
-	github.com/f-secure-foundry/tamago v0.0.0-20201127101424-e0d521d1ec51
+	github.com/f-secure-foundry/tamago v0.0.0-20201127230944-9b6478583a99
 	github.com/fatih/color v1.9.0 // indirect
 	github.com/go-sql-driver/mysql v1.5.0
 	github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b

go.mod

@@ -219,6 +219,8 @@ github.com/f-secure-foundry/tamago v0.0.0-20201126222218-ecc3aa53ae88 h1:YbymNPH
 github.com/f-secure-foundry/tamago v0.0.0-20201126222218-ecc3aa53ae88/go.mod h1:+xmhdYxGfaNhWUZ/F1mbwFu38H73slg/k/oPjOL7tc8=
 github.com/f-secure-foundry/tamago v0.0.0-20201127101424-e0d521d1ec51 h1:pewB+4yHr4ivS1KAfQx3jQtld96ceV2ORqpi7xZ3s/Y=
 github.com/f-secure-foundry/tamago v0.0.0-20201127101424-e0d521d1ec51/go.mod h1:+xmhdYxGfaNhWUZ/F1mbwFu38H73slg/k/oPjOL7tc8=
+github.com/f-secure-foundry/tamago v0.0.0-20201127230944-9b6478583a99 h1:kMeONmx7TxN2Wgn6aURmObm2htgfey6luj3wJiGkYpM=
+github.com/f-secure-foundry/tamago v0.0.0-20201127230944-9b6478583a99/go.mod h1:+xmhdYxGfaNhWUZ/F1mbwFu38H73slg/k/oPjOL7tc8=
 github.com/fatih/color v1.3.0/go.mod h1:Zm6kSWBoL9eyXnKyktHP6abPY2pDugNf5KwzbycvMj4=
 github.com/fatih/color v1.7.0 h1:DkWD4oS2D8LGGgTQ6IvwJJXSL5Vp2ffcQg58nFV38Ys=
 github.com/fatih/color v1.7.0/go.mod h1:Zm6kSWBoL9eyXnKyktHP6abPY2pDugNf5KwzbycvMj4=