--- name: "Authen::Bitcard" section: "3pm" platform: "linux" package: "libauthen-bitcard-perl" version: "0.90-2.1" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/Authen::Bitcard" --- # Authen::Bitcard(3pm) Bitcard authentication verification ## 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.