Firefox용 WebUSB 확장

4 hours ago 1

(github.com/ArcaneNibble)

Firefox에서 WebUSB 기능을 사용할 수 있게 하는 확장으로, 브라우저 확장과 컴퓨터에 설치하는 native stub를 함께 사용하는 구조
Chrome의 WebUSB 구현 호환을 목표로 하지만, API는 메인 페이지에서만 노출되며 Web Workers에서는 사용할 수 없음
Android는 native messaging 부재 때문에 지원 대상에서 제외되며, 사전 빌드 바이너리는 macOS, Linux, Windows의 지정된 아키텍처에 제공됨
시스템 요구사항으로 macOS 10.15 이상, Windows 10 이상, Linux kernel 4.8 이상이 제시되며, Linux에서는 USBDEVFS_DISCONNECT_CLAIM 지원과 /dev, /sys, udev 호환 데몬 필요
native stub는 Rust 기반으로 소스 빌드 가능하며, 브라우저가 바이너리를 찾으려면 운영체제별 위치 또는 Windows 레지스트리에 native manifest 설정 필요

기능 지원

Chrome의 WebUSB 구현과 호환을 목표로 하며, 차이로 인해 소프트웨어가 동작하지 않는 경우 보고 요청
Chrome과 달리 이 API는 메인 페이지에서만 노출되며, Web Workers에서는 사용할 수 없음
Android는 native messaging 기능 부재 때문에 지원 대상에서 제외됨

설치

확장 설치
- 서명된 버전은 GitHub Releases의 바이너리를 내려받아 .xpi 파일을 Firefox에서 열어 설치 가능
- Firefox Developer Edition에서 테스트 버전을 로드하려면 about:debugging에서 "This Firefox" 선택 후 "Load Temporary Add-on…"을 사용하고 extension/ 디렉터리의 manifest.json 지정 필요
native stub 설치
- 사전 빌드 바이너리 사용 시 모든 파일의 압축을 푼 뒤 Linux 또는 macOS에서는 ./install.sh, Windows에서는 install.bat 실행 필요
- 설치 스크립트는 적절한 위치로 파일을 자동 복사하고, 브라우저가 찾을 수 있도록 native manifest 설정 시도
- 사전 빌드 바이너리 제공 플랫폼은 macOS x86_64/ARM64, Linux x86_64/aarch64, Windows AMD64/ARM64
- 사전 빌드 바이너리를 사용하지 않을 경우 아래의 소스 빌드 절차 참고 필요
비표준 구성
- 서로 다른 CPU 아키텍처를 가진 여러 컴퓨터 간 Unix 계열 홈 디렉터리 공유 구성에서 기본 설치 프로그램 문제가 알려져 있음
- 서로 다른 CPU 아키텍처를 가진 컴퓨터 간 Windows roaming user profile 구성에서도 동일한 문제가 알려져 있음
- 원인으로 native manifest 메커니즘의 설계 한계가 언급되며, 예시로 절대 경로 사용 포함
- 이런 구성에서는 사용자가 임시방편의 ad-hoc workaround를 직접 마련해야 함

시스템 요구사항

macOS
- macOS 10.15 이상 필요
- Firefox 시스템 요구사항과 일치
- 더 오래된 시스템은 테스트가 충분하지 않으며, macOS 12가 더 현실적인 기준선으로 언급됨
Windows
- Rust 플랫폼 지원 요구사항 때문에 Windows 10 이상 필요
- Firefox 시스템 요구사항과도 일치
- Windows 8/8.1로의 백포팅은 이론적으로 가능할 수 있으나, 그보다 오래된 버전은 WinUSB 제한 때문에 동작할 것으로 기대되지 않음
Linux
- Linux kernel 4.8 이상 필요
- 더 구체적으로는 커밋 5cce438와 USBDEVFS_CAP_REAP_AFTER_DISCONNECT를 포함한 커널 강력 권장
- USBDEVFS_DISCONNECT_CLAIM 지원 커널 필수
- 시스템에는 /dev와 /sys가 마운트되어 있어야 함
- USB 장치 연결 감지를 위해 udev 또는 호환 데몬 필요
- 구체적으로 NETLINK_KOBJECT_UEVENT 그룹 2에서 0xfeedcafe 형식 메시지를 브로드캐스트하는 데몬 필요

소스에서 빌드

일반 사항
- native stub는 전반적으로 Rust만으로 작성되었으며 native-stub 디렉터리에서 cargo build로 빌드 가능
- 크로스 컴파일 지원되며, 지원 플랫폼에 대한 기본 설정 포함
macOS
- 저장소에 최종 바이너리 링크에 필요한 모든 .tbd 파일의 vendored copy 포함
- 이 구성이 문제를 일으킬 경우 .cargo/config.toml의 관련 항목 비활성화 가능
- 해당 항목을 비활성화하면 macOS SDK 설치 필요
Linux
- Linux 사전 빌드 바이너리는 musl libc와 Rust 기본값인 정적 링크 사용 구성
- 목표는 어떤 배포판에서도 동작하는 바이너리 생성
- 원하지 않을 경우 적절한 RUSTFLAGS 변경 필요
- glibc 빌드는 동작할 것으로 예상되지만 테스트되지는 않음
Windows
- Windows 사전 빌드 바이너리는 mingw-w64를 사용해 UCRT 대상으로 빌드되도록 구성
- Rust의 *-windows-gnullvm 타깃에 해당
- Windows는 주로 Windows 외 플랫폼에서의 cross-build로 테스트됨
- Windows 자체에서의 빌드는 가능하도록 되어 있으나 rust-mingw 컴포넌트 추가가 필요할 수 있음
- Windows가 아닌 시스템에서 빌드할 경우 mingw-w64의 .lib 파일을 별도로 확보해야 함
- 예시 확보 경로로 Dockerfile에 포함된 단계 언급
- .cargo/config.toml에는 이 라이브러리 탐색을 위한 하드코딩된 경로가 있어 점검 또는 수정 필요
- MSVC toolchain 빌드는 지원되지 않음
  - 근본적으로 불가능한 것은 아니지만 테스트되지는 않았다고 명시

native manifest 설정

브라우저가 컴파일된 바이너리를 찾으려면 컴퓨터의 특정 위치에 manifest 파일 설치 필요
manifest는 짧은 JSON 파일이며 운영체제에 따라 지정 위치가 달라짐
macOS
- 전역 위치 /Library/Application Support/Mozilla/NativeMessagingHosts/awawausb_native_stub.json
- 사용자 로컬 위치 ~/Library/Application Support/Mozilla/NativeMessagingHosts/awawausb_native_stub.json
Linux
- 전역 위치 /usr/lib/mozilla/native-messaging-hosts/awawausb_native_stub.json
- 전역 위치 /usr/lib64/mozilla/native-messaging-hosts/awawausb_native_stub.json
- 사용자 로컬 위치 ~/.mozilla/native-messaging-hosts/awawausb_native_stub.json
Windows
- manifest 파일은 어느 위치에 두어도 되지만, 해당 파일을 가리키는 레지스트리 키 설정 필요
- 전역 키 HKLM\SOFTWARE\Mozilla\NativeMessagingHosts\awawausb_native_stub
- 사용자 로컬 키 HKCU\SOFTWARE\Mozilla\NativeMessagingHosts\awawausb_native_stub
- 올바르게 설정된 레지스트리 항목의 스크린샷 포함
native manifest 내용
- JSON에는 name, description, path, type, allowed_extensions 필드 포함
- name 값은 awawausb_native_stub
- description 값은 Allows WebUSB extension to access USB devices
- path 값은 실행 파일 경로인 /path/to/awawausb-native-stub
- type 값은 stdio
- allowed_extensions 값은 ["awawausb@arcanenibble.com"]
- Windows에서는 전체 경로가 필수가 아니며 "awawausb-native-stub.exe"만으로도 충분