ykoxide: my YubiKey toolbox, rewritten as a single Rust binary

Also available in Portuguese: ykoxide: a minha caixa de ferramentas da YubiKey virou um binário em Rust.

In the YubiKey series I went from 2FA-because-you-have-to to sudo, SSH and GPG, and ended up at file encryption with age. The scripts from that phase live in yubikey-shell-toolkit. They work, but they depend on ykman, age and openssl being installed.

ykoxide is the Rust rewrite: a single binary, ykox, with none of those runtime dependencies. It reads the files and configuration the scripts created, so what you already encrypted keeps opening.

What it does

age on a PIV slot, interoperable with age-plugin-yubikey in both directions
file encryption with the OTP slot in HMAC-SHA1 challenge-response mode
file encryption with FIDO2 hmac-secret (experimental)
SSHSIG signing, with a FIDO2 (sk) key or a PIV slot, verifiable with ssh-keygen -Y verify
a device report and configuration backup as JSON, with no secrets in it

Basic usage:

ykox info                        # is the key detected?
ykox age setup                   # extract (or generate) the age identity on the key
ykox age encrypt secret.txt      # secret.txt.age
ykox age decrypt secret.txt.age
ykox sign report.pdf             # report.pdf.sig

With more than one YubiKey plugged in, --serial <N> picks which one to use. FIDO2 is the exception, because its HID interface does not report a serial.

Installation

cargo install ykoxide --locked   # builds from source
cargo binstall ykoxide           # downloads the release binary instead

Tarballs for Linux x86_64 and aarch64 are also on the releases page, with SHA256SUMS and, from 0.1.1 on, a build provenance attestation. Tags are GPG-signed.

At runtime it needs pcscd running (sudo systemctl enable --now pcscd.socket). On Arch, also install pcsclite and ccid; on Fedora, pcsc-lite and pcsc-lite-ccid. Building needs the PC/SC and udev headers.

What was tested

It is still pre-1.0, and the README spells out exactly what was exercised on hardware:

Systems: Fedora 44 and Omarchy 4.0.3 (Arch-based), both x86_64.
Keys: YubiKey 5 NFC (firmware 5.2.6) and YubiKey 5C (firmware 5.4.3).
Checked against the reference tools: age files interoperate with age-plugin-yubikey, the HMAC response matches ykman otp calculate, and .yk.enc files from the old toolkit decrypt.
FIDO2 only works end to end from 0.1.2 on. Earlier releases failed with CTAP2_ERR_UNSUPPORTED_OPTION on tokens without built-in user verification, which includes the 5 series. The format is specific to ykox and does not interoperate with age-plugin-fido2-hmac.
Not exercised on hardware: age setup --generate, a Security Key, and aarch64 with a key (the binary is built and tested in CI, but has never run against one).

Two security notes worth repeating here. ykox protects the key material, not the plaintext: malware on the host that reads the already decrypted file is still your problem. And the legacy .yk.enc format is unauthenticated, so a wrong key passes about 1 time in 256. Always prefer .yk.age.

The YubiKey series on this blog

If you landed here without the background, this is the order. The first group is in Portuguese:

And in English:

The code is at github.com/Esl1h/ykoxide and the package at crates.io. MIT licensed.