1File::KDBX::Key::YubiKeUys(e3r)Contributed Perl DocumentFaitlieo:n:KDBX::Key::YubiKey(3)
2
3
4

NAME

6       File::KDBX::Key::YubiKey - A Yubico challenge-response key
7

VERSION

9       version 0.906
10

SYNOPSIS

12           use File::KDBX::Key::YubiKey;
13           use File::KDBX;
14
15           my $yubikey = File::KDBX::Key::YubiKey->new(%attributes);
16
17           my $kdbx = File::KDBX->load_file('database.kdbx', $yubikey);
18           # OR
19           my $kdbx = File::KDBX->load_file('database.kdbx', ['password', $yubikey]);
20
21           # Scan for USB YubiKeys:
22           my ($first_key, @other_keys) = File::KDBX::Key::YubiKey->scan;
23
24           my $response = $first_key->challenge('hello');
25

DESCRIPTION

27       A File::KDBX::Key::YubiKey is a type of challenge-response key. This
28       module follows the KeePassXC-style challenge-response implementation,
29       so this might not work at all with incompatible challenge-response
30       implementations (e.g. KeeChallenge).
31
32       Inherets methods and attributes from
33       File::KDBX::Key::ChallengeResponse.
34
35       To use this type of key to secure a File::KDBX database, you also need
36       to install the YubiKey Personalization Tool (CLI)
37       <https://developers.yubico.com/yubikey-personalization/> and configure
38       at least one of the slots on your YubiKey for HMAC-SHA1 challenge
39       response mode. You can use the YubiKey Personalization Tool GUI to do
40       this.
41
42       See <https://keepassxc.org/docs/#faq-yubikey-howto> for more
43       information.
44

ATTRIBUTES

46   device
47           $device = $key->device($device);
48
49       Get or set the device number, which is the index number starting and
50       incrementing from zero assigned to the YubiKey device. If there is only
51       one detected YubiKey device, its number is 0.
52
53       Defaults to 0.
54
55   slot
56           $slot = $key->slot($slot);
57
58       Get or set the slot number, which is a number starting and incrementing
59       from one. A YubiKey can have multiple slots (often just two) which can
60       be independently configured.
61
62       Defaults to 1.
63
64   timeout
65           $timeout = $key->timeout($timeout);
66
67       Get or set the timeout, in seconds. If the challenge takes longer than
68       this, the challenge will be cancelled and an error is thrown.
69
70       If the timeout is zero, the challenge is non-blocking; an error is
71       thrown if the challenge would block. If the timeout is negative,
72       timeout is disabled and the challenge will block forever or until a
73       response is received.
74
75       Defaults to 0.
76
77   pre_challenge
78           $callback = $key->pre_challenge($callback);
79
80       Get or set a callback function that will be called immediately before
81       any challenge is issued. This might be used to prompt the user so they
82       are aware that they are expected to interact with their YubiKey.
83
84           $key->pre_challenge(sub {
85               my ($key, $challenge) = @_;
86
87               if ($key->requires_interaction) {
88                   say 'Please touch your key device to proceed with decrypting your KDBX file.';
89               }
90               say 'Key: ', $key->name;
91               if (0 < $key->timeout) {
92                   say 'Key access request expires: ' . localtime(time + $key->timeout);
93               }
94           });
95
96       You can throw from this subroutine to abort the challenge. If the
97       challenge is part of loading or dumping a KDBX database, the entire
98       load/dump will be aborted.
99
100   post_challenge
101           $callback = $key->post_challenge($callback);
102
103       Get or set a callback function that will be called immediately after a
104       challenge response has been received.
105
106       You can throw from this subroutine to abort the challenge. If the
107       challenge is part of loading or dumping a KDBX database, the entire
108       load/dump will be aborted.
109
110   ykchalresp
111           $program = $key->ykchalresp;
112
113       Get or set the ykchalresp(1) program name or filepath. Defaults to
114       $ENV{YKCHALRESP} or "ykchalresp".
115
116   ykinfo
117           $program = $key->ykinfo;
118
119       Get or set the ykinfo(1) program name or filepath. Defaults to
120       $ENV{YKINFO} or "ykinfo".
121

METHODS

123   scan
124           @keys = File::KDBX::Key::YubiKey->scan(%options);
125
126       Find connected, configured YubiKeys that are capable of responding to a
127       challenge. This can take several seconds.
128
129       Options:
130
131       •   "limit" - Scan for only up to this many YubiKeys (default: 4)
132
133       Other options are passed as-is as attributes to the key constructors of
134       found keys (if any).
135
136   serial
137       Get the device serial number, as a number, or "undef" if there is no
138       such device.
139
140   version
141       Get the device firmware version (or "undef").
142
143   touch_level
144       Get the "touch level" value for the device associated with this key (or
145       "undef").
146
147   vendor_id
148   product_id
149       Get the vendor ID or product ID for the device associated with this key
150       (or "undef").
151
152   name
153           $name = $key->name;
154
155       Get a human-readable string identifying the YubiKey (or "undef").
156
157   requires_interaction
158       Get whether or not the key requires interaction (e.g. a touch) to
159       provide a challenge response (or "undef").
160

ENVIRONMENT

162       •   "YKCHALRESP" - Path to the ykchalresp(1) program
163
164       •   "YKINFO" - Path to the ykinfo(1) program
165
166       •   "YKCHALRESP_FLAGS" - Extra arguments to the ykchalresp(1) program
167
168       •   "YKINFO_FLAGS" - Extra arguments to the ykinfo(1) program
169
170       YubiKey searches for these programs in the same way perl typically
171       searches for executables (using the "PATH" environment variable on many
172       platforms). If the programs aren't installed normally, or if you want
173       to override the default programs, these environment variables can be
174       used.
175

CAVEATS

177       This doesn't work yet on Windows, probably. The hangup is pretty silly:
178       IPC. Theoretically it would work if "run_forked" from IPC::Cmd worked
179       in Windows, but it probably doesn't. I spent a couple hours applying
180       various quirks to IPC::Open3 and IPC::Cmd implementations but never
181       quite got it to worked reliably without deadlocks. Maybe I'll revisit
182       this later. Hit me up so I know if there's interest.
183
184       It would also be possible to implement this as an XS module that
185       incorporated ykcore, using libusb-1 which would probably make it more
186       portable with Windows. Perhaps if I get around to it.
187

BUGS

189       Please report any bugs or feature requests on the bugtracker website
190       <https://github.com/chazmcgarvey/File-KDBX/issues>
191
192       When submitting a bug or request, please include a test-file or a patch
193       to an existing test-file that illustrates the bug or desired feature.
194

AUTHOR

196       Charles McGarvey <ccm@cpan.org>
197

199       This software is copyright (c) 2022 by Charles McGarvey.
200
201       This is free software; you can redistribute it and/or modify it under
202       the same terms as the Perl 5 programming language system itself.
203
204
205
206perl v5.36.1                      2023-09-27       File::KDBX::Key::YubiKey(3)
Impressum