Authen::Bitcard (3pm)

    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;

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 \s-1API\s0!)

Authen::Bitcard->new

Create a new Authen::Bitcard object. 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). Get/set the base \s-1URL\s0 for the Bitcard service. The default \s-1URL\s0 is https://www.bitcard.org/. The other *_url methods are build based on the \*(C`bitcard_url\*(C' value. Returns the \s-1URL\s0 for the user to login. Takes a hash or hash ref with extra parameters to put in the \s-1URL\s0. One of them must be the \*(C`r\*(C' parameter with the \s-1URL\s0 the user will get returned to after logging in (or canceling the login). Returns the \s-1URL\s0 you can send the user if they wish to logout. Also needs the \*(C`r\*(C' parameter for the \s-1URL\s0 the Bitcard server should send the user back to after logging out. Returns the \s-1URL\s0 the user can edit his Bitcard account information at. Also needs the \*(C`r\*(C' parameter like \*(C`login_url\*(C' and \*(C`logout_url\*(C'. Returns the \s-1URL\s0 for a user to register a new Bitcard account. Also needs the \*(C`r\*(C' parameter as above. Get the \s-1URL\s0 from which the Bitcard public key can be obtained. With info_required you specify what user data you require. The possible fields are \*(L"username\*(R", \*(L"name\*(R" and \*(L"email\*(R" (see \*(C`verify\*(C' for more information).

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

This must be called before \*(C`login_url\*(C'.

\s-1NOTE:\s0 \*(L"name\*(R" is currently not implemented well in the Bitcard server, so we recommend you require \*(L"username\*(R", but mark \*(L"name\*(R" as optional if you want the \*(L"display name\*(R" of the user returned. As \*(C`info_required\*(C' 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. 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 \s-1CGI\s0 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 \*(C`info_required\*(C' and \*(C`info_optional\*(C').

• 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 \*(C`undef\*(C', and the error message can be found in \*(C`$bc->errstr\*(C'. Provide a caching mechanism for the public key.

If $cache is a \s-1CODE\s0 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 \s-1URI\s0 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 \s-1DSA\s0 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. 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. 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. 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 \*(C`undef\*(C' unless the user agent has been previously set. Get/set the version of the Bitcard protocol to use. The default version is 3. Get/set the api_secret (needed for some \s-1API\s0 calls, add_invite for example). Returns a hashref with \*(C`invite_url\*(C' and \*(C`invite_key\*(C'. Can be used for \*(L"invitation only\*(R" sites where you have to login before you can access the site.

Authen::Bitcard is distributed under the Apache License; see the \s-1LICENSE\s0 file in the distribution for details.

Except where otherwise noted, Authen::Bitcard is Copyright 2004-2010 Develooper \s-1LLC\s0, [email protected].

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

All rights reserved.