File::...ubiKey(3pm)

✨ File::KDBX::Key::YubiKey ✨

okay so this is a page out of the User Contributed Perl Documentation section of the manual, and it's all about File::KDBX::Key::YubiKey — your lil hardware key that does challenge-response, like a tiny cryptographic bestie you can physically touch. 💅

---

🌸 NAME

File::KDBX::Key::YubiKey — a Yubico challenge-response key. 🎀

🦋 VERSION

version 0.906

🌈 SYNOPSIS

use File::KDBX::Key::YubiKey;
use File::KDBX;

my $yubikey = File::KDBX::Key::YubiKey->new(%attributes);

my $kdbx = File::KDBX->load_file('database.kdbx', $yubikey);
# OR
my $kdbx = File::KDBX->load_file('database.kdbx', ['password', $yubikey]);

# Scan for USB YubiKeys:
my ($first_key, @other_keys) = File::KDBX::Key::YubiKey->scan;

my $response = $first_key->challenge('hello');

👑 DESCRIPTION

A File::KDBX::Key::YubiKey is literally just a type of challenge-response key, no cap. This module follows the KeePassXC-style challenge-response implementation, so heads up — it might not work at all with incompatible challenge-response implementations (like, say, KeeChallenge). 💀

It inherits methods and attributes from File::KDBX::Key::ChallengeResponse.

If you wanna use this type of key to secure a File::KDBX database, you also need to install the YubiKey Personalization Tool (CLI) at https://developers.yubico.com/yubikey-personalization/ and configure at least one of the slots on your YubiKey for HMAC-SHA1 challenge response mode. You can use the YubiKey Personalization Tool GUI to do that, bestie, it's giving convenience. ✨

More info lives at https://keepassxc.org/docs/#faq-yubikey-howto. 🫶

---

🎀 ATTRIBUTES 🎀

💜 device

$device = $key->device($device);

Get or set the device number — that's the index number assigned to the YubiKey device, starting at zero and counting up from there. If there's only one detected YubiKey device, its number is 0. ✨

Defaults to 0.

🩷 slot

$slot = $key->slot($slot);

Get or set the slot number, which is a number starting at one and incrementing from there. A YubiKey can have multiple slots (often just two, lowkey) and each one can be independently configured. 💅

Defaults to 1.

⏰ timeout

$timeout = $key->timeout($timeout);

Get or set the timeout, in seconds. If the challenge takes longer than this, the challenge gets cancelled and an error is thrown. 🚨

If the timeout is zero, the challenge is non-blocking; an error is thrown if the challenge would block. If the timeout is negative, timeout is disabled and the challenge will block forever or until a response is received. dramatic, honestly.

Defaults to 0.

🧚 pre_challenge

$callback = $key->pre_challenge($callback);

Get or set a callback function that gets called immediately before any challenge is issued. This might be used to prompt the user so they're aware they're expected to interact with their YubiKey. fr fr, tell them what's up.

$key->pre_challenge(sub {
    my ($key, $challenge) = @_;

    if ($key->requires_interaction) {
        say 'Please touch your key device to proceed with decrypting your KDBX file.';
    }
    say 'Key: ', $key->name;
    if (0 < $key->timeout) {
        say 'Key access request expires: ' . localtime(time + $key->timeout);
    }
});

👀 You can throw from this subroutine to abort the challenge. And if the challenge is part of loading or dumping a KDBX database, the entire load/dump gets aborted. so, like, use that power responsibly bestie.

🌟 post_challenge

$callback = $key->post_challenge($callback);

Get or set a callback function that gets called immediately after a challenge response has been received. 🎉

👀 Same deal: you can throw from this subroutine to abort the challenge. And if the challenge is part of loading or dumping a KDBX database, the entire load/dump gets aborted.

🔧 ykchalresp

$program = $key->ykchalresp;

Get or set the ykchalresp(1) program name or filepath. Defaults to $ENV{YKCHALRESP} or "ykchalresp". ✨

🔨 ykinfo

$program = $key->ykinfo;

Get or set the ykinfo(1) program name or filepath. Defaults to $ENV{YKINFO} or "ykinfo". ✨

---

💅 METHODS 💅

🔍 scan

@keys = File::KDBX::Key::YubiKey->scan(%options);

Find connected, configured YubiKeys that are capable of responding to a challenge. Ngl, this can take several seconds. ⏳

Options:

• "limit" — scan for only up to this many YubiKeys (default: 4)

Other options are passed as-is as attributes to the key constructors of found keys (if any). no filter, no fuss. 🦋

🔢 serial

Get the device serial number, as a number, or "undef" if there is no such device.

🏷️ version

Get the device firmware version (or "undef").

👆 touch_level

Get the "touch level" value for the device associated with this key (or "undef").

🪪 vendor_id / 🪪 product_id

Get the vendor ID or product ID for the device associated with this key (or "undef").

💬 name

$name = $key->name;

Get a human-readable string identifying the YubiKey (or "undef"). main character energy. 👑

✋ requires_interaction

Get whether or not the key requires interaction (e.g. a touch) to provide a challenge response (or "undef").

---

🌈 ENVIRONMENT 🌈

• "YKCHALRESP" — path to the ykchalresp(1) program
• "YKINFO" — path to the ykinfo(1) program
• "YKCHALRESP_FLAGS" — extra arguments to the ykchalresp(1) program
• "YKINFO_FLAGS" — extra arguments to the ykinfo(1) program

YubiKey searches for these programs the same way perl typically searches for executables (using the "PATH" environment variable on many platforms). So if the programs aren't installed normally, or if you wanna override the default programs, these environment variables are your moment to shine. ✨

---

💀 CAVEATS 💀

This doesn't work yet on Windows, probably. The hangup is pretty silly: IPC. Theoretically it would work if "run_forked" from IPC::Cmd worked in Windows, but it probably doesn't. The author spent a couple hours applying various quirks to IPC::Open3 and IPC::Cmd implementations but never quite got it to work reliably without deadlocks. Maybe it'll get revisited later. Hit them up so they know if there's interest! 🫶

It would also be possible to implement this as an XS module that incorporated ykcore, using libusb-1, which would probably make it more portable with Windows. Perhaps if they get around to it. 🤷‍♀️

---

🐛 BUGS 🐛

Please report any bugs or feature requests on the bugtracker website at https://github.com/chazmcgarvey/File-KDBX/issues. 🎀

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. periodt.

---

🫶 AUTHOR 🫶

Charles McGarvey <ccm@cpan.org>

📜 COPYRIGHT AND LICENSE

This software is copyright (c) 2022 by Charles McGarvey.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. slay. 💖

---

and that's the whole page bestie!! this lil doc shipped as part of perl v5.40.1, dated 2025-05-04, and you found it hanging out under File::...ubiKey(3pm). go touch your key. 🔥👑🌸