Tock Tutorial 2023

Makefile

@@ -9,13 +9,13 @@
 .PHONY: check_mdbook check_mdbook_linkcheck check_mdbook_pagetoc check_prettier
 .PHONY: install_mdbook install_mdbook_linkcheck install_mdbook_pagetoc install_prettier
 
-SHELL = /bin/bash
+SHELL = /usr/bin/env bash
 
 # Configuration
 MDBOOK_VERSION := 0.4.32
 MDBOOK_LINKCHECK_VERSION := 0.7.7
 MDBOOK_PAGETOC_VERSION := 0.1.7
-PRETTIER_VERSION := 2.3.2
+PRETTIER_VERSION := 3.0.0
 
 # For CI, use local install; for normal users system install
 # (already in PATH) is fine

book.toml

@@ -10,3 +10,4 @@ additional-css = ["theme/pagetoc.css", "theme/pagetoc-tock.css"]
 additional-js  = ["theme/pagetoc.js"]
 
 [output.linkcheck]
+optional = true

dev-vm/README.md

@@ -0,0 +1,15 @@
+# Packer-based Tutorial / Development VM Image
+
+Build instructions:
+
+1. Install VirtualBox and ensure that you can run a VM as an unprivileged user.
+2. Install HashiCorp Packer.
+3. Run `packer build packer.json`, and grab a cup of coffee. It'll download a
+   large Ubuntu server image, and then magically type some boot arguments. The
+   Ubuntu installer may take about 10 minutes, depending on your hardware and
+   network connection.
+4. If it fails during installation because the installer crashed, there was
+   likely an intermittent network issue trying to download packages. Quit Packer
+   (`C-c`), wait until it finishes cleaning up, and then try again.
+5. `mv output-virtualbox-iso tock-dev-vm`
+6. `zip -r tock-dev-vm.zip tock-dev-vm`, avoid using .tar.\* for Windows

dev-vm/install-jlink.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+
+JLINK_VERSION="766"
+JLINK_URL="https://www.segger.com/downloads/jlink/JLink_Linux_V${JLINK_VERSION}_x86_64.deb"
+
+cat <<EOF
+Use of the "SEGGER JLink Software and Documentation pack" requires the
+acceptance of the following licenses:
+
+  - SEGGER Downloads Terms of Use
+    (${JLINK_URL})
+  - SEGGER Software Licensing
+    (https://www.segger.com/purchase/licensing/)
+
+This script can automatically download and install the JLink software
+for you, but you need to agree to the terms and conditions of the
+above licenses.
+
+If you agree to proceed, we will pass \`accept_license_agreement=accepted\`
+along with the request to download the software.
+
+EOF
+
+read -p "Do you want to proceed and accept the licenses? (y/N) " ACCEPT_LICENSE_PROMPT
+
+if [ "$ACCEPT_LICENSE_PROMPT" != "y" ]; then
+	echo "Aborting."
+	exit 1
+fi
+
+echo "Downloading the JLink software..."
+curl -o/tmp/jlink.deb --data accept_license_agreement=accepted "${JLINK_URL}"
+
+echo "Installing the JLink software..."
+sudo dpkg -i /tmp/jlink.deb
+
+echo "Reloading udev..."
+sudo udevadm control --reload-rules
+sudo udevadm trigger

dev-vm/packer.json

@@ -0,0 +1,65 @@
+{
+  "builders": [
+    {
+      "type": "virtualbox-iso",
+      "headless": false,
+
+      "boot_command": [
+        "<esc><wait>",
+        "e<wait>",
+        "<down><down><down><end>",
+        "<bs><bs><bs><bs><wait>",
+        "autoinstall ds=nocloud-net\\;s=http://{{ .HTTPIP }}:{{ .HTTPPort }}/ ---<wait>",
+        "<f10><wait>"
+      ],
+      "boot_wait": "1s",
+
+      "cpus": 4,
+      "memory": 4096,
+      "disk_size": 131072,
+
+      "guest_os_type": "Ubuntu_64",
+      "iso_checksum": "5e38b55d57d94ff029719342357325ed3bda38fa80054f9330dc789cd2d43931",
+      "iso_url": "http://releases.ubuntu.com/22.04.2/ubuntu-22.04.2-live-server-amd64.iso",
+
+      "shutdown_command": "sudo shutdown -h now",
+
+      "ssh_password": "tock",
+      "ssh_port": 22,
+      "ssh_read_write_timeout": "600s",
+      "ssh_timeout": "120m",
+      "ssh_username": "tock",
+
+      "vboxmanage": [
+        [
+          "modifyvm",
+          "{{.Name}}",
+          "--nat-localhostreachable1",
+          "on",
+	  "--vram",
+	  "128",
+	  "--graphicscontroller",
+	  "vboxvga",
+	  "--usb-ohci",
+	  "on"
+        ]
+      ],
+
+      "http_directory": "./"
+    }
+  ],
+  "post-processors": [
+  ],
+  "provisioners": [
+    {
+      "type": "file",
+      "source": "install-jlink.sh",
+      "destination": "/home/tock/install-jlink.sh"
+    },
+    {
+      "type": "shell",
+      "script": "provision-vm.sh"
+    }
+  ]
+}
+

dev-vm/provision-vm.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+echo "Provisioning Tock development VM..."
+cd /home/tock/
+
+git clone https://github.com/tock/tock ./tock
+git clone https://github.com/tock/libtock-c ./libtock-c
+git clone https://github.com/tock/libtock-rs ./libtock-rs
+
+echo "Installing rustup"
+curl https://sh.rustup.rs -sSf | sh -s -- -y
+
+echo "Installing Tockloader"
+sudo pip3 install tockloader

dev-vm/user-data

@@ -0,0 +1,126 @@
+#cloud-config
+
+# This is a modified version of [1], which installs automatically installs a
+# Ubuntu server, converts it into a Ubuntu Desktop installation, and performs
+# some further modifications to prepare it for the final provisioning stage
+# in Packer. It already includes some packages which are going to be needed
+# by the Tock provisioning script.
+#
+# [1]: https://github.com/canonical/autoinstall-desktop/blob/600a9ec2b9ef53a6945f11e227bbb680810ef6e3/autoinstall.yaml
+
+autoinstall:
+  # version is an Autoinstall required field.
+  version: 1
+
+  # The live-server ISO does not contain some of the required packages,
+  # such as ubuntu-desktop or the hwe kernel (or most of their depdendencies).
+  # The system being installed will need some sort of apt access. If you're
+  # behind a proxy, set that here:
+  #
+  # proxy: http://192.168.0.1:3142
+
+  # Add the ubuntu-desktop packages, along some other required or useful
+  # utilities:
+  packages:
+    - ubuntu-desktop
+    - ca-certificates
+    - cloud-guest-utils
+    - cloud-init
+    - curl
+    - e2fsprogs
+    - iproute2
+    - openssh-server
+    - perl
+    - python3
+    - python3-pip
+    - rsync
+    - sudo
+    - git
+    - vim
+    - htop
+    - nload
+    - tmux
+
+  # This adds the default snaps found on a 22.04 Ubuntu Desktop system.
+  # Any desired additional snaps may also be listed here.
+  snaps:
+    - name: firefox
+    - name: gnome-3-38-2004
+    - name: gtk-common-themes
+    - name: snap-store
+    - name: snapd-desktop-integration
+
+  # Create a Tock user. It is given password-less sudo below:
+  identity:
+    realname: 'Tock Developer'
+    username: tock
+    # Password is 'tock'
+    password: '$6$nRD/3FTV3bz/J8jV$.PSxDdqbuwNIyDZcSSXVy/q4/Pe.M4ehABFrf/smpPKKlinEgi7WyI1Vp6IJz7O2ZGkXovwdF3uODLfrUacvx1'
+    hostname: tockvm
+
+  # Install an OpenSSH server and ensure password-based login is enabled:
+  ssh:
+    install-server: yes
+    authorized-keys: []
+    allow-pw: yes
+
+  # Subiquity will, by default, configure a partition layout using LVM.
+  # The 'direct' layout method shown here will produce a non-LVM result.
+  storage:
+    layout:
+      name: direct
+
+  # Ubuntu Desktop uses the hwe flavor kernel by default.
+  early-commands:
+    - echo 'linux-generic-hwe-22.04' > /run/kernel-meta-package
+
+  late-commands:
+    # Enable the boot splash
+    - >-
+      curtin in-target --
+      sed -i /etc/default/grub -e
+      's/GRUB_CMDLINE_LINUX_DEFAULT=".*/GRUB_CMDLINE_LINUX_DEFAULT="quiet splash"/'
+    - curtin in-target -- update-grub
+
+    # Let NetworkManager handle network
+    - rm /target/etc/netplan/00-installer-config*yaml
+    - >-
+      printf "network:\n  version: 2\n  renderer: NetworkManager"
+      > /target/etc/netplan/01-network-manager-all.yaml
+
+    # Remove default filesystem and related tools not used with the suggested
+    # 'direct' storage layout.  These may yet be required if different
+    # partitioning schemes are used.
+    - >-
+      curtin in-target -- apt-get remove -y
+      btrfs-progs cryptsetup* lvm2 xfsprogs
+
+    # Remove other packages present by default in Ubuntu Server but not
+    # normally present in Ubuntu Desktop.
+    - >-
+      curtin in-target -- apt-get remove -y
+      ubuntu-server ubuntu-server-minimal byobu dmeventd finalrd kpartx
+      mdadm ncurses-term needrestart open-iscsi sg3-utils ssh-import-id
+      sssd thin-provisioning-tools sosreport open-vm-tools
+      motd-news-config lxd-agent-loader landscape-common
+
+    # Keep cloud-init, as it performs some of the installation on first boot.
+    - curtin in-target -- apt-get install -y cloud-init
+
+    # Finally, remove things only installed as dependencies of other things
+    # we have already removed.
+    - curtin in-target -- apt-get autoremove -y
+
+    # Enable password-less sudo for the tock user:
+    - "curtin in-target -- /bin/bash -c '\
+        mkdir -p /etc/sudoers.d; \
+	chmod 0755 /etc/sudoers.d; \
+	echo \"tock ALL=(ALL) NOPASSWD: ALL\" > /etc/sudoers.d/tock; \
+	chmod 0440 /etc/sudoers.d/tock; \
+	chown -Rf root:root /etc/sudoers.d; \
+	systemctl disable apt-daily.service; \
+	systemctl disable apt-daily.timer; \
+	systemctl disable apt-daily-upgrade.service; \
+	systemctl disable apt-daily-upgrade.timer; \
+	exit 0\
+      '"

src/SUMMARY.md

@@ -12,10 +12,20 @@ Tock OS Course
 
     - [Course Setup](./course_setup.md)
     - [Modules](./modules.md)
+      - [USB Security Key](./key-overview.md)
+        - [Setup](./key-setup.md)
+        - [HOTP Application](./key-hotp-application.md)
+        - [Encryption Oracle Capsule](./key-hotp-oracle.md)
+        - [Access Control](./key-hotp-access.md)
+      - [Kernel Boot](./boot.md)
+      - [Policies](./policies.md)
+      - [TicKV](./tickv.md)
+      - [USB Keyboard](./usb-hid.md)
       - [Application](./application.md)
+    - [Graduation](./graduation.md)
+    - [Deprecated](./deprecated.md)
       - [Important Client](./important_client.md)
       - [Capsule](./capsule.md)
-    - [Graduation](./graduation.md)
 
   - [Mini Tutorials](./tutorials/tutorials.md)
     - [Blink an LED](./tutorials/01_running_blink.md)