NAME

POE::Component::YubiAuth - Use Yubico Web Service API to check 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>', '<optionally 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 optionally 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');

If API key is provided, verification requests will be signed with the 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.

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.