NAME

       AnyEvent::Yubico - AnyEvent based Perl extension for validating YubiKey OTPs.  Though AnyEvent is used
       internally, the module does not impose any particular coding style on the caller. Provides both blocking
       and non-blocking methods of OTP verification.

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) ...

       For more details about the response, instead call verify_sync($otp), which returns a hash containing all
       the parameters that were in the response.

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

       As an alternative, you can call verify_async, which will return a condition variable immediately. This
       can be used if your application already uses an asynchronous model. You can also pass a callback as a
       second parameter to verify as well as verify_async, which will be 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

       Validates a YubiKey OTP (One Time Password) using the YKVAL 2.0 protocol as defined here:
       https://github.com/Yubico/yubikey-val/wiki/ValidationProtocolV20

       To use this module, an API key is required, which can be requested here:
       https://upgrade.yubico.com/getapikey/

       When creating the AnyEvent::Yubico instance, the following arguments can be passed:

       client_id = $id_int
           Required. The client ID corresponding to the API key.

       api_key => $api_key_string
           Optional.  The  API  key used to sign requests and verify responses. 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  enabled  (enabled  by  default)  requests will be signed, as long as api_key is also
           provided.

       timeout => $seconds
           Optional. Timeout parameter sent to the server, see the protocol details for more information.

       sl => $level
           Optional. Security level parameter sent to the server, see the protocol details for more information.

       timestamp => $enable
           Optional. When enabled, sends the timestamp parameter to the  server,  causing  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.

perl v5.26.2                                       2018-05-21                              AnyEvent::Yubico(3pm)