NAME
Crypt::MultiKey::PKey::YKChalResp - Use a YubiKey OTP challenge/response to encrypt/decrypt the private key
DESCRIPTION
This module uses the YubiKey OTP protocol's challenge/response feature to generate a password to decrypt the private half of a PKey. Not all YubiKeys support the OTP protocol, particularly the cheaper "Security Key" variety. (for those, see Crypt::MultiKey::PKey::FIDO2) You must have also configured one of the slots on your YubiKey to allow challenge/response.
Linux support is available via XS. Other platforms are supported by the external tools ykinfo(1) and ykchalresp(1), which you must install separately.
ATTRIBUTES
yubikey_serial
This identifies which YubiKey to issue the challenge to. You can see a YubiKey's serial number (from the OTP protocol) using ykinfo -s.
If assigned prior to "encrypt_private", it forces that method to use only that key for the encryption. Otherwise, that method uses the first available key and assigns this attribute with the serial of whichever one it used.
yubikey_slot
Either 1 or 2. The YubiKey OTP protocol defines two slots which can be configured for challenge/response. The default is to attempt them both and record which slot was used.
kdf_salt
Random salt (base64) used to build the YubiKey challenge.
METHODS
list_yubikeys
Return a list of hashrefs about any connected YubiKeys (limited to those which support the OTP protocol)
can_obtain_private
Returns true if the configured YubiKey serial number is connected. Returns undef on a permanent error like if the Yubico OTP tools can't be found.
obtain_private
Pass the challenge to the configured YubiKey, and "decrypt_private" using the response as a password.
encrypt_private
Encrypt the private key using a password derived from YubiKey challenge/response.
$pkey->encrypt_private;
$pkey->encrypt_private($serial_number_or_yk_device);If no serial is provided, this picks the first detected key and records its serial.
SECURITY MODEL
This mechanism of challenge/response basically just takes a local string of public bytes and a string of secret bytes within the YubiKey, runs them both through SHA-1 within the device, and returns a portion of the result. This mode of operation is just making use of the YubiKey as an un-copyable string of bytes which can only be hashed when touching the button of the device. Anyone who can see the contents of your PKey PEM file can reconstruct the challenge, and if they then have access to the YubiKey (including a button press) they can capture the response, and use it to decrypt the PKey. Someone who knows the correct response could also build a fake USB device that emits the correct response without actually knowing the secret.
For comparison, FIDO2 authenticates the identify of the hardware device so that it can't be faked even if an attacker knows the correct response for a challenge. The downside with FIDO2 is that it requires an enrollment process and credential stored on the device for each enrolled PKey. This YKChalResp key can be set up without storing anything on the authenticator device.
VERSION
version 0.000_001
AUTHOR
Michael Conrad <mike@nrdvana.net>
COPYRIGHT AND LICENSE
This software is copyright (c) 2026 by Michael Conrad.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.