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.

AUTHOR & COPYRIGHT

Except where otherwise noted, Authen::TypeKey is Copyright 2004 Six Apart Ltd, cpan@sixapart.com. All rights reserved.