.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Authen::Bitcard 3pm"
.TH Authen::Bitcard 3pm "2021-01-09" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Authen::Bitcard \- Bitcard authentication verification
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 8
\&    use CGI;
\&    use Authen::Bitcard;
\&    my $q = CGI\->new;
\&    my $bc = Authen::Bitcard\->new;
\&    $bc\->token(\*(Aqbitcard\-token\*(Aq);
\&    # 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;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIAuthen::Bitcard\fR is an implementation of verification for signatures
generated by Bitcard authentication. For information on the Bitcard
protocol and using Bitcard in other applications, see
\&\fIhttp://www.bitcard.org/api\fR.
.PP
The module and the protocol are heavily based on \fIAuthen::Typekey\fR.
(In fact, the Bitcard authentication server also supports the TypeKey
\&\s-1API\s0!)
.SH "USAGE"
.IX Header "USAGE"
.SS "Authen::Bitcard\->new"
.IX Subsection "Authen::Bitcard->new"
Create a new \fIAuthen::Bitcard\fR object.
.ie n .SS "$bc\->token([ $bitcard_token ])"
.el .SS "\f(CW$bc\fP\->token([ \f(CW$bitcard_token\fP ])"
.IX Subsection "$bc->token([ $bitcard_token ])"
Your Bitcard token, which you passed to Bitcard when creating the original
sign-in link.
.PP
This must be set \fBbefore\fR calling \fIverify\fR or \fIlogin_url\fR (etc).
.ie n .SS "$bc\->bitcard_url( [ $url ])"
.el .SS "\f(CW$bc\fP\->bitcard_url( [ \f(CW$url\fP ])"
.IX Subsection "$bc->bitcard_url( [ $url ])"
Get/set the base \s-1URL\s0 for the Bitcard service.  The default \s-1URL\s0 is
\&\fIhttps://www.bitcard.org/\fR.  The other *_url methods are build based
on the \f(CW\*(C`bitcard_url\*(C'\fR value.
.ie n .SS "$bc\->login_url( r => $return_url )"
.el .SS "\f(CW$bc\fP\->login_url( r => \f(CW$return_url\fP )"
.IX Subsection "$bc->login_url( r => $return_url )"
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 \f(CW\*(C`r\*(C'\fR
parameter with the \s-1URL\s0 the user will get returned to after logging in
(or canceling the login).
.ie n .SS "$bc\->logout_url( r => $return_url )"
.el .SS "\f(CW$bc\fP\->logout_url( r => \f(CW$return_url\fP )"
.IX Subsection "$bc->logout_url( r => $return_url )"
Returns the \s-1URL\s0 you can send the user if they wish to logout.  Also
needs the \f(CW\*(C`r\*(C'\fR parameter for the \s-1URL\s0 the Bitcard server should send
the user back to after logging out.
.ie n .SS "$bc\->account_url( r => $return_url )"
.el .SS "\f(CW$bc\fP\->account_url( r => \f(CW$return_url\fP )"
.IX Subsection "$bc->account_url( r => $return_url )"
Returns the \s-1URL\s0 the user can edit his Bitcard account information at.
Also needs the \f(CW\*(C`r\*(C'\fR parameter like \f(CW\*(C`login_url\*(C'\fR and \f(CW\*(C`logout_url\*(C'\fR.
.ie n .SS "$bc\->register_url( r => $return_url )"
.el .SS "\f(CW$bc\fP\->register_url( r => \f(CW$return_url\fP )"
.IX Subsection "$bc->register_url( r => $return_url )"
Returns the \s-1URL\s0 for a user to register a new Bitcard account.  Also
needs the \f(CW\*(C`r\*(C'\fR parameter as above.
.ie n .SS "$bc\->\fBkey_url()\fP"
.el .SS "\f(CW$bc\fP\->\fBkey_url()\fP"
.IX Subsection "$bc->key_url()"
Get the \s-1URL\s0 from which the Bitcard public key can be obtained.
.ie n .SS "$bc\->info_required(  $string | [ array ref ] )"
.el .SS "\f(CW$bc\fP\->info_required(  \f(CW$string\fP | [ array ref ] )"
.IX Subsection "$bc->info_required( $string | [ array ref ] )"
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 \f(CW\*(C`verify\*(C'\fR for
more information).
.PP
The method takes either a comma separated string or a reference to an
array.
.PP
This must be called before \f(CW\*(C`login_url\*(C'\fR.
.PP
\&\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.
.ie n .SS "$bc\->info_optional( $string | [ array ref ] )"
.el .SS "\f(CW$bc\fP\->info_optional( \f(CW$string\fP | [ array ref ] )"
.IX Subsection "$bc->info_optional( $string | [ array ref ] )"
As \f(CW\*(C`info_required\*(C'\fR except the Bitcard server will ask the user to
allow the information to be forwarded, but not require it to proceed.
.PP
The Bitcard server will always have a confirmed email address on file
before letting a user login.
.ie n .SS "$bc\->verify($query)"
.el .SS "\f(CW$bc\fP\->verify($query)"
.IX Subsection "$bc->verify($query)"
Verify a Bitcard signature based on the other parameters given. The signature
and other parameters are found in the \fI\f(CI$query\fI\fR object, which should be
either a hash reference, or any object that supports a \fIparam\fR method\*(--for
example, a \fI\s-1CGI\s0\fR or \fIApache::Request\fR object.
.PP
If the signature is successfully verified, \fIverify\fR returns a reference to
a hash containing the following values.
.IP "\(bu" 4
id
.Sp
The unique user id of the Bitcard user on your site.  It's a 128bit
number as a 40 byte hex value.
.Sp
The id is always returned when the verification was successful (all
other user data fields are optional, see \f(CW\*(C`info_required\*(C'\fR and
\&\f(CW\*(C`info_optional\*(C'\fR).
.IP "\(bu" 4
username
.Sp
The unique username of the Bitcard user.
.IP "\(bu" 4
name
.Sp
The user's display name.
.IP "\(bu" 4
email
.Sp
The user's email address.
.IP "\(bu" 4
ts
.Sp
The timestamp at which the signature was generated, expressed as seconds
since the epoch.
.PP
If verification is unsuccessful, \fIverify\fR will return \f(CW\*(C`undef\*(C'\fR, and the
error message can be found in \f(CW\*(C`$bc\->errstr\*(C'\fR.
.ie n .SS "$bc\->key_cache([ $cache ])"
.el .SS "\f(CW$bc\fP\->key_cache([ \f(CW$cache\fP ])"
.IX Subsection "$bc->key_cache([ $cache ])"
Provide a caching mechanism for the public key.
.PP
If \fI\f(CI$cache\fI\fR 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
\&\fIAuthen::TypeKey\fR object, and the \s-1URI\s0 of the key. It should return a
hash reference with the \fIp\fR, \fIg\fR, \fIq\fR, and \fIpub_key\fR keys set to
\&\fIMath::BigInt\fR objects representing the pieces of the \s-1DSA\s0 public key.
.PP
Otherwise, \fI\f(CI$cache\fI\fR should be the path to a local file where the public
key will be cached/mirrored.
.PP
If \fI\f(CI$cache\fI\fR is not set, the key is not cached. By default, no caching
occurs.
.ie n .SS "$bc\->skip_expiry_check([ $boolean ])"
.el .SS "\f(CW$bc\fP\->skip_expiry_check([ \f(CW$boolean\fP ])"
.IX Subsection "$bc->skip_expiry_check([ $boolean ])"
Get/set a value indicating whether \fIverify\fR should check the expiration
date and time in the TypeKey parameters. The default is to check the
expiration date and time.
.ie n .SS "$bc\->expires([ $secs ])"
.el .SS "\f(CW$bc\fP\->expires([ \f(CW$secs\fP ])"
.IX Subsection "$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.
.ie n .SS "$bc\->ua([ $user_agent ])"
.el .SS "\f(CW$bc\fP\->ua([ \f(CW$user_agent\fP ])"
.IX Subsection "$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 \fImirror\fR and \fIget\fR methods. 
By default, LWP::UserAgent is used, and this method as a getter returns
\&\f(CW\*(C`undef\*(C'\fR unless the user agent has been previously set.
.ie n .SS "$bc\->version([ $version ])"
.el .SS "\f(CW$bc\fP\->version([ \f(CW$version\fP ])"
.IX Subsection "$bc->version([ $version ])"
Get/set the version of the Bitcard protocol to use. The default version
is \f(CW3\fR.
.ie n .SS "$bc\->api_secret( $secret )"
.el .SS "\f(CW$bc\fP\->api_secret( \f(CW$secret\fP )"
.IX Subsection "$bc->api_secret( $secret )"
Get/set the api_secret (needed for some \s-1API\s0 calls, add_invite for
example).
.ie n .SS "$bc\->add_invite"
.el .SS "\f(CW$bc\fP\->add_invite"
.IX Subsection "$bc->add_invite"
Returns a hashref with \f(CW\*(C`invite_url\*(C'\fR and \f(CW\*(C`invite_key\*(C'\fR.  Can be used
for \*(L"invitation only\*(R" sites where you have to login before you can
access the site.
.SH "LICENSE"
.IX Header "LICENSE"
\&\fIAuthen::Bitcard\fR is distributed under the Apache License; see the
\&\s-1LICENSE\s0 file in the distribution for details.
.SH "AUTHOR & COPYRIGHT"
.IX Header "AUTHOR & COPYRIGHT"
Except where otherwise noted, \fIAuthen::Bitcard\fR is Copyright
2004\-2010 Develooper \s-1LLC,\s0 ask@develooper.com.
.PP
Parts are Copyright 2004 Six Apart Ltd, cpan@sixapart.com.
.PP
All rights reserved.