Authen::Bitcard(3pm)

🌸 Authen::Bitcard — the vibe

okay bestie, welcome to Authen::Bitcard, a User Contributed Perl Documentation page 💖 This is the whole thing about verifying Bitcard authentication signatures, and honestly it's giving ✨login but make it cryptographically correct✨. Let's get into it.

---

✨ 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 🦋

So Authen::Bitcard is an implementation of verification for signatures generated by Bitcard authentication. That's the whole main character job 💅

Want the tea on the Bitcard protocol and how to use Bitcard in other applications? Go look at http://www.bitcard.org/api — that's the spot.

The module and the protocol are heavily based on Authen::Typekey. And no cap — the Bitcard authentication server also supports the TypeKey API! 🔥

---

👑 USAGE 👑

💜 Authen::Bitcard->new

Create a new Authen::Bitcard object. New object, who dis ✨

💜 $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). No token, no entry, periodt.

💜 $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 built based on the "bitcard_url" value, so change this one and everything downstream follows along 🫶

💜 $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). So like, the comeback link, bestie 🌈

💜 $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. Bye bye, see you never (jk) 👋

💜 $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". Glow-up zone 🎀

💜 $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. Fresh account energy ✨

💜 $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. Polite ask, not a demand 💅

The Bitcard server will always have a confirmed email address on file before letting a user login. Fr fr, always.

💜 $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. Very flexible of you, honestly iconic 😌

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". Sad girl hours 😭 but at least the error tells you why.

💜 $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. Zero caching, zero drama 🙈

💜 $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. Safety first, bestie 🛡️

💜 $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. Ten minutes, that's the window ⏳

💜 $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. Surprise — it's undef until you set it 💀

💜 $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). Secret stays secret 🤫

💜 $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. Exclusive club vibes 👑

---

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

---

and that's the whole page, bestie 🫶 this one's from the perl v5.32.0 era, dated 2021-01-09 — vintage but still slaying 💅✨ no cap, go verify some signatures 🌸🦋