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, ask@develooper.com.

Parts are Copyright 2004 Six Apart Ltd, cpan@sixapart.com.

All rights reserved.

cpanm Authen::Bitcard

perl -MCPAN -e shell
install Authen::Bitcard