Authen::ModAuthPubTkt - Generate Tickets (Signed HTTP Cookies) for mod_auth_pubtkt protected websites.
version 0.1.1
On the command-line, generate the public + private keys: (More details available at https://neon1.net/mod_auth_pubtkt/install.html)
$ openssl genrsa -out key.priv.pem 1024 $ openssl rsa -in key.priv.pem -out key.pub.pem -pubout
Then in your perl script (which is probably the your custom login website), use the following code to issue tickets:
use Authen::ModAuthPubTkt; my $ticket = pubtkt_generate( privatekey => "key.priv.pem", keytype => "rsa", clientip => undef, # or a valid IP address userid => "102", # or any ID that makes sense to your application, e.g. email validuntil => time() + 86400, # valid for one day graceperiod=> 3600, # grace period of an hour tokens => undef, # comma separated string of tokens. userdata => undef # any application specific data to pass. ); ## $ticket string will look something like: ## "uid=102;validuntil=1337899939;graceperiod=1337896339;tokens=;udata=;sig=h5qR" \ ## "yZZDl8PfW8wNxPYkcOMlAxtWuEyU5bNAwEFT9lztN3I7V13SaGOHl+U6wB+aMkvvLQiaAfD2xF/Hl" \ ## "+QmLDEvpywp98+5nRS+GeihXTvEMRaA4YVyxb4NnZujCZgX8IBhP6XBlw3s7180jxE9I8DoDV8bDV" \ ## "k/2em7yMEzLns="
To verify a ticket, use the following code:
my $ok = pubtkt_verify ( publickey => "key.pub.pem", keytype => "rsa", ticket => $ticket ); die "Ticket verification failed.\n" if not $ok;
To extract items from a ticket, use the following code:
my %items = pubtkt_parse($ticket); ## %items will be something like: ## { ## 'uid' => 102, ## 'validuntil' => 1337899939, ## 'graceperiod => 1337896339, ## 'tokens' => "", ## 'udata' => "", ## 'sig' => 'h5qRyZZDl8PfW8wNxPYkcOMlAxtWuEyU5bNAwEFT9lztN3 (....)' ## }
Also, a command-line utility (mod_auth_pubtkt.pl) will be installed, and can be used to generate/verify keys:
mod_auth_pubtkt.pl
$ mod_auth_pubtkt.pl --generate --private-key key.priv.pem --rsa $ mod_auth_pubtkt.pl --verify --public-key key.pub.pem --rsa $ mod_autH_pubtkt.pl --help
This module generates and verify a mod_auth_pubtkt-compatible ticket string, which should be used as a cookie with the rest of the mod_auth_pubtkt ( https://neon1.net/mod_auth_pubtkt/ ) system.
pubtkt_generate
A working (but minimal) perl login example is available at https://github.com/manuelkasper/mod_auth_pubtkt/blob/master/perl-login/minimal_cgi/login.pl
Generates a signed ticket.
If successful, returns a signed ticket string (to be sent back to the user as a cookie).
On any failure (bad key, failure to run openssl, etc.) returns undef.
openssl
undef
Accepts a hash of parameters:
String containing the private key filename (full path). The key can be either DSA or RSA key (see keytype).
either "rsa" or "dsa" - depending on how you created the private/public key files.
String containing the user ID. No specific format is enforced: can by a number, a string, an email address, etc. It will be encoded as "uid=XXXX" in the signed ticket.
Numeric value, containing the validity period, in seconds since epoch (use time() function).
time()
Optional. Numeric value. If given, will be added to the signed ticket string.
Optional. A string with an IP address. If given. will be added to the signed ticket string.
Optional. Any textual string. If given. will be added to the signed ticket string.
Verifies a signed ticket string.
If successful (i.e. the ticket's signature is valid), returns TRUE (=1).
NOTE: This function checks ONLY THE SIGNATURE, based on the public key file. It is the caller's resposibility to check the expiration date. That is: The function will return TRUE if the ticket is properly signed, but possibly expired.
String containing the public key filename (full path). The key can be either DSA or RSA key (see keytype).
The string of the ticket (such as returned by pubtkt_generate).
Utility function to parse a ticket string into a Perl hash.
NOTE: No validation is performed. The given ticket might be expired, or even forged.
openssl must be installed (and available on the $PATH).
IPC::Run3 is required to run the openssl executables.
Probably many.
Use Perl's Crypt::OpenSSL::RSA and Crypt::OpenSSL::DSA instead of the running openssl executable.
Don't assume openssl binary is on the $PATH.
Refactor into OO interface.
Copyright (C) 2012 A. Gordon ( gordon at cshl dot edu ).
Apache License, same as the rest of mod_auth_pubtkt
A. Gordon, heavily based on the PHP code from mod_auth_pubtkt.
ModAuthPubTkt main website: https://neon1.net/mod_auth_pubtkt/
ModAuthPubTkt github repository: https://github.com/manuelkasper/mod_auth_pubtkt
This module's github repository: https://github.com/agordon/Authen-ModAuthPubTkt
Examples in the ./eg directory:
./eg
Generates a pair of RSA key files.
Generates a pair of DSA key files.
A command-line utility to generate/verify tickets.
To install Authen::ModAuthPubTkt, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Authen::ModAuthPubTkt
CPAN shell
perl -MCPAN -e shell install Authen::ModAuthPubTkt
For more information on module installation, please visit the detailed CPAN module installation guide.