app-monorepo icon indicating copy to clipboard operation
app-monorepo copied to clipboard
verified publisher icon OneKeyHQ

[Linux: Hardware wallet fails to sign transactions when “USB Lock” is enabled]:

Open Gerald-Ha opened this issue 1 month ago • 4 comments

Describe the bug

On Linux, the OneKey hardware wallet connects successfully and can add new networks/chains, but fails when trying to sign or send a transaction.

The app shows generic hardware errors (polling timeout / WebUSB device not found), and the device never completes the signing flow.

After a lot of debugging on the OS level (udev, hidraw, USB permissions), the root cause turned out to be the "USB Lock" security setting on the device itself.

Once USB Lock is disabled on the hardware wallet, everything works immediately on Linux (AppImage, Snap, and browser extension).

Environment

  • OS: Fedora Linux (KDE / Wayland) & Ubuntu KDE (X11)
  • Device: OneKey Pro
  • OneKey Wallet:
    • Desktop App (AppImage)
    • Desktop App (Snap)
    • Browser extension (with and without OneKey Bridge)
  • Connection: direct USB, no hub

On the Linux side:

  • udev rules are configured to allow full access to on both USB and hidraw:
    • /dev/bus/usb/001/XXX → crw-rw-rw-
    • /dev/hidrawX (OneKey_Pro) → crw-rw-rw-
  • No permission denied errors in the logs once udev is configured.

Steps to reproduce

  1. Enable USB Lock on the OneKey device:
    Settings → Security → USB Lock = ON
  2. On Linux, start OneKey Wallet (AppImage, Snap, or browser extension).
  3. Connect the OneKey Pro via USB.
  4. Add a new network/chain (this usually works).
  5. Try to send a transaction (e.g. on Sui or another supported chain).
  6. Confirm the transaction in the UI and wait for the hardware signing step.

Expected behavior

  • The wallet should be able to talk to the hardware device, ask for confirmation, sign the transaction, and broadcast it (or at least show a clear error message if USB Lock blocks it).

Actual behavior

  • When the app tries to talk to the hardware for signing, the USB device gets reset and the wallet eventually shows a hardware error.

  • From journalctl -f you can see something like:

    • usb ... reset high-speed USB device using xhci_hcd
    • Low-level transfer error: Cannot send after transport endpoint shutdown (108)
    • usbfs: process onekey-wallet did not claim interface 0 before use
    • OneKey logs:
      • Device initialization failed (errorCode: 106)
      • Web-USB or Web-Bluetooth device not found or needs permission (errorCode: 901)
      • Polling timeout

  • This happens even though the Linux side has full permissions (0666) on both the USB and hidraw devices.

Workaround / Root cause

The issue is not caused by udev or Linux permissions, but by the USB Lock setting on the device:

  1. On the OneKey hardware wallet, go to:
    Settings → Security → USB Lock
  2. Set USB Lock = OFF.
  3. Reconnect the device and try again.

After disabling USB Lock:

  • Adding networks works.
  • Signing and sending transactions works properly.
  • The errors (Polling timeout, WebUSB device not found, Device initialization failed) disappear.

Security note

Disabling USB Lock slightly reduces physical security, because the device becomes more permissive in how it exposes USB to the host.

However, on a trusted personal Linux machine this is an acceptable trade-off for many users.
It would be very helpful if:

  • the app/extension could detect when USB Lock is blocking communication and show a clear warning, or
  • the documentation mentioned this clearly as a known interaction on Linux (AppImage, Snap, and browser extension).

Suggestion

  • In the Linux desktop app, show a clear warning/tooltip when USB communication to the device fails and USB Lock is enabled.
    For example:
    "Your device's USB Lock is enabled. On Linux this can block USB communication. Please disable it under Settings → Security → USB Lock if you want to use this device with the Linux desktop app or browser on this machine."
  • Optionally add a short, Linux-specific note in the setup docs / README for OneKey Bridge and the desktop app that mentions:
    • USB Lock may prevent the wallet from signing transactions on Linux
    • The workaround is to temporarily disable USB Lock on trusted machines.

Thanks – I’m happy to help others with the feedback.

Gerald-Ha avatar Dec 03 '25 06:12 Gerald-Ha

cc @wabicai

originalix avatar Dec 03 '25 07:12 originalix

Thank you for your feedback. I will follow up on this issue. Any updates will be posted on this channel.

wabicai avatar Dec 05 '25 02:12 wabicai

@Gerald-Ha Thank you very much for the information you provided, But I'm very sorry that I didn't reproduce this problem.

I conducted tests on four pro devices, and they all communicated normally after the usb lock was turned on. This is quite strange.

I have used linux versions including Fedora linux, arch linux and linux mint, but none of them reproduced the problem. I suspect that this might be a hardware-level issue.

Considering that it cannot be reproduced, I suggest you can first turn off the usb lock. If we have a device that can reproduce this problem in the future, we will try to fix it again. Sorry~

wabicai avatar Dec 10 '25 11:12 wabicai

@wabicai Thanks a lot for taking the time to test this so thoroughly!

I fully understand that if you can’t reproduce it on multiple Pro devices and multiple Linux distros, it’s very hard to treat it as a general bug. Given your feedback, it really does look like this is a very hardware-specific or environment-specific edge case on my side.

So I agree this is probably not a general Linux bug, but a very specific interaction between:

  • my USB controller / hardware,
  • Linux kernel / drivers (xhci, hid),
  • and the “USB Lock” behavior on this device.

Thanks again for checking this and for the quick response!

Gerald-Ha avatar Dec 10 '25 11:12 Gerald-Ha