integral-unlock

integral-unlock is a public Rust workspace for the Integral Crypto-197 USB unlock protocol.

The project has two goals:

• document the protocol in a reproducible, implementation-oriented way
• provide a Linux user-space SG_IO driver and CLI that follows that protocol safely

What this repo contains

• PROTOCOL_MAP.md: canonical protocol map, command surface, and behavior notes
• linux_driver/: Rust library + CLI implementation (integral-unlock)
• flake.nix: reproducible validation and build environment
• packaging/alpine/: APKBUILD and setup guide for Alpine Linux

Private reverse-analysis notes, tooling, and raw capture artifacts are intentionally not included.

Project model

The device unlock flow is implemented as a strict 3-round auth/session handshake, followed by unlock or password-change operations over vendor SCSI commands.

Implementation priorities:

• fail-closed behavior on protocol mismatches and anomalous responses
• explicit safety gates around risky operations
• no plaintext password argv flags for unlock/change-password
• trace/output redaction of secret-derived data

The public tree uses scrubbed placeholder auth material; live unlock requires private auth material supplied at runtime.

Install on Alpine Linux

The driver is pure Rust over the Linux SG_IO ioctl with no glibc dependency, so it runs on Alpine (musl) natively. Three ways to get it there:

• Prebuilt static binary — download integral-unlock-x86_64-linux-musl from the latest release, chmod +x, and run. Built by .github/workflows/release.yml on each tag.
• apk package — build the APKBUILD in packaging/alpine/ with abuild -r for a native .apk that installs the binary and the sg autoload config.
• Nix — nix build .#integralUnlockX64Musl produces the same static musl binary on any host with Nix.

Full Alpine setup (loading the sg driver, mapping the two LUNs, supplying private auth material, permissions) is in packaging/alpine/README.md.

Where to start

• protocol overview: PROTOCOL_MAP.md
• driver design and CLI details: linux_driver/README.md
• Alpine install and runtime setup: packaging/alpine/README.md
• release checks: PUBLISH_CHECKLIST.md

License

MIT (LICENSE)