mortenVChristiansen
/
k_card
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
k_card/Setup.md

9.9 KiB
Raw Blame History

Setup

Last updated: 2026-04-24

This is a living setup/status file for the local ChromeCard workspace at /home/user/chromecard. Update this file whenever environment status or verified behavior changes.

Repository Policy

  • Treat /home/user/chromecard/CR_SDK_CK-main as read-only in this workflow.
  • Do not add or modify helper/test scripts inside CR_SDK_CK-main.
  • Keep host-side helper scripts at workspace root (/home/user/chromecard).

Documentation Maintenance

  • Canonical living status docs for this workspace are:
    • /home/user/chromecard/Setup.md
    • /home/user/chromecard/Workplan.md
  • After each meaningful execution step, update at least:
    • Setup.md for observed environment/runtime state
    • Workplan.md for phase progress and next blocking action
  • Keep helper script paths consistent in docs:
    • /home/user/chromecard/fido2_probe.py
    • /home/user/chromecard/webauthn_local_demo.py
  • Treat CR_SDK_CK-main/README_HOST.md as historical reference unless its script paths are aligned with this workspace policy.

Scope

  • Experimental ChromeCard connected over USB.
  • Firmware source tree: /home/user/chromecard/CR_SDK_CK-main.
  • Host-side FIDO2 demo tools:
    • /home/user/chromecard/fido2_probe.py
    • /home/user/chromecard/webauthn_local_demo.py
  • Target runtime platform: Qubes OS with 3 AppVMs:
    • k_client (browser + enrollment process)
    • k_proxy (card-connected proxy/auth client)
    • k_server (protected resource/backend)

Planned Transport Evolution

  • Current phase assumption: card is connected directly to k_proxy (USB).
  • Future target: card is connected to a phone, and k_proxy performs validation through a wireless link to that phone.
  • Design implication: keep authenticator transport behind an abstraction in k_proxy so USB-direct and phone-wireless backends can be swapped without changing client/server API contracts.

Target Qubes Topology

  • Base template for all AppVMs: debian-13-xfce.
  • Allowed network paths:
    • k_client -> k_proxy over TLS
    • k_proxy -> k_server over TLS
    • Response traffic returns on those established connections.
  • Disallowed direct path:
    • k_client -> k_server (direct access should be blocked).

Functional roles:

  • k_client:
    • Browser-only traffic client.
    • Runs a user enrollment process.
  • k_proxy:
    • Current: connected to the ChromeCard over USB.
    • Future: connects wirelessly to phone-attached card for validation.
    • Accepts TLS requests from k_client.
    • Uses card-backed FIDO2/WebAuthn operations to authenticate user/session.
    • Calls k_server over TLS after successful authorization.
    • Returns proxied data and session information to k_client.
  • k_server:
    • Hosts resource(s) requiring login via the proxy-mediated flow.
    • Provides a dummy protected resource for early integration testing (monotonic increasing number/counter).
    • May hold user/session state logic needed for authorization decisions.

UI baseline for each AppVM (start-menu visible apps):

  • Firefox
  • XFCE Terminal
  • File Manager

Target Request Flow

  1. k_client sends HTTPS request to k_proxy.
  2. k_proxy validates/authenticates user via card-backed flow.
  3. If allowed, k_proxy opens HTTPS request to k_server resource.
  4. k_server responds to k_proxy.
  5. k_proxy returns response payload to k_client plus session state.
  6. Subsequent requests reuse session state so card auth is not required every request.

Implementation note:

  • k_proxy does not need a full web server stack; a minimal TLS API service is sufficient.
  • Session state should be integrity-protected (signed/encrypted token or server-side session ID) with TTL and revocation behavior defined.
  • k_proxy and k_server must be safe under concurrent access (thread-safe state handling).

Minimum Service Behavior (Current Target)

  • k_server:
    • Expose protected endpoint returning an increasing integer value (dummy resource).
    • Increment behavior must remain correct under concurrent requests.
    • Optionally expose/maintain user/session validation logic.
  • k_proxy:
    • Accept concurrent HTTPS requests from one or more k_client instances.
    • Perform card-backed auth when no valid session is present.
    • Cache and validate session state so repeated requests avoid card access until expiry.
    • Forward authorized requests to k_server and return upstream data plus session info.

Thread-safety expectation:

  • Shared mutable state (counter, session store, user state) must be protected against races.
  • Parallel requests must not corrupt session records or return duplicate/skipped counter values caused by unsafe updates.

Test Topology Requirement

  • Support concurrency testing from multiple simultaneous clients:
    • multiple browser tabs/processes in one k_client, and/or
    • multiple k_client AppVM instances if available.
  • Validate both correctness and stability under load:
    • session reuse works as intended
    • unauthorized access stays blocked
    • protected counter/resource remains consistent.

Current Status Snapshot (2026-04-24)

  • AppVM OS version is confirmed: Debian 13.4 (k_server, and same on k_client/k_proxy).
  • Python in AppVMs is available: Python 3.13.5.
  • python3 /home/user/chromecard/fido2_probe.py --list in k_proxy now detects ChromeCard on /dev/hidraw0 (vid:pid=4617:5).
  • HID raw device nodes are now visible in k_proxy:
    • /dev/hidraw0 -> crw-rw----+
    • /dev/hidraw1 -> crw-------
  • python3 /home/user/chromecard/fido2_probe.py --json succeeds and returns CTAP2 getInfo:
    • versions: ["FIDO_2_0"]
    • aaguid: 1234567890abcdef0123456789abcdef
    • options: rk=false, up=true, uv=true
    • max_msg_size: 1024
  • Local WebAuthn demo (http://localhost:8765 in k_proxy) succeeded:
    • register: ok=true, username=alice, credential_count=1
    • login/auth: ok=true, username=alice, authenticated=true
  • west is not currently installed/in PATH: west not found.
  • The checked-out CR_SDK_CK-main tree appears incomplete for documented sysbuild role layout:
    • missing: mvp, setup, components, samples
  • CR_SDK_CK-main/scripts/build_flash_mvp.sh exists, but it expects the above role directories.
  • Python helper scripts were intentionally moved out of CR_SDK_CK-main/scripts and are now maintained at workspace root.
  • Qubes AppVM baseline is now up: k_client, k_proxy, k_server can start and have terminals running.

Implication:

  • Live FIDO2 connectivity from k_proxy to ChromeCard is confirmed over USB HID/CTAPHID.
  • Local browser WebAuthn register/login flow is confirmed working in k_proxy.
  • We cannot currently run the documented firmware build/flash flow.

Session note (2026-04-24):

  • Markdown tracking was reviewed and normalized around Setup.md + Workplan.md as the active, continuously updated execution record.
  • AppVM template decision recorded: use debian-13-xfce for k_client, k_proxy, and k_server.
  • VM start attempt failed with Xen toolstack error: libxenlight have failed to create new domain 'k_client'.
  • VM start blocker was resolved by reducing VM memory to 400 MiB; all three AppVMs now start.
  • Runtime check from VMs: Debian 13.4 and Python 3.13.5; k_proxy still shows no hidraw devices.
  • After USB assignment to k_proxy, /dev/hidraw0 and /dev/hidraw1 appeared.
  • CTAP probe re-run succeeded with detected ChromeCard device and valid CTAP2 getInfo response.
  • Local WebAuthn demo completed successfully for user alice (register + login).

Known FIDO2 Transport Boundary

  • FIDO2 on this firmware is handled via USB HID (CTAPHID), not Wi-Fi/BLE/MQTT.
  • Key code points in CR_SDK_CK-main:
    • mgr_fido2.c: mgr_fido2_init() registers fido2_ctaphid_handle_packet.
    • ctaphid.c: fido2_ctaphid_handle_packet(...).
    • cr_config.h: FIDO2 HID report descriptor definitions.

Host Bring-Up Steps (How To Get To A Working FIDO2 Check)

  1. Confirm USB enumeration and HID visibility.
  • Replug card with a known data-capable cable.
  • Check: ls -l /dev/hidraw*
  1. If needed, grant Linux HID access for this device.
  • Add rule at /etc/udev/rules.d/70-chromecard-fido.rules:
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="1209", ATTRS{idProduct}=="0005", MODE="0660", TAG+="uaccess"
  • Reload/apply rules and replug the device.
  1. Verify CTAP HID presence.
  • python3 /home/user/chromecard/fido2_probe.py --list
  • Then:
  • python3 /home/user/chromecard/fido2_probe.py --json
  1. Run local WebAuthn bring-up demo.
  • python3 /home/user/chromecard/webauthn_local_demo.py
  • Open http://localhost:8765 (use localhost, not 127.0.0.1).
  1. Execute register/login test.
  • Register a user.
  • Login with the same user.
  • Confirm no origin/challenge mismatch errors.

Build/Flash Prerequisites (How To Get To Firmware Build)

  1. Ensure full SDK checkout layout exists under CR_SDK_CK-main:
  • mvp
  • setup
  • components
  • samples
  1. Ensure toolchain is available in shell:
  • west --version
  • nrfjprog --version
  1. Once layout/tooling are in place, run:
  • cd /home/user/chromecard/CR_SDK_CK-main
  • ./scripts/build_flash_mvp.sh

Open Gaps To Resolve

  • Why no /dev/hidraw* device is visible despite USB connection.
  • Whether udev rule is missing or device VID/PID differs from expected.
  • Whether current firmware on card exposes the FIDO2 HID interface.
  • Whether a full CR_SDK_CK-main checkout (with role directories) is available locally.
  • Whether server-side code should be pulled now for broader CIP/WebAuthn integration testing.
  • Exact Qubes firewall and service binding rules to enforce the k_client -> k_proxy -> k_server chain.
  • Exact enrollment process interface running in k_client and how it reaches k_proxy.
  • Concrete session format/lifetime so cached sessions reduce card prompts without weakening security.
  • Precise ownership split of session/user state between k_proxy and k_server.
  • Concrete concurrency limits and acceptance criteria (requests/sec, parallel clients, latency/error thresholds).