Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions docs/forgebox-signing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# ForgeBox offline firmware signing

**Tools → ForgeBox Signing** can recover a dedicated signing key from a loaded
seed using BIP85, export its public key, and sign firmware or registration
requests transferred by microSD. It supports mnemonic-backed seeds and XprvSeed
through `seed.get_root()`. No private key or WIF is exported.

Install the paired SeedSigner OS change providing
`/usr/lib/seedsigner/secure-boot/forgebox_sign.py`. The menu hides when that
module is absent. The app loads only trusted OS code, never code from the card.
Desktop development can set `SEEDSIGNER_SECURE_BOOT_DIR` to the OS checkout's
`opt/luckfox/secure-boot` directory.

1. Load the intended root/passphrase. Choose **Export BIP85 Public Key**, select a
dedicated index and record the displayed `m/83696968'/2'/index'` path and public
key. Restore independently and repeat export before enrolling that key.
2. Keep a trusted PC copy of the exported `pubkey.pem`. The OS repository's PC
helper compresses a full firmware image with official forgebox-cli 1.2.0 and
writes a small request to `forgebox-signing/request.json` on the card.
3. Choose **Sign Request on Card**, review the digest-only warning and both
hashes, select the same root/index, compare the public key and confirm Sign.
4. Return the card. The PC helper verifies `response.json` against the trusted
public key, original image and unchanged unsigned package, then assembles the
signed OTA. It will not overwrite an existing output.

The OS helper can also hold a factory USB session open while SeedSigner signs a
registration proof of possession. This keeps the private key off the PC during
initial enrollment too. Physical registration/nonce lifetime are untested; the
adapter is covered with an injected device. Enrollment is once per device
lifetime, so verify the seed/passphrase/index recovery and device display first.

This signs hashes; it cannot inspect firmware or vouch for the build PC. It
does not flash a device or implement JavaCard/secure-element key storage.
Pure-Python ECDSA and Python memory management do not provide constant-time
execution or guaranteed secret erasure. Keys remain short-lived local objects,
are not cached/logged/written, and all cancel/error paths drop their references.

The complete commands, build pairing, threat assumptions and validation status
are in the OS repo's
[ForgeBox offline signing guide](https://github.com/3rdIteration/seedsigner-os/blob/feat/forgebox-offline-signing/docs/forgebox-offline-signing.md).

For a paired image build, select the OS PR branch and this app's exact commit
using the existing build workflow/app-ref inputs. Keep the app's `seedsigner-os`
release gitlink unchanged until the paired release is cut.
26 changes: 26 additions & 0 deletions src/seedsigner/helpers/forgebox_tools.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
"""Resolve the OS-provided ForgeBox protocol; never execute code from microSD."""
import importlib.util
import os
from seedsigner.helpers.secure_boot_tools import candidate_dirs


def find_path():
for directory in candidate_dirs():
path = os.path.join(directory, 'forgebox_sign.py')
if os.path.isfile(path):
return path
return None


def is_available():
return find_path() is not None


def load():
path = find_path()
if path is None:
raise RuntimeError('ForgeBox signing tools are not installed in this OS')
spec = importlib.util.spec_from_file_location('seedsigner_os_forgebox', path)
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module
121 changes: 121 additions & 0 deletions src/seedsigner/views/forgebox_views.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
"""BIP85 ForgeBox key recovery, public export and explicit offline signing.

All operation screens live in one View, so Back never replays a signing action.
No private material is written, logged, placed in destinations or cached.
"""
from gettext import gettext as _
from seedsigner.gui.components import GUIConstants, reflow_text_into_pages
from seedsigner.gui.screens import ButtonListScreen, WarningScreen
from seedsigner.gui.screens.screen import ButtonOption, PagedTextScreen
from seedsigner.gui.screens.seed_screens import SeedBIP85SelectChildIndexScreen
from seedsigner.hardware.microsd import MicroSD
from seedsigner.helpers import forgebox_tools
from seedsigner.models.settings_definition import SettingsConstants
from seedsigner.views.view import View, Destination, BackStackView


def _groups(value):
return ' '.join(value[i:i+4] for i in range(0, len(value), 4))


class ToolsForgeBoxMenuView(View):
EXPORT = ButtonOption('Export BIP85 Public Key')
SIGN = ButtonOption('Sign Request on Card')

def run(self):
if not forgebox_tools.is_available():
return Destination(BackStackView)
buttons = [self.EXPORT, self.SIGN]
selected = self.run_screen(ButtonListScreen, title=_('ForgeBox Signing'), button_data=buttons)
if selected not in (0, 1):
return Destination(BackStackView)
return Destination(ToolsForgeBoxRunView, view_args={'action': 'export' if selected == 0 else 'sign'})


class ToolsForgeBoxRunView(View):
def __init__(self, action):
super().__init__()
if action not in ('export', 'sign'):
raise ValueError('unknown ForgeBox action')
self.action = action

def show_text(self, title, text):
width, height = PagedTextScreen.get_paging_dimensions()
pages = reflow_text_into_pages(text=text, width=width, height=height,
font_size=GUIConstants.get_body_font_size())
for page in range(len(pages)):
if self.run_screen(PagedTextScreen, title=title, paged_info=pages, page_num=page) != 0:
return False
return True

def run(self):
key = None
try:
tools = forgebox_tools.load()
card = str(MicroSD.get_microsd_dir())
# Read once before review; a swapped request is never re-read for signing.
request = tools.validate_request(tools.read_json(card, 'request.json')) if self.action == 'sign' else None
if request is not None:
registering = request['action'] == 'register'
selected = self.run_screen(WarningScreen, title=_('ForgeBox Signing'),
status_headline=_('Register owner key') if registering else _('Digest-only signing'),
text=_('Registration binds a lifetime firmware key. Compare the full public key on ForgeBox.')
if registering else _('The firmware is not on this device. Only sign hashes prepared on your trusted PC.'),
button_data=[ButtonOption('Review')])
if selected != 0:
return Destination(BackStackView)
if registering:
review = _('Registration mode: {}\nNonce: {}').format(
'legacy' if request['legacy'] else 'challenge', _groups(request['nonce']) or '(none)')
else:
review = _('Label: {}\nOriginal size: {}\nOriginal SHA256:\n{}\nCompressed SHA256:\n{}').format(
' '.join(request['name'][i:i+12] for i in range(0, len(request['name']), 12)),
request['original_size'], _groups(request['original_hash']), _groups(request['compressed_hash']))
if not self.show_text(_('Review Request'), review):
return Destination(BackStackView)
seeds = self.controller.storage.seeds
if not seeds:
self.show_text(_('Load a seed first'), _('Load the signing seed, then return to ForgeBox Signing.'))
return Destination(BackStackView)
network = self.settings.get_value(SettingsConstants.SETTING__NETWORK)
selected = self.run_screen(ButtonListScreen, title=_('Signing Seed'),
button_data=[ButtonOption(seed.get_fingerprint(network)) for seed in seeds])
if type(selected) is not int or not 0 <= selected < len(seeds):
return Destination(BackStackView)
index = self.run_screen(SeedBIP85SelectChildIndexScreen, title=_('ForgeBox Key Index'))
if not isinstance(index, str):
return Destination(BackStackView)
# get_root supports mnemonic-backed seeds and XprvSeed (seed_bytes=None).
key = tools.key_from_root(seeds[selected].get_root(network), int(index))
public = tools.public_hex(key)
if request is not None and request['public_key'] != public:
self.show_text(_('Wrong signing key'), _('Seed, passphrase or BIP85 index does not match this request.'))
return Destination(BackStackView)
if not self.show_text(_('Signing Public Key'),
"BIP85 path:\nm/83696968'/2'/\n%s'\nSHA256 key ID:\n%s\nPublic key:\n%s" %
(index, _groups(tools.fingerprint(public)), _groups(public[2:]))):
return Destination(BackStackView)
selected = self.run_screen(WarningScreen, title=_('ForgeBox Signing'), status_headline=None,
text=_('Only the public key is saved. Record the seed, passphrase and index for recovery.')
if self.action == 'export' else _('Authorize this exact request with the displayed signing key?'),
button_data=[ButtonOption('Export' if self.action == 'export' else 'Sign')])
if selected != 0:
return Destination(BackStackView)
if self.action == 'export':
tools.export_public(card, key, int(index))
message = _('Public key saved in forgebox-signing/. Verify recovery before registration.')
else:
response = tools.sign_request(request, key)
tools.write_json(card, 'response.json', response)
message = _('Response saved. Return the card to your PC to verify and assemble or register.')
# Drop our key reference before showing completion; no shared key cache.
key = None
self.show_text(_('ForgeBox Complete'), message)
except Exception:
# Exceptions may carry key-library objects: do not log/format them.
key = None
self.show_text(_('Cannot continue'), _('Check the card request, OS tools and signing seed. No private key was saved.'))
finally:
key = None
# Multiple-screen operation terminates at its entry menu, never an action.
return Destination(ToolsForgeBoxMenuView)
7 changes: 7 additions & 0 deletions src/seedsigner/views/tools_views.py
Original file line number Diff line number Diff line change
Expand Up @@ -367,6 +367,7 @@ class ToolsMenuView(View):
BATTERY_CALIBRATION = ButtonOption("Battery Calibration")
GPG = ButtonOption("GPG Tools")
LUCKFOX_BUILD_TOOLS = ButtonOption("Luckfox Build Tools")
FORGEBOX_SIGNING = ButtonOption("ForgeBox Signing")
CLEAR_DESCRIPTOR = ButtonOption("Clear Multisig Descriptor")
NETWORK_INFO = ButtonOption("Network Info")

Expand All @@ -376,6 +377,7 @@ def __init__(self, include_password_generator: bool = True):

def run(self):
button_data = [self.IMAGE, self.DICE]
from seedsigner.helpers import forgebox_tools

if getattr(self, "include_password_generator", True):
button_data.append(self.PASSWORD_GENERATOR)
Expand All @@ -395,6 +397,7 @@ def run(self):
self.VERIFY_ADDRESS,
self.TEXTQRCODE,
self.MICROSD,
self.FORGEBOX_SIGNING if forgebox_tools.is_available() else None,
# Two gates, both deliberate. The setting is off by default because
# this turns the device into a signing machine for SeedSigner OS
# releases. The availability check is because the signers are
Expand Down Expand Up @@ -455,6 +458,10 @@ def run(self):
from seedsigner.views.resign_views import ToolsLuckfoxBuildToolsMenuView
return Destination(ToolsLuckfoxBuildToolsMenuView)

elif button_data[selected_menu_num] == self.FORGEBOX_SIGNING:
from seedsigner.views.forgebox_views import ToolsForgeBoxMenuView
return Destination(ToolsForgeBoxMenuView)

elif button_data[selected_menu_num] == self.PASSWORD_GENERATOR:
return Destination(ToolsPasswordGeneratorTypeView)

Expand Down
32 changes: 32 additions & 0 deletions tests/test_flows_menu_navigation.py
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,38 @@ def _patch_javacard_diy(cap_dir=None):


class TestMenuNavigationFlows(FlowTest):
def test_forgebox_menu_and_back(self):
from seedsigner.views.forgebox_views import ToolsForgeBoxMenuView
with patch('seedsigner.helpers.forgebox_tools.is_available', return_value=True):
self.run_sequence([
FlowStep(MainMenuView, button_data_selection=MainMenuView.TOOLS),
FlowStep(tools_views.ToolsMenuView, button_data_selection=tools_views.ToolsMenuView.FORGEBOX_SIGNING),
FlowStep(ToolsForgeBoxMenuView, screen_return_value=RET_CODE__BACK_BUTTON),
FlowStep(tools_views.ToolsMenuView),
])

def test_forgebox_export_no_seed_returns_to_entry_menu(self):
from seedsigner.views.forgebox_views import ToolsForgeBoxMenuView, ToolsForgeBoxRunView
with patch('seedsigner.helpers.forgebox_tools.is_available', return_value=True), \
patch('seedsigner.helpers.forgebox_tools.load', return_value=MagicMock()):
self.run_sequence([
FlowStep(MainMenuView, button_data_selection=MainMenuView.TOOLS),
FlowStep(tools_views.ToolsMenuView, button_data_selection=tools_views.ToolsMenuView.FORGEBOX_SIGNING),
FlowStep(ToolsForgeBoxMenuView, button_data_selection=ToolsForgeBoxMenuView.EXPORT),
FlowStep(ToolsForgeBoxRunView, screen_return_value=0),
FlowStep(ToolsForgeBoxMenuView, screen_return_value=RET_CODE__BACK_BUTTON),
FlowStep(tools_views.ToolsMenuView),
])

def test_forgebox_hidden_without_os_tool(self):
with patch('seedsigner.helpers.forgebox_tools.is_available', return_value=False):
view = tools_views.ToolsMenuView()
def screen(screen_class, **kwargs):
assert view.FORGEBOX_SIGNING not in kwargs['button_data']
return RET_CODE__BACK_BUTTON
view.run_screen = screen
assert view.run().View_cls is BackStackView

"""Walk every menu path in the UI to catch import errors, reachability bugs,
stuck states, and settings gating regressions.

Expand Down
119 changes: 119 additions & 0 deletions tests/test_forgebox_views.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
"""UI authorization/lifecycle tests; hardware and OS protocol independently tested."""
from types import SimpleNamespace
from unittest.mock import MagicMock
import pytest
import base # repository hardware/renderer test doubles
from seedsigner.views import forgebox_views as views
from seedsigner.views.view import BackStackView
from seedsigner.gui.screens.screen import RET_CODE__BACK_BUTTON, RET_CODE__POWER_BUTTON
from seedsigner.models.seed import Seed, XprvSeed
from seedsigner.models.settings_definition import SettingsConstants
from seedsigner.helpers import forgebox_tools


def make_view(monkeypatch, action='sign', seed=None):
request = dict(action='firmware', name='test.bin', original_size=123,
original_hash='aa'*32, compressed_hash='bb'*32, public_key='04'+'11'*64)
tools = MagicMock()
tools.read_json.return_value = request
tools.validate_request.side_effect = lambda value: value
tools.public_hex.return_value = request['public_key']
tools.fingerprint.return_value = 'cc'*32
tools.sign_request.return_value = {'signatures':['public signature']}
monkeypatch.setattr(forgebox_tools, 'load', lambda: tools)
monkeypatch.setattr(views.MicroSD, 'get_microsd_dir', lambda: '/test-card')
view = object.__new__(views.ToolsForgeBoxRunView)
view.action = action
view.controller = SimpleNamespace(storage=SimpleNamespace(seeds=[seed or MagicMock()]))
view.settings = MagicMock()
view.settings.get_value.return_value = SettingsConstants.MAINNET
text = []
view.show_text = lambda title, message: text.append((title, message)) or True
calls = []
def screen(kind, **kwargs):
calls.append((kind, kwargs))
return '0' if kind is views.SeedBIP85SelectChildIndexScreen else 0
view.run_screen = screen
return view, tools, request, calls, text


@pytest.mark.parametrize('xprv', [False, True])
def test_sign_with_bip39_and_xprv_uses_get_root(monkeypatch, xprv):
seed = Seed(mnemonic=['abandon']*11+['about'])
if xprv:
seed = XprvSeed(seed.get_root().to_base58())
assert seed.seed_bytes is None
view, tools, request, calls, text = make_view(monkeypatch, seed=seed)
result = view.run()
assert result.View_cls is views.ToolsForgeBoxMenuView
assert tools.key_from_root.call_args.args[0].to_base58() == seed.get_root(SettingsConstants.MAINNET).to_base58()
assert tools.key_from_root.call_args.args[1] == 0
tools.sign_request.assert_called_once_with(request, tools.key_from_root.return_value)
tools.write_json.assert_called_once_with('/test-card', 'response.json', tools.sign_request.return_value)
assert calls[-1][1]['button_data'][0].button_label == 'Sign'
assert not hasattr(view.controller, 'forgebox_key')


@pytest.mark.parametrize('stop_at', range(4))
@pytest.mark.parametrize('exit_code', [RET_CODE__BACK_BUTTON, RET_CODE__POWER_BUTTON])
def test_exit_at_every_input_stops_signing(monkeypatch, stop_at, exit_code):
view, tools, request, calls, text = make_view(monkeypatch)
real_screen = view.run_screen
count = [0]
def screen(kind, **kwargs):
i = count[0]
count[0] += 1
return exit_code if i == stop_at else real_screen(kind, **kwargs)
view.run_screen = screen
assert view.run().View_cls is BackStackView
tools.sign_request.assert_not_called()
tools.write_json.assert_not_called()


def test_cancel_hash_or_public_review_and_wrong_key(monkeypatch):
for cancel_at in (0, 1):
view, tools, request, calls, text = make_view(monkeypatch)
count = [0]
def review(*args):
value = count[0] != cancel_at
count[0] += 1
return value
view.show_text = review
assert view.run().View_cls is BackStackView
tools.sign_request.assert_not_called()
view, tools, request, calls, text = make_view(monkeypatch)
tools.public_hex.return_value = 'different key'
assert view.run().View_cls is BackStackView
tools.sign_request.assert_not_called()


def test_export_and_failure_do_not_export_private_key(monkeypatch):
view, tools, request, calls, text = make_view(monkeypatch, action='export')
assert view.run().View_cls is views.ToolsForgeBoxMenuView
tools.read_json.assert_not_called()
tools.export_public.assert_called_once()
tools.sign_request.assert_not_called()
view, tools, request, calls, text = make_view(monkeypatch)
tools.sign_request.side_effect = ValueError('sensitive exception must not reach UI')
assert view.run().View_cls is views.ToolsForgeBoxMenuView
tools.write_json.assert_not_called()
assert all('sensitive exception' not in message for _, message in text)


def test_missing_seed_and_registration_review(monkeypatch):
view, tools, request, calls, text = make_view(monkeypatch)
view.controller.storage.seeds = []
assert view.run().View_cls is BackStackView
tools.key_from_root.assert_not_called()
view, tools, request, calls, text = make_view(monkeypatch)
request.update(action='register', legacy=False, nonce='ab'*32)
assert view.run().View_cls is views.ToolsForgeBoxMenuView
assert 'lifetime' in calls[0][1]['text']
assert any('Nonce' in message for _, message in text)


def test_missing_os_tools_hidden_and_loader_refuses(monkeypatch):
monkeypatch.setattr(forgebox_tools, 'candidate_dirs', lambda: [])
assert not forgebox_tools.is_available()
with pytest.raises(RuntimeError, match='not installed'):
forgebox_tools.load()
Loading