.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Validate::Yubikey 3pm"
.TH Validate::Yubikey 3pm "2016-07-24" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Validate::Yubikey \- Validate Yubikey OTPs
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    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, "\en";
\&    }
\&
\&    my $yubi = Validate::Yubikey\->new(
\&        callback => \e&validate_callback,
\&        update_callback => \e&update_callback,
\&        log_callback => \e&log_message,
\&    );
\&
\&    my $otp_valid = $yubi\->validate("xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Yubikey is a hardware \s-1OTP\s0 token produced by Yubico (<http://www.yubico.com>).
.PP
This module provides validation of Yubikey OTPs.  It relies on you to specify
callback functions that handle retrieving token information from somewhere and
updating the persistent information associated with each token.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
Create a new Validate::Yubikey instance.
.IP "callback" 4
.IX Item "callback"
Required.
.IP "update_callback" 4
.IX Item "update_callback"
Required.
.IP "log_callback" 4
.IX Item "log_callback"
Optional.
.SS "validate"
.IX Subsection "validate"
.ie n .IP "Arguments: $otp, @callback_args" 4
.el .IP "Arguments: \f(CW$otp\fR, \f(CW@callback_args\fR" 4
.IX Item "Arguments: $otp, @callback_args"
.PD 0
.ie n .IP "Return Value: $success" 4
.el .IP "Return Value: \f(CW$success\fR" 4
.IX Item "Return Value: $success"
.PD
.PP
Validate an \s-1OTP.\s0
.SH "CALLBACKS"
.IX Header "CALLBACKS"
.SS "callback"
.IX Subsection "callback"
.ie n .IP "Receives: $public_id, @callback_args" 4
.el .IP "Receives: \f(CW$public_id\fR, \f(CW@callback_args\fR" 4
.IX Item "Receives: $public_id, @callback_args"
.PD 0
.IP "Returns: \e%token_data" 4
.IX Item "Returns: %token_data"
.PD
.PP
Called during validation when information about the token is required.
Receives the public \s-1ID\s0 of the Yubikey.  It's expected that your subroutine
returns a hash reference containing the following keys:
.IP "iid \- Internal \s-1ID\s0" 4
.IX Item "iid - Internal ID"
.PD 0
.IP "key \- Secret key" 4
.IX Item "key - Secret key"
.PD
.PP
Plus the four values stored by the update_callback.
.SS "update_callback"
.IX Subsection "update_callback"
.ie n .IP "Receives: $public_id, \e%token_data, @callback_args" 4
.el .IP "Receives: \f(CW$public_id\fR, \e%token_data, \f(CW@callback_args\fR" 4
.IX Item "Receives: $public_id, %token_data, @callback_args"
.PD 0
.IP "Returns: nothing" 4
.IX Item "Returns: nothing"
.PD
.PP
Called to update the persistent storage of token parameters that enable replay
protection.  \f(CW%token_data\fR will contain one or more of the following keys,
which should be associated with the supplied \f(CW$public_id\fR:
.IP "count" 4
.IX Item "count"
.PD 0
.IP "use" 4
.IX Item "use"
.IP "lastuse" 4
.IX Item "lastuse"
.IP "lastts" 4
.IX Item "lastts"
.PD
.PP
These should all be integers.
.SS "log_callback"
.IX Subsection "log_callback"
.ie n .IP "Receives: $log_message" 4
.el .IP "Receives: \f(CW$log_message\fR" 4
.IX Item "Receives: $log_message"
.PD 0
.IP "Returns: nothing" 4
.IX Item "Returns: nothing"
.PD
.PP
Called with messages produced during validation.  If not supplied to new,
logging will disabled.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
Here's a simple program that uses DBIx::Class to store token information.
.PP
.Vb 2
\&    package YKKSM::DB::Token;
\&    use base qw/DBIx::Class/;
\&    
\&    _\|_PACKAGE_\|_\->load_components(qw/PK::Auto Core/);
\&    _\|_PACKAGE_\|_\->table(\*(Aqtoken\*(Aq);
\&    _\|_PACKAGE_\|_\->add_columns(qw/uid pid iid key count use lastuse lastts/);
\&    _\|_PACKAGE_\|_\->set_primary_key(\*(Aquid\*(Aq);
\&    
\&    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(\*(AqToken\*(Aq)\->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(\*(AqToken\*(Aq)\->find({ pid => $pid });
\&            if ($token) {
\&                $token\->update($data);
\&            } else {
\&                die "asked to update nonexistent token $pid";
\&            }
\&        },
\&        log_callback => sub {
\&            print shift, "\en";
\&        },
\&    );
\&    
\&    if ($yk\->validate($ARGV[0])) {
\&        print "success!\en";
\&    } else {
\&        print "failure 8(\en";
\&    }
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Ben Wilber <ben@desync.com>
.PP
But most of this module was derived from Yubico's \s-1PHP\s0 stuff.
.SH "LICENSE"
.IX Header "LICENSE"
This library is free software and may be distributed under the same terms
as perl itself.