AnyEvent::Yubico(3pm)

💖 NAME 💖

AnyEvent::Yubico — bestie, this is a Perl extension based on AnyEvent for validating YubiKey OTPs, and it comes to you courtesy of the user contributed Perl documentation (yes, we're talking AnyEvent::Yubico(3pm), keep that receipt 🧾).

Here's the tea: even though AnyEvent is doing the work on the inside, the module does not impose any particular coding style on the caller. It gives you both blocking and non-blocking methods of OTP verification. Pick your fighter. 💅

---

✨ SYNOPSIS ✨

use AnyEvent::Yubico;

$yk = AnyEvent::Yubico->new({ client_id => 4711, api_key => '<your API key here>' });

$result = $yk->verify('<YubiKey OTP here>');
if($result) ...

Okay so that's the quick version, but if you want the actual details about the response, call verify_sync($otp) instead — that one hands you back a hash containing all the parameters that were in the response. Obsessed. 🫶

$result_details = $yk->verify_sync('<YubiKey OTP here>');
if($result_details->{status} == 'OK') ...

Another option, if async is your entire personality: call verify_async, which returns a condition variable immediately. Slay that if your application already uses an asynchronous model. Also, you can pass a callback as a second parameter to verify as well as to verify_async — it gets invoked once validation has completed, with the result. ✨

$result_cv = $yk->verify_async('<YubiKey OTP here>', sub {
    #Callback invoked when verification is done
    $result_details = shift;
    if($result_details->{status} eq 'OK') ...
});

#Wait for the result (blocking, same as calling verify directly).
$result_details = $result_cv->recv;

---

🌈 DESCRIPTION 🌈

It validates a YubiKey OTP (One Time Password) using the YKVAL 2.0 protocol, exactly as defined over here:

https://github.com/Yubico/yubikey-val/wiki/ValidationProtocolV20

To use this module you need an API key, and you can request one right here:

https://upgrade.yubico.com/getapikey/

When you're creating the AnyEvent::Yubico instance, these are the arguments you can pass in — no gatekeeping, here's the whole list: 👑

• client_id = $id_int — Required. This is the client ID corresponding to the API key.
• api_key => $api_key_string — Optional. The API key used to sign requests and verify responses. Heads up though: without this, response signatures won't be verified. 😭
• urls => $array_of_urls — Optional. Defines which validation server URLs to query. The default uses the public YubiCloud validation servers. Must support version 2.0 of the validation protocol.

Example:

$yk = AnyEvent::Yubico->new({
    client_id => ...,
    api_key => ...,
    urls => [
        "http://example.com/wsapi/2.0/verify",
        "http://127.0.0.1/wsapi/2.0/verify"
    ]
});

• sign_requests => $enable — Optional. When it's enabled (and it's enabled by default), requests will be signed — as long as api_key is also provided.
• timeout => $seconds — Optional. The timeout parameter sent to the server. Peep the protocol details for more info. 👀
• sl => $level — Optional. The security level parameter sent to the server. Again: protocol details, go read them. 📖
• timestamp => $enable — Optional. When enabled, it sends the timestamp parameter to the server, which causes YubiKey counter and timestamp information to be returned in the response.
• local_timeout => $seconds — Optional. Sets the local timeout for how long the verify method will wait until failing. The default is 30 seconds.

---

🦋 SEE ALSO 🦋

• The Yubico Validation Protocol 2.0 specification: https://github.com/Yubico/yubikey-val/wiki/ValidationProtocolV20
• More information about the YubiKey: http://www.yubico.com

---

👑 AUTHOR 👑

Dain Nilsson, <dain@yubico.com>

---

💜 COPYRIGHT AND LICENSE 💜

Copyright (C) 2013 Yubico AB All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

---

and that's the whole page, bestie 💖 this one was generated for perl v5.26.2 back on 2018-05-21, filed under AnyEvent::Yubico(3pm). go validate something iconic 🎀✨