Authen::ModAuthPubTkt(3pm)

1Authen::ModAuthPubTkt(3U)ser Contributed Perl DocumentatiAounthen::ModAuthPubTkt(3)
2
3
4

NAME

6       Authen::ModAuthPubTkt - Generate Tickets (Signed HTTP Cookies) for
7       mod_auth_pubtkt protected websites.
8

VERSION

10       version 0.1.1
11

SYNOPSIS

13       On the command-line, generate the public + private keys: (More details
14       available at <https://neon1.net/mod_auth_pubtkt/install.html>)
15
16               $ openssl genrsa -out key.priv.pem 1024
17               $ openssl rsa -in key.priv.pem -out key.pub.pem -pubout
18
19       Then in your perl script (which is probably the your custom login
20       website), use the following code to issue tickets:
21
22               use Authen::ModAuthPubTkt;
23
24               my $ticket = pubtkt_generate(
25                       privatekey => "key.priv.pem",
26                       keytype    => "rsa",
27                       clientip   => undef,  # or a valid IP address
28                       userid     => "102",  # or any ID that makes sense to your application, e.g. email
29                       validuntil => time() + 86400, # valid for one day
30                       graceperiod=> 3600,   # grace period of an hour
31                       tokens     => undef,  # comma separated string of tokens.
32                       userdata   => undef   # any application specific data to pass.
33               );
34
35               ## $ticket string will look something like:
36               ## "uid=102;validuntil=1337899939;graceperiod=1337896339;tokens=;udata=;sig=h5qR" \
37               ## "yZZDl8PfW8wNxPYkcOMlAxtWuEyU5bNAwEFT9lztN3I7V13SaGOHl+U6wB+aMkvvLQiaAfD2xF/Hl" \
38               ## "+QmLDEvpywp98+5nRS+GeihXTvEMRaA4YVyxb4NnZujCZgX8IBhP6XBlw3s7180jxE9I8DoDV8bDV" \
39               ## "k/2em7yMEzLns="
40
41       To verify a ticket, use the following code:
42
43               my $ok = pubtkt_verify (
44                       publickey => "key.pub.pem",
45                       keytype   => "rsa",
46                       ticket    => $ticket
47               );
48               die "Ticket verification failed.\n" if not $ok;
49
50       To extract items from a ticket, use the following code:
51
52               my %items = pubtkt_parse($ticket);
53
54               ## %items will be something like:
55               ## {
56               ##    'uid' => 102,
57               ##    'validuntil' => 1337899939,
58               ##    'graceperiod => 1337896339,
59               ##    'tokens' => "",
60               ##    'udata'  => "",
61               ##    'sig'    => 'h5qRyZZDl8PfW8wNxPYkcOMlAxtWuEyU5bNAwEFT9lztN3 (....)'
62               ## }
63
64       Also, a command-line utility ("mod_auth_pubtkt.pl") will be installed,
65       and can be used to generate/verify keys:
66
67               $ mod_auth_pubtkt.pl --generate --private-key key.priv.pem --rsa
68               $ mod_auth_pubtkt.pl --verify --public-key key.pub.pem --rsa
69               $ mod_autH_pubtkt.pl --help
70

DESCRIPTION

72       This module generates and verify a mod_auth_pubtkt-compatible ticket
73       string, which should be used as a cookie with the rest of the
74       mod_auth_pubtkt ( <https://neon1.net/mod_auth_pubtkt/> ) system.
75
76       Common scenario:
77
78       1. On the login server side, write perl code to authenticate users
79       (using Apache's authenetication, LDAP, DB, etc.).
80       2. Once the user is authenticated, call "pubtkt_generate" to generate a
81       ticket, and send it back to the user as a cookie.
82       3. Redirect the user back to the server he/she came from.
83

Working Example

85       A working (but minimal) perl login example is available at
86       <https://github.com/manuelkasper/mod_auth_pubtkt/blob/master/perl-login/minimal_cgi/login.pl>
87

METHODS

89   pubtkt_generate
90       Generates a signed ticket.
91
92       If successful, returns a signed ticket string (to be sent back to the
93       user as a cookie).
94
95       On any failure (bad key, failure to run "openssl", etc.) returns
96       "undef".
97
98       Accepts a hash of parameters:
99
100       privatekey
101           String containing the private key filename (full path). The key can
102           be either DSA or RSA key (see keytype).
103
104       keytype
105           either "rsa" or "dsa" - depending on how you created the
106           private/public key files.
107
108       userid
109           String containing the user ID. No specific format is enforced: can
110           by a number, a string, an email address, etc. It will be encoded as
111           "uid=XXXX" in the signed ticket.
112
113       validuntil
114           Numeric value, containing the validity period, in seconds since
115           epoch (use "time()" function).
116
117       graceperiod
118           Optional. Numeric value. If given, will be added to the signed
119           ticket string.
120
121       clientip
122           Optional. A string with an IP address. If given. will be added to
123           the signed ticket string.
124
125       token
126           Optional. Any textual string. If given. will be added to the signed
127           ticket string.
128
129       userdata
130           Optional. Any textual string. If given. will be added to the signed
131           ticket string.
132
133   pubtkt_verify
134       Verifies a signed ticket string.
135
136       If successful (i.e. the ticket's signature is valid), returns TRUE
137       (=1).
138
139       On any failure (bad key, failure to run "openssl", etc.) returns
140       "undef".
141
142       NOTE: This function checks ONLY THE SIGNATURE, based on the public key
143       file. It is the caller's resposibility to check the expiration date.
144       That is: The function will return TRUE if the ticket is properly
145       signed, but possibly expired.
146
147       Accepts a hash of parameters:
148
149       publickey
150           String containing the public key filename (full path). The key can
151           be either DSA or RSA key (see keytype).
152
153       keytype
154           either "rsa" or "dsa" - depending on how you created the
155           private/public key files.
156
157       ticket
158           The string of the ticket (such as returned by "pubtkt_generate").
159
160   pubtkt_parse($ticket)
161       Utility function to parse a ticket string into a Perl hash.
162
163       NOTE: No validation is performed. The given ticket might be expired, or
164       even forged.
165

PREREQUISITES

167       openssl must be installed (and available on the $PATH).
168
169       IPC::Run3 is required to run the openssl executables.
170

BUGS

172       Probably many.
173

TODO

175       Use Perl's Crypt::OpenSSL::RSA and Crypt::OpenSSL::DSA instead of the
176       running "openssl" executable.
177
178       Don't assume "openssl" binary is on the $PATH.
179
180       Refactor into OO interface.
181

LICENSE

183       Copyright (C) 2012,2022 A. Gordon ( assafgordon at gmail dot com ).
184       All rights reserved. This module is free software; you can redistribute
185       it and/or modify it under the same terms as Perl itself.
186

AUTHORS

188       A. Gordon, heavily based on the PHP code from mod_auth_pubtkt.
189