> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thistle.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Thistle Verified Boot (TVB) on Orange Pi Zero 3

> Enable Linux Kernel signature verification using Thistle on Orange Pi Zero 3 (Allwinner H618)

<img src="https://mintcdn.com/thistletechnologies/MrBm0BC7xpW_ySdM/images/orangepiz3.png?fit=max&auto=format&n=MrBm0BC7xpW_ySdM&q=85&s=0bf51c20a39e2b0c629499c3eb75540d" alt="Orange Pi Zero 3" width="956" height="798" data-path="images/orangepiz3.png" />

This guide enables Thistle Verified Boot (TVB) on Orange Pi Zero 3 by validating a signed kernel before boot. If you only need OTA updates without boot‑time verification, follow the Quick path in the OTA guide instead: `hardware/orange_pi/zero3_ota_ab_update`.

## Board setup (vendor/community docs)

* General Orange Pi OS preparation and flashing microSD: [Orange Pi guide – prepare microSD](https://sbc-community.org/docs/general_guides/prepare_sd_card/)

## Default credentials

* **Orange Pi OS (official):** `oem` / `oem` (hostname: `orange-os.local`)

## Prerequisites

* Orange Pi Zero 3 running a Linux image with U‑Boot (Orange Pi OS)
* Access to Thistle Control Center (project with TVB signing enabled)

## Prepare Kernel for Signing

1. Copy the board’s kernel image to a workstation:

```bash theme={"dark"}
scp oem@orange-os.local:/boot/Image ./kernel || scp oem@orange-os.local:/boot/vmlinuz ./kernel
```

2. In Thistle Control Center, create a Signed Firmware bundle for TVB and upload `kernel`. Download `kernel-sig`.

<Note>
  TVB signing happens in Thistle Control Center; you do not need TRH on the workstation for TVB specifically. For OTA flows, see the OTA guide for TRH/TUC download commands.
</Note>

## Deploy Signature and Boot Script

1. Copy `kernel-sig` to the board’s boot partition:

```bash theme={"dark"}
scp kernel-sig oem@orange-os.local:/tmp/
ssh oem@orange-os.local 'sudo cp /tmp/kernel-sig /boot/kernel-sig && sudo chmod 644 /boot/kernel-sig && sync'
```

2. Ensure U‑Boot loads the kernel and checks the signature using a public key provisioned from your Thistle project. On Orange Pi OS, U‑Boot typically reads the boot partition at `/boot`, and places `boot.scr` there. Some builds use `extlinux.conf`; in that case, adapt your integration to call TVB verification before booting the kernel.

## Provision TVB Public Key

You must make the TVB public verification key available at boot. There are two supported approaches:

### Option A: Store the public key on the boot partition (recommended for Orange Pi OS)

1. On your workstation, copy the public key from Thistle Control Center (Settings → Access → Signed Firmware) into a file:

```bash theme={"dark"}
cat > tvb-pubkey.pem << 'EOF'
<paste the TVB public key here>
EOF
```

2. Copy it to the device and place it on the boot partition:

```bash theme={"dark"}
scp tvb-pubkey.pem oem@orange-os.local:/tmp/
ssh oem@orange-os.local 'sudo mv /tmp/tvb-pubkey.pem /boot/tvb-pubkey.pem && sudo chmod 0644 /boot/tvb-pubkey.pem && sync'
```

3. Ensure your U‑Boot boot script (boot.scr) refers to the same path (for example `/boot/tvb-pubkey.pem`) when verifying `kernel` against `kernel-sig` before booting. If you are using a custom script, keep the key, kernel, and signature paths consistent:

```text theme={"dark"}
/boot/kernel         # or /boot/Image or /boot/vmlinuz on your OS
/boot/kernel-sig     # signature downloaded from Thistle Control Center
/boot/tvb-pubkey.pem # public verification key (this step)
```

### Option B: Embed the public key into U‑Boot (advanced)

Embed the public key into the U‑Boot build when you manage and rebuild U‑Boot for your Orange Pi image. This approach avoids storing a separate key file but requires a U‑Boot rebuild and update on the device. At a high level:

* Generate or obtain the public key used by Thistle TVB (copy from Thistle Control Center) and convert it to the format your U‑Boot integration expects (for example, a DTS include)
* Add the key to the U‑Boot configuration (signature key node) as per your BSP’s verified‑boot flow
* Rebuild U‑Boot and update your boot media once

Only use this method if you control the U‑Boot build for your image; otherwise prefer Option A.

## Verify at Boot

Reboot and observe serial console logs. A valid signature results in normal boot; otherwise, boot fails and the system falls back per script.

## References

* Armbian overlays and device‑tree guidance for Allwinner H616/H618 families: community discussions on I²C/SPI overlays can help when adding peripherals: [I²C/SPI overlays](https://forum.armbian.com/topic/41365-orange-pi-zero-2w-overlay-i2c-spi-help/)
* General OS flashing: [Prepare microSD](https://sbc-community.org/docs/general_guides/prepare_sd_card/)