Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Authen::Bitcard(3)    User Contributed Perl Documentation   Authen::Bitcard(3)

       Authen::Bitcard - Bitcard authentication	verification

	   use CGI;
	   use Authen::Bitcard;
	   my $q = CGI->new;
	   my $bc = Authen::Bitcard->new;
	   # 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

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

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

       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

       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.

       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.

       o   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

       o   username

	   The unique username of the Bitcard user.

       o   name

	   The user's display name.

       o   email

	   The user's email address.

       o   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

   $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

       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.

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

       Except where otherwise noted, Authen::Bitcard is	Copyright 2004-2010
       Develooper LLC,

       Parts are Copyright 2004	Six Apart Ltd,

       All rights reserved.

perl v5.24.1			  2011-06-11		    Authen::Bitcard(3)


Want to link to this manual page? Use this URL:

home | help