NAME

POE::Component::YubiAuth - Use Yubico Web Service API to verify YubiKey one time passwords.

SYNOPSIS

POE::Component::YubiAuth uses Yubico's public Web Service API to verify One Time Passwords generated by Yubikey.

    use POE::Component::YubiAuth;

    # Get your API id and key at https://api.yubico.com/get-api-key/
    POE::Component::YubiAuth->spawn('<api id>', '<api key>');

    # subref as callback
    POE::Kernel->post('yubi', 'verify', '<otp data>', sub {
        print Data::Dumper::Dumper($_[0]);
    });

    # session event as callback
    POE::Session->create(
        inline_states => {
            _start => sub {
                my ($kernel, $heap) = @_[KERNEL, HEAP];
                $kernel->post('yubi', 'verify', '<otp data>', 'dump');
                $kernel->alias_set('foo');
            },
            dump => sub {
                my ($kernel, $heap) = @_[KERNEL, HEAP];
                print Data::Dumper::Dumper($_[ARG0]);
                $kernel->alias_remove;
                $kernel->post('yubi', 'shutdown');
            },
        }
    );
    POE::Kernel->run();

CONSTRUCTOR

POE::Component::YubiAuth->spawn(<api id>, <api key>)

spawn() takes Yubico API ID and API key as parameters and spawns a POE session named 'yubi' that will respond to various events later:

    POE::Kernel->post('yubi', 'verify', ...);
        or
    $kernel->post('yubi', 'shutdown');

Verification requests will be signed with the API key.

EVENTS

verify

verify() takes three parameters - One Time Password, a callback event and optional callback data.

Callback can be a subroutine reference or a name of a POE event in the current session. Examples on how to use both types of callbacks are provided in the SYNOPSIS.

    POE::Kernel->post('yubi', 'verify', '<otp data>', sub {
        print Data::Dumper::Dumper(\@_);
    }, 'some callback data');

The callback will receive a hash reference with response from Yubico's server and the provided callback data, which may be used to identify the response. For caller's convenience, Yubikey's id extracted from the one time password is added to the hash under the name 'keyid'.

If the 'status' key in the response has the value 'OK', then the verification process was successfull. If callback receives an undefined value instead of a hash reference, then some strange error has occured (e.g. no connection to the Yubico's server).

Please visit http://www.yubico.com/developers/api/ for more information.

shutdown

shutdown() terminates the 'yubi' session.

AUTHOR

Kirill Miazine, <km@krot.org>

COPYRIGHT & LICENSE

Copyright 2010 Kirill Miazine.

This software is distributed under an ISC-style license, please see <http://km.krot.org/code/license.txt> for details.