NAME

Authen::TypeKey - TypeKey authentication verification

SYNOPSIS

    use CGI;
    use Authen::TypeKey;
    my $q = CGI->new;
    my $tk = Authen::TypeKey->new;
    $tk->token('typekey-token');
    my $res = $tk->verify($q) or die $tk->errstr;

DESCRIPTION

Authen::TypeKey is an implementation of verification for signatures generated by TypeKey authentication. For information on the TypeKey protocol and using TypeKey in other applications, see http://www.sixapart.com/typekey/api.

USAGE

Authen::TypeKey->new

Create a new Authen::TypeKey object.

$tk->token([ $typekey_token ])

Your TypeKey token, which you passed to TypeKey when creating the original sign-in link. This is required to successfully validate the signature in TypeKey 1.1 and higher, which includes the token in the plaintext.

This must be set before calling verify.

$tk->verify($query)

Verify a TypeKey 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.

name
The unique username of the TypeKey user.
nick
The user's display name.
email
The user's email address. If the user has chosen not to pass his/her email address, this will contain the SHA-1 hash of the string "mailto:<email>".
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 "$tk->errstr".

$tk->key_cache([ $cache ])

Provide a caching mechanism for the TypeKey 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.

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

$tk->expires([ $secs ])

Get/set the amount of time at which a TypeKey signature is intended to expire. The default value is 600 seconds, i.e. 10 minutes.

$tk->key_url([ $url ])

Get/set the URL from which the TypeKey public key can be obtained. The default URL is http://www.typekey.com/extras/regkeys.txt.

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

$tk->version([ $version ])

Get/set the version of the TypeKey protocol to use. The default version is 1.1.

LICENSE

Authen::TypeKey is free software; you may redistribute it and/or modify it under the same terms as Perl itself.