gandalf/secubox-openwrt
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
79bb3c43f4
secubox-openwrt/package/secubox/secubox-master-link
History
CyberMind-FR 857622ff56 feat(master-link): Add dynamic join IPK generation for mesh onboarding 
Generate a minimal IPK on-the-fly when a client visits the master-link
landing page, so the "Download Package" step always works even without
a pre-built IPK bundle. The IPK configures the peer via postinst uci
commands (avoiding file conflicts with secubox-master-link), and can be
installed directly via opkg install URL from SSH.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-03 09:36:04 +01:00
..
files feat(master-link): Add dynamic join IPK generation for mesh onboarding 2026-02-03 09:36:04 +01:00
Makefile feat(master-link): Add secure mesh onboarding packages 2026-02-03 06:15:47 +01:00
README.md docs(master-link): Add README for both master-link packages 2026-02-03 07:16:22 +01:00

README.md

SecuBox Master-Link

Secure mesh onboarding for SecuBox appliances. A master node generates one-time join tokens, serves the secubox IPK bundle, and approves new peers via blockchain-backed trust. Supports gigogne (nested) hierarchy where approved nodes can become sub-masters.

Overview

  MASTER (depth 0)
  ├── Peer A (depth 1)
  ├── Sub-Master B (depth 1)
  │   ├── Peer C (depth 2)
  │   └── Peer D (depth 2)
  └── Peer E (depth 1)

Installation

opkg install secubox-master-link luci-app-master-link

Configuration

# /etc/config/master-link

config master-link 'main'
    option enabled '1'
    option role 'master'          # master | peer | sub-master
    option upstream ''            # upstream master IP (peers/sub-masters)
    option depth '0'              # gigogne depth (0 = root master)
    option max_depth '3'          # max nesting depth
    option token_ttl '3600'       # token validity in seconds
    option auto_approve '0'       # auto-approve join requests
    option ipk_path '/www/secubox-feed/secubox-master-link_*.ipk'

Join Protocol

  1. Master generates token — one-time HMAC-SHA256 token with TTL
  2. New node opens landing page — http://<master>:7331/master-link/?token=...
  3. New node downloads IPK — token-validated download via /api/master-link/ipk
  4. New node sends join request — fingerprint + address submitted to master
  5. Master approves — TOFU key exchange, blockchain block recorded, peer added to mesh
  6. Optional: promote to sub-master — approved peer can onboard its own peers

CGI Endpoints

All served on port 7331 under /api/master-link/.

Endpoint Method Auth Description
/token POST Local only Generate join token
/join POST Token Submit join request
/approve POST Local only Approve/reject peer
/status GET Public/Local Mesh status
/ipk POST Token Download secubox IPK

RPCD API

ubus call luci.master_link status '{}'
ubus call luci.master_link peers '{}'
ubus call luci.master_link tree '{}'
ubus call luci.master_link token_generate '{}'
ubus call luci.master_link approve '{"fingerprint":"...","action":"approve"}'
ubus call luci.master_link approve '{"fingerprint":"...","action":"reject","reason":"..."}'
ubus call luci.master_link approve '{"fingerprint":"...","action":"promote"}'
ubus call luci.master_link token_cleanup '{}'

Blockchain Block Types

Type Description
join_request New node requesting to join
peer_approved Master approved peer
peer_rejected Master rejected peer
peer_promoted Peer promoted to sub-master
token_generated Audit: token was created

Security

  • Tokens: HMAC-SHA256, one-time use, time-limited (default 1h)
  • TOFU: First join establishes trust via fingerprint exchange
  • Depth limiting: max_depth prevents unbounded nesting
  • Chain integrity: All actions recorded as blockchain blocks
  • Audit trail: Token lifecycle and peer events queryable via chain

Dependencies

  • secubox-p2p — mesh networking and blockchain
  • openssl-util — HMAC token generation
  • curl — peer notification

License

Apache-2.0