Skip to Content
DocumentationFirmwareOverview

Firmware

KeepKey firmware source is published under LGPLv3. Use the published release record for installable firmware and the candidate’s own evidence for development and testing.

What this section covers

CI test suite

Firmware CI includes host-side and emulator tests. Selected tests contribute OLED captures to the curated PDF report. The exact jobs, variants and tests depend on the workflow and candidate. A green run or a captured screen is not a substitute for required physical-device testing.

The Test Atlas identifies an inspected report and explains passed, skipped, pending and withheld coverage. Historical reports remain useful for their own builds; their counts do not describe current coverage.

Building from source

Select the exact release tag or commit before initializing dependencies and building. Follow the build instructions at that ref, including its pinned toolchain and submodules. Do not mix source from one candidate with dependency pins or an emulator from another.

The firmware repository  contains device and emulator build scripts. Available CI artifacts vary; a container image is not necessarily the libkkemu library used by Vault.

Verifying a release

Compare a downloaded file’s SHA-256 with the value recorded for that exact artifact. Reproducing a build is a separate check: compare the appropriate firmware payload with one built from the matching source and toolchain. A signed release header can differ from a local unsigned build.

A matching hash establishes file equivalence to a particular reference. It does not alone establish what is installed on a physical device or prove the source has no defects. Follow the update guide and keep the release record with your verification results.

Firmware verification workflow

Watch: Verify your firmware. Keep release authentication, reproducibility and device-reported evidence separate. Use the exact source revision and image variant that belong to your reference.

The published v7.14.3 release  supplies a Bitcoin-only image and records its source commit, pinned builder and payload hash. It is not the multi-chain update. Use KeepKey Desktop  and the appropriate update flow for your wallet.

Choose Bitcoin-only firmware

Watch this step.

  1. When supported setup shows Choose your KeepKey firmware, read the two options: Bitcoin-only and Multi-chain.
  2. For an existing wallet, confirm your written recovery backup with the non-destructive backup check before any firmware change.
  3. Read the warning about changing between firmware variants. Do not assume the switch preserves device state or access to other coins.
  4. Select Bitcoin-only, then Continue with Bitcoin-only. Follow the official update flow and compare the selected firmware identity with the device’s prompts.
  5. After the instructed restart, unlock the intended wallet and verify a known Bitcoin address.

Authenticate firmware files

Watch this step.

  1. Obtain the intended firmware through KeepKey’s documented release channel. Keep its authenticated reference hashes and signing information together. A filename or matching label does not authenticate a binary; the reference source matters.
  2. Run the repository’s host-side signature verifier against the application binary. Authenticate the source of its release public keys. These verification keys are unrelated to wallet private keys and recovery words.
  3. The verifier checks three distinct release-key signatures over the declared application code. Filled signature slots alone are insufficient. A file hash checks byte identity with a reference; a valid signature additionally ties the signed code to its signing keys.
  4. KeepKey Desktop also analyzes local firmware files and verifies release signatures. Read its result and image classification before proceeding. An unsigned local build can be intentional, but it is a different trust decision with possible device-wipe consequences.
  5. Finally, authenticate the source of your reference keys and hashes independently. Successful cryptography with the wrong trust anchors proves little. Stop when the expected file, signature result, or firmware variant does not agree.

Prepare an offline build bundle

Watch this step.

  1. Choose the source revision and firmware variant to reproduce. Record its builder-image digest. Keep authenticated reference firmware, hashes, release-key information, and verification tools with the build inputs.
  2. While online, obtain the source and initialize its required submodules recursively. A source archive without dependency contents is incomplete. Compare submodule revisions with the selected source before packaging the directory.
  3. The existing release script names a digest-pinned Docker builder. Obtain that exact image while connected, then use Docker save to export it. The release workflow uses the same save-and-load mechanism for its builder cache.
  4. Transfer the checkout, image archive, and reference files using your planned media. On the build computer, inspect the transferred files and load the builder with Docker load. Verify the expected image is present before disconnecting.
  5. This is a manual preparation checklist, not an automated offline-bundle command. The release script may pull a missing image. If any dependency or tool is absent, return to preparation rather than assuming an offline build can fetch it.

Build firmware offline

Watch this step.

  1. Confirm Docker, the exact loaded builder image, and all source submodules are available locally. Check the recorded revision and firmware variant; building different inputs answers a different question.
  2. Disconnect networking according to your offline-computer plan. The existing release script does not add a container network-isolation flag, so a diagram or command name alone does not prove network isolation. Establish and record that boundary separately.
  3. From the firmware checkout, run scripts/build/docker/device/release.sh from the selected checkout. For a Bitcoin-only reference, include -DKK_BITCOIN_ONLY=ON; otherwise use the matching default variant. The canonical recipe writes binaries under bin.
  4. Inspect the exit status and complete build log. Missing tools, dependency downloads, or a missing image mean the preflight was incomplete. Do not silently substitute a different compiler image just to obtain an output file.
  5. Keep the application binary, source revision, builder digest, and build log together. Building successfully does not authenticate the result or prove it matches a release. Continue to payload comparison before considering any device installation.

Compare firmware payloads

Watch this step.

  1. Match the intended source revision, configuration, and firmware variant. Authenticate the reference binary and release signatures first. Reproducibility does not replace deciding which source and signing keys you trust.
  2. KPKY application binaries have a metadata header. Signing fills fields in that header. An unsigned build can have a different whole-file hash while carrying identical payload bytes.
  3. Use the repository’s hash-manifest tooling to identify the hash scopes and reject truncated images. Compare the payload hashes for the local and reference application binaries. Its documented header-removal comparison applies to KPKY application images, not arbitrary bootloader files.
  4. Require the complete payload hashes to match. If they differ, investigate source revision, dependency state, builder digest, variant, and build flags. Preserve the mismatch and logs; do not remove extra bytes until a comparison happens to pass.
  5. A matching payload corroborates that this build reproduced those reference code bytes. The device-image hash includes its metadata and signatures, so it answers another question. Neither comparison independently measures the bootloader, wallet storage, or every byte inside a physical device.

Install a local firmware file

Watch this step.

  1. Before updating an initialized device, verify your recovery backup using the established backup procedure. Authenticate the intended application binary and confirm its variant. A local file does not become trustworthy merely because the computer is offline.
  2. Open KeepKey Desktop and drop the local .bin file into it. Read the file analysis, signature status, image kind, and wipe warnings. A custom build or a signed-to-unsigned transition needs a different decision from a normal signed update.
  3. Follow Desktop’s bootloader instructions and read the physical device prompts before approving. Keep the connection steady. The accompanying video uses a workflow diagram; it is not evidence of a physical-device flash.
  4. When installation finishes, follow the unplug-and-reconnect instruction without holding the button. Read the resulting firmware and bootloader status. Open How this is checked to inspect the reported hashes and compare the expected device-image reference.
  5. The hash comparison is corroboration: the device reports those values. The bootloader separately checks release signatures and warns about unsigned code. Neither a green label nor a reported hash proves full-device integrity.

Detect an altered firmware file

Watch this step.

  1. Keep the authenticated original unchanged and use a disposable copy for verification. Never flash an intentionally altered file onto a wallet device or enter recovery words for this test.
  2. Changed payload bytes should fail the reference hash check. Changing signed code also invalidates unchanged release signatures. Recheck the original to distinguish alteration from a broken verification setup.
  3. The repository signature verifier includes a self-test covering a modified synthetic image, invalid key indices, duplicate indices, and signatures from the wrong key. Use that existing test to understand rejection behavior without producing a dangerous installable demonstration.
  4. Interpret each failure by its scope. A whole-file mismatch may involve header metadata, while payload comparison checks application bytes. A structurally populated signature area is not enough; use actual signature verification and preserve the original diagnostic output.
  5. An unfamiliar device-reported hash may indicate a different legitimate build or an alteration; investigate the expected source and variant. Conversely, hostile running firmware could lie about its hash. File checks and boot warnings provide evidence, not independent full-device attestation.

Build and verification entry points

Use the selected source revision’s own instructions and tools. The inspected workflow uses scripts/build/docker/device/release.sh, scripts/release/verify-signatures.py and scripts/release/hash-manifest.sh. Tool availability and options can differ by source revision; consult their help at that revision. Prepare dependencies and the pinned builder before disconnecting, and establish network isolation separately from the script name.

Local-file installation and update recovery · Back up and verify before an update · Firmware status and evidence limits.

Last updated on