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->key_url() Get the URL from which the Bitcard public key can be obtained. $bc->info_required( $string | [ array ref ] ) $bc->info_optional( $string | [ array ref ] ) $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. * 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. LICENSE *Authen::Bitcard* is free software; you may redistribute it and/or modify it under the same terms as Perl itself. AUTHOR & COPYRIGHT Except where otherwise noted, *Authen::Bitcard* is Copyright 2004-2005 Develooper LLC, ask@develooper.com. Parts are Copyright 2004 Six Apart Ltd, cpan@sixapart.com. All rights reserved.