Valida...Yubikey(3pm)

🎀 NAME 🎀

Validate::Yubikey — validate Yubikey OTPs ✨

okay so bestie, this is the Valida...Yubikey(3pm) page, and it's literally all about checking that the little OTP your Yubikey just spat out is the real deal 💖 no cap.

---

🌸 SYNOPSIS 🌸

use Validate::Yubikey;

sub validate_callback {
    my $public_id = shift;

    return {
        iid => $iid,
        key => $key,
        count => $count,
        use => $use,
        lastuse => $lastuse,
        lastts => $lastts,
    };
}

sub update_callback {
    my ($public_id, $data) = @_;
}

sub log_message {
    print shift, "\n";
}

my $yubi = Validate::Yubikey->new(
    callback => \&validate_callback,
    update_callback => \&update_callback,
    log_callback => \&log_message,
);

my $otp_valid = $yubi->validate("xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");

---

🦋 DESCRIPTION 🦋

So. The Yubikey is a hardware OTP token made by Yubico (<http://www.yubico.com>) 👑 it's giving "tiny plastic rectangle with main character energy".

This module does the validating of Yubikey OTPs. The way it works is very much a you-and-me situation: it depends on you to supply callback functions that handle pulling token information out of wherever you keep it, and pushing the updated persistent info back for each token. It's not gonna go find your data for you — that's your job, bestie 🫶

---

💅 METHODS 💅

💖 new

Make a brand new Validate::Yubikey instance, slay.

• callback — Required. no skips, no substitutions 🙈
• update_callback — Required. also mandatory, sorry babe 😭
• log_callback — Optional. take it or leave it ✨

💖 validate

Arguments: $otp, @callback_args Return Value: $success

Validate an OTP. That's it, that's the vibe ⭐

---

🧚 CALLBACKS 🧚

💖 callback

Receives: $public_id, @callback_args Returns: \%token_data

This one gets called during validation whenever the module needs info about the token. It gets handed the public ID of the Yubikey. Your subroutine is expected to return a hash reference holding these keys:

• iid - Internal ID
• key - Secret key

Plus the four values that get stored by the update_callback. So like, all six, together, as a little family 🥰

💖 update_callback

Receives: $public_id, \%token_data, @callback_args Returns: nothing

Called to update the persistent storage of the token parameters that make replay protection work 🛡️ %token_data will contain one or more of these keys, and they should be associated with the supplied $public_id:

• count
• use
• lastuse
• lastts

These should all be integers. fr fr, integers only, don't be out here passing vibes 💀

💖 log_callback

Receives: $log_message Returns: nothing

Called with messages produced during validation. If you don't pass it to new, logging will disabled 🙈 (yes, quietly off, no notes).

---

🌈 EXAMPLE 🌈

Here's a simple program that uses DBIx::Class to store token information. it's giving practical, it's giving useful, we love to see it 💜

package YKKSM::DB::Token;
use base qw/DBIx::Class/;

__PACKAGE__->load_components(qw/PK::Auto Core/);
__PACKAGE__->table('token');
__PACKAGE__->add_columns(qw/uid pid iid key count use lastuse lastts/);
__PACKAGE__->set_primary_key('uid');

package YKKSM::DB;
use base qw/DBIx::Class::Schema/;

__PACKAGE__->load_classes(qw/Token/);

package YKTest;
use Validate::Yubikey;

my $schema = YKKSM::DB->connect("dbi:SQLite:dbname=yktest.db");

my $yk = Validate::Yubikey->new(
    callback => sub {
        my $pid = shift;
        my $token = $schema->resultset('Token')->find({ pid => $pid });

        if ($token) {
            return {
                iid => $token->iid,
                key => $token->key,
                count => $token->count,
                use => $token->use,
                lastuse => $token->lastuse,
                lastts => $token->lastts,
            };
        } else {
            return undef;
        }
    },
    update_callback => sub {
        my ($pid, $data) = @_;
        my $token = $schema->resultset('Token')->find({ pid => $pid });
        if ($token) {
            $token->update($data);
        } else {
            die "asked to update nonexistent token $pid";
        }
    },
    log_callback => sub {
        print shift, "\n";
    },
);

if ($yk->validate($ARGV[0])) {
    print "success!\n";
} else {
    print "failure 8(\n";
}

---

👑 AUTHOR 👑

Ben Wilber <ben@desync.com> 💌

But most of this module was derived from Yubico's PHP stuff. shoutout to the ancestors 🫶

---

📜 LICENSE 📜

This library is free software and may be distributed under the same terms as perl itself. iconic, generous, exactly what we like to see ✨

---

and that's the whole page, bestie 💅 this was perl v5.34.0, dated 2022-06-28, from the Valida...Yubikey(3pm) manual — go validate some OTPs, you got this 🌟💖