Provided by: libfile-kdbx-perl_0.906-2_all 
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 a type of challenge-response key. This module follows the
KeePassXC-style challenge-response implementation, so this might not work at all with
incompatible challenge-response implementations (e.g. KeeChallenge).
Inherets methods and attributes from File::KDBX::Key::ChallengeResponse.
To use this type of key to secure a File::KDBX database, you also need to install the
YubiKey Personalization Tool (CLI) <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 this.
See <https://keepassxc.org/docs/#faq-yubikey-howto> for more information.
ATTRIBUTES
device
$device = $key->device($device);
Get or set the device number, which is the index number starting and incrementing from
zero assigned to the YubiKey device. If there is 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 and incrementing from one. A
YubiKey can have multiple slots (often just two) which 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
will be 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.
Defaults to 0.
pre_challenge
$callback = $key->pre_challenge($callback);
Get or set a callback function that will be called immediately before any challenge is
issued. This might be used to prompt the user so they are aware that they are expected to
interact with their YubiKey.
$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. If the challenge is part of
loading or dumping a KDBX database, the entire load/dump will be aborted.
post_challenge
$callback = $key->post_challenge($callback);
Get or set a callback function that will be called immediately after a challenge response
has been received.
You can throw from this subroutine to abort the challenge. If the challenge is part of
loading or dumping a KDBX database, the entire load/dump will be 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. 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).
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").
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 in the same way perl typically searches for
executables (using the "PATH" environment variable on many platforms). If the programs
aren't installed normally, or if you want to override the default programs, these
environment variables can be used.
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. I
spent a couple hours applying various quirks to IPC::Open3 and IPC::Cmd implementations
but never quite got it to worked reliably without deadlocks. Maybe I'll revisit this
later. Hit me up so I 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 I get
around to it.
BUGS
Please report any bugs or feature requests on the bugtracker website
<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.
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.