NAME
   Authen::Bitcard - Bitcard authentication verification

SYNOPSIS
       use CGI;
       use Authen::Bitcard;
       my $q = CGI->new;
       my $bc = Authen::Bitcard->new;
       $bc->token('bitcard-token');
       # send user to $bc->login_url(r => $return_url);
       # when the user comes back, get the user id with:
       my $user = $bc->verify($q) or die $bc->errstr;

DESCRIPTION
   *Authen::Bitcard* is an implementation of verification for signatures
   generated by Bitcard authentication. For information on the Bitcard
   protocol and using Bitcard in other applications, see
   *http://www.bitcard.org/api*.

   The module and the protocol are heavily based on *Authen::Typekey*. (In
   fact, the Bitcard authentication server also supports the TypeKey API!)

USAGE
 Authen::Bitcard->new
   Create a new *Authen::Bitcard* object.

 $bc->token([ $bitcard_token ])
   Your Bitcard token, which you passed to Bitcard when creating the
   original sign-in link.

   This must be set before calling *verify* or *login_url* (etc).

 $bc->bitcard_url( [ $url ])
   Get/set the base URL for the Bitcard service. The default URL is
   *https://www.bitcard.org/*. The other *_url methods are build based on
   the "bitcard_url" value.

 $bc->login_url( r => $return_url )
   Returns the URL for the user to login. Takes a hash or hash ref with
   extra parameters to put in the URL. One of them must be the "r"
   parameter with the URL the user will get returned to after logging in
   (or canceling the login).

 $bc->logout_url( r => $return_url )
   Returns the URL you can send the user if they wish to logout. Also needs
   the "r" parameter for the URL the Bitcard server should send the user
   back to after logging out.

 $bc->account_url( r => $return_url )
   Returns the URL the user can edit his Bitcard account information at.
   Also needs the "r" parameter like "login_url" and "logout_url".

 $bc->register_url( r => $return_url )
   Returns the URL for a user to register a new Bitcard account. Also needs
   the "r" parameter as above.

 $bc->key_url()
   Get the URL from which the Bitcard public key can be obtained.

 $bc->info_required(  $string | [ array ref ] )
   With info_required you specify what user data you require. The possible
   fields are "username", "name" and "email" (see "verify" for more
   information).

   The method takes either a comma separated string or a reference to an
   array.

   This must be called before "login_url".

   NOTE: "name" is currently not implemented well in the Bitcard server, so
   we recommend you require "username", but mark "name" as optional if you
   want the "display name" of the user returned.

 $bc->info_optional( $string | [ array ref ] )
   As "info_required" except the Bitcard server will ask the user to allow
   the information to be forwarded, but not require it to proceed.

   The Bitcard server will always have a confirmed email address on file
   before letting a user login.

 $bc->verify($query)
   Verify a Bitcard signature based on the other parameters given. The
   signature and other parameters are found in the *$query* object, which
   should be either a hash reference, or any object that supports a *param*
   method--for example, a *CGI* or *Apache::Request* object.

   If the signature is successfully verified, *verify* returns a reference
   to a hash containing the following values.

   *   id

       The unique user id of the Bitcard user on your site. It's a 128bit
       number as a 40 byte hex value.

       The id is always returned when the verification was successful (all
       other user data fields are optional, see "info_required" and
       "info_optional").

   *   username

       The unique username of the Bitcard user.

   *   name

       The user's display name.

   *   email

       The user's email address.

   *   ts

       The timestamp at which the signature was generated, expressed as
       seconds since the epoch.

   If verification is unsuccessful, *verify* will return "undef", and the
   error message can be found in "$bc->errstr".

 $bc->key_cache([ $cache ])
   Provide a caching mechanism for the public key.

   If *$cache* is a CODE reference, it is treated as a callback that should
   return the public key. The callback will be passed two arguments: the
   *Authen::TypeKey* object, and the URI of the key. It should return a
   hash reference with the *p*, *g*, *q*, and *pub_key* keys set to
   *Math::BigInt* objects representing the pieces of the DSA public key.

   Otherwise, *$cache* should be the path to a local file where the public
   key will be cached/mirrored.

   If *$cache* is not set, the key is not cached. By default, no caching
   occurs.

 $bc->skip_expiry_check([ $boolean ])
   Get/set a value indicating whether *verify* should check the expiration
   date and time in the TypeKey parameters. The default is to check the
   expiration date and time.

 $bc->expires([ $secs ])
   Get/set the amount of time at which a Bitcard signature is intended to
   expire. The default value is 600 seconds, i.e. 10 minutes.

 $bc->ua([ $user_agent ])
   Get/set the LWP::UserAgent-like object which will be used to retrieve
   the regkeys from the network. Needs to support *mirror* and *get*
   methods. By default, LWP::UserAgent is used, and this method as a getter
   returns "undef" unless the user agent has been previously set.

 $bc->version([ $version ])
   Get/set the version of the Bitcard protocol to use. The default version
   is 3.

 $bc->api_secret( $secret )
   Get/set the api_secret (needed for some API calls, add_invite for
   example).

 $bc->add_invite
   Returns a hashref with "invite_url" and "invite_key". Can be used for
   "invitation only" sites where you have to login before you can access
   the site.

LICENSE
   *Authen::Bitcard* is distributed under the Apache License; see the
   LICENSE file in the distribution for details.

AUTHOR & COPYRIGHT
   Except where otherwise noted, *Authen::Bitcard* is Copyright 2004-2010
   Develooper LLC, [email protected].

   Parts are Copyright 2004 Six Apart Ltd, [email protected].

   All rights reserved.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.