]>
Dogcows Code - chaz/p5-CGI-Ex/blob - lib/CGI/Ex/Auth.pm
5 CGI::Ex::Auth - Handle logins nicely.
9 ###----------------------------------------------------------------###
10 # Copyright 2006 - Paul Seamons #
11 # Distributed under the Perl Artistic License without warranty #
12 ###----------------------------------------------------------------###
15 use vars
qw($VERSION);
17 use MIME
::Base64
qw(encode_base64 decode_base64);
18 use Digest
::MD5
qw(md5_hex);
23 ###----------------------------------------------------------------###
26 my $class = shift || __PACKAGE__
;
27 my $args = shift || {};
28 return bless {%$args}, $class;
33 $self = $self->new(@_) if ! ref $self;
35 ### shortcut that will print a js file as needed (such as the md5.js)
36 if ($self->script_name . $self->path_info eq $self->js_uri_path . "/CGI/Ex/md5.js") {
37 $self->cgix->print_js('CGI/Ex/md5.js');
38 eval { die "Printed Javascript" };
42 my $form = $self->form;
43 my $cookies = $self->cookies;
44 my $key_l = $self->key_logout;
45 my $key_c = $self->key_cookie;
46 my $has_cookies = scalar %$cookies;
49 if ($form->{$key_l}) {
50 $self->delete_cookie({key
=> $key_c});;
51 $self->location_bounce($self->logout_redirect);
52 eval { die "Logging out" };
57 foreach ([$form, $self->key_user, 1],
58 [$cookies, $key_c, 0],
60 my ($hash, $key, $is_form) = @$_;
61 next if ! defined $hash->{$key};
62 $had_form_info ++ if $is_form;
64 ### if it looks like a bare username (as in they didn't have javascript)- add in other items
67 && $hash->{$key} !~ m
|^[^/]+/|
68 && defined $hash->{ $self->key_pass }) {
69 $data = $self->verify_token({
71 user
=> delete $hash->{$key},
72 test_pass
=> delete $hash->{ $self->key_pass },
73 expires_min
=> delete($hash->{ $self->key_save }) ? -1 : delete($hash->{ $self->key_expires_min }) || $self->expires_min,
74 payload
=> delete $hash->{ $self->key_payload } || '',
80 $data = $self->verify_token({token
=> $hash->{$key}, from
=> ($is_form ? 'form' : 'cookie')}) || next;
81 delete $hash->{$key} if $is_form;
84 ### generate a fresh cookie if they submitted info on plaintext types
85 if ($self->use_plaintext || ($data->{'type'} && $data->{'type'} eq 'crypt')) {
88 val
=> $self->generate_token($data),
89 no_expires
=> ($data->{ $self->key_save } ? 0 : 1), # make it a session cookie unless they ask for saving
90 }) if $is_form; # only set the cookie if we found info in the form - the cookie will be a session cookie after that
92 ### always generate a cookie on types that have expiration
96 val
=> $self->generate_token($data),
103 ### bounce to redirect
104 if (my $redirect = $form->{ $self->key_redirect }) {
105 $self->location_bounce($redirect);
106 eval { die "Success login - bouncing to redirect" };
109 ### if they have cookies we are done
110 } elsif ($has_cookies || $self->no_cookie_verify) {
113 ### need to verify cookies are set-able
115 $form->{$self->key_verify} = $self->server_time;
116 my $query = $self->cgix->make_form($form);
117 my $url = $self->script_name . $self->path_info . ($query ? "?$query" : "");
119 $self->location_bounce($url);
120 eval { die "Success login - bouncing to test cookie" };
125 ### make sure the cookie is gone
126 $self->delete_cookie({key
=> $key_c}) if $cookies->{$key_c};
128 ### nothing found - see if they have cookies
129 if (my $value = delete $form->{$self->key_verify}) {
130 if (abs(time() - $value) < 15) {
131 $self->no_cookies_print;
136 ### oh - you're still here - well then - ask for login credentials
137 my $key_r = $self->key_redirect;
138 if (! $form->{$key_r}) {
139 my $query = $self->cgix->make_form($form);
140 $form->{$key_r} = $self->script_name . $self->path_info . ($query ? "?$query" : "");
143 $form->{'had_form_data'} = $had_form_info;
145 my $data = $self->last_auth_data;
146 eval { die defined($data) ? $data : "Requesting credentials" };
150 ###----------------------------------------------------------------###
152 sub script_name
{ shift-
>{'script_name'} || $ENV{'SCRIPT_NAME'} || die "Missing SCRIPT_NAME" }
154 sub path_info
{ shift-
>{'path_info'} || $ENV{'PATH_INFO'} || '' }
156 sub server_time
{ time }
160 $self->{'cgix'} = shift if $#_ != -1;
161 return $self->{'cgix'} ||= CGI
::Ex-
>new;
166 $self->{'form'} = shift if $#_ != -1;
167 return $self->{'form'} ||= $self->cgix->get_form;
172 $self->{'cookies'} = shift if $#_ != -1;
173 return $self->{'cookies'} ||= $self->cgix->get_cookies;
179 my $key = $args->{'key'};
180 $self->cgix->set_cookie({
186 delete $self->cookies->{$key};
192 my $key = $args->{'key'};
193 my $val = $args->{'val'};
194 $self->cgix->set_cookie({
197 ($args->{'no_expires'} ? () : (-expires
=> '+20y')), # let the expires time take care of things for types that self expire
200 $self->cookies->{$key} = $val;
203 sub location_bounce
{
206 return $self->cgix->location_bounce($url);
209 ###----------------------------------------------------------------###
211 sub key_logout
{ shift-
>{'key_logout'} ||= 'cea_logout' }
212 sub key_cookie
{ shift-
>{'key_cookie'} ||= 'cea_user' }
213 sub key_user
{ shift-
>{'key_user'} ||= 'cea_user' }
214 sub key_pass
{ shift-
>{'key_pass'} ||= 'cea_pass' }
215 sub key_time
{ shift-
>{'key_time'} ||= 'cea_time' }
216 sub key_save
{ shift-
>{'key_save'} ||= 'cea_save' }
217 sub key_expires_min
{ shift-
>{'key_expires_min'} ||= 'cea_expires_min' }
218 sub form_name
{ shift-
>{'form_name'} ||= 'cea_form' }
219 sub key_verify
{ shift-
>{'key_verify'} ||= 'cea_verify' }
220 sub key_redirect
{ shift-
>{'key_redirect'} ||= 'cea_redirect' }
221 sub key_payload
{ shift-
>{'key_payload'} ||= 'cea_payload' }
222 sub secure_hash_keys
{ shift-
>{'secure_hash_keys'} ||= [] }
223 sub no_cookie_verify
{ shift-
>{'no_cookie_verify'} ||= 0 }
224 sub use_crypt
{ shift-
>{'use_crypt'} ||= 0 }
225 sub use_blowfish
{ shift-
>{'use_blowfish'} ||= '' }
226 sub use_plaintext
{ my $s = shift; $s->use_crypt || ($s->{'use_plaintext'} ||= 0) }
227 sub use_base64
{ my $s = shift; $s->{'use_base64'} = 1 if ! defined $s->{'use_base64'}; $s->{'use_base64'} }
228 sub expires_min
{ my $s = shift; $s->{'expires_min'} = 6 * 60 if ! defined $s->{'expires_min'}; $s->{'expires_min'} }
230 sub logout_redirect
{
232 return $self->{'logout_redirect'} || $self->script_name ."?loggedout=1";
237 return $self->{'js_uri_path'} ||= $self->script_name ."/js";
240 ###----------------------------------------------------------------###
242 sub no_cookies_print
{
244 $self->cgix->print_content_type;
245 print qq{<div style="border: 2px solid black;background:red;color:white">You do not appear to have cookies enabled.</div>};
251 my $hash = $self->login_hash_common;
252 my $template = $self->login_template;
254 ### allow for a hooked override
255 if (my $meth = $self->{'login_print'}) {
256 $meth->($self, $template, $hash);
260 ### process the document
261 require CGI
::Ex
::Template
;
262 my $cet = CGI
::Ex
::Template-
>new($self->template_args);
264 $cet->process_simple($template, $hash, \
$out) || die $cet->error;
266 ### fill in form fields
267 require CGI
::Ex
::Fill
;
268 CGI
::Ex
::Fill
::fill
({text
=> \
$out, form
=> $hash});
271 $self->cgix->print_content_type;
279 return $self->{'template_args'} ||= {
280 INCLUDE_PATH
=> $self->template_include_path,
284 sub template_include_path
{ shift-
>{'template_include_path'} || '' }
286 sub login_hash_common
{
288 my $form = $self->form;
289 my $data = $self->last_auth_data;
290 $data = {} if ! defined $data;
294 error
=> ($form->{'had_form_data'}) ? "Login Failed" : "",
296 key_user
=> $self->key_user,
297 key_pass
=> $self->key_pass,
298 key_time
=> $self->key_time,
299 key_save
=> $self->key_save,
300 key_expires_min
=> $self->key_expires_min,
301 key_payload
=> $self->key_payload,
302 key_redirect
=> $self->key_redirect,
303 form_name
=> $self->form_name,
304 script_name
=> $self->script_name,
305 path_info
=> $self->path_info,
306 md5_js_path
=> $self->js_uri_path ."/CGI/Ex/md5.js",
307 use_plaintext
=> $self->use_plaintext,
308 $self->key_user => $data->{'user'} || '',
309 $self->key_pass => '', # don't allow for this to get filled into the form
310 $self->key_time => $self->server_time,
311 $self->key_payload => $self->generate_payload({%$data, login_form
=> 1}),
312 $self->key_expires_min => $self->expires_min,
317 ###----------------------------------------------------------------###
322 my $token = delete $args->{'token'} || die "Missing token";
323 my $data = $self->{'_last_auth_data'} = $self->new_auth_data({token
=> $token, %$args});
325 ### token already parsed
327 $data->add_data({%$token, armor
=> 'none'});
329 ### parse token for info
333 for my $armor ('none', 'base64', 'blowfish') { # try with and without base64 encoding
334 my $copy = ($armor eq 'none') ? $token
335 : ($armor eq 'base64') ? decode_base64
($token)
336 : ($key = $self->use_blowfish) ? decrypt_blowfish
($token, $key)
338 if ($copy =~ m
|^ ([^/]+) / (\d
+) / (-?\d+) / (.*) / ([a-fA-F0-9]{32}) (?: / (sh\
.\d
+\
.\d
+))? $|x
) {
345 secure_hash
=> $6 || '',
350 } elsif ($copy =~ m
|^ ([^/]+) / (.*) $|x
) {
361 $data->error('Invalid token');
367 ### verify the user and get the pass
369 if (! defined($data->{'user'})) {
370 $data->error('Missing user');
372 } elsif (! defined $data->{'test_pass'}) {
373 $data->error('Missing test_pass');
375 } elsif (! $self->verify_user($data->{'user'} = $self->cleanup_user($data->{'user'}))) {
376 $data->error('Invalid user');
378 } elsif (! defined($pass = eval { $self->get_pass_by_user($data->{'user'}) })) {
379 $data->add_data({details
=> $@});
380 $data->error('Could not get pass');
382 return $data if $data->error;
385 ### store - to allow generate_token to not need to relookup the pass
386 $data->add_data({real_pass
=> $pass});
389 ### looks like a secure_hash cram
390 if ($data->{'secure_hash'}) {
391 $data->add_data(type
=> 'secure_hash_cram');
392 my $array = eval {$self->secure_hash_keys };
394 $data->error('secure_hash_keys not found');
395 } elsif (! @$array) {
396 $data->error('secure_hash_keys empty');
397 } elsif ($data->{'secure_hash'} !~ /^sh\.(\d+)\.(\d+)$/ || $1 > $#$array) {
398 $data->error('Invalid secure hash');
402 my $real = $data->{'real_pass'} =~ /^[a-f0-9]{32}$/ ? lc($data->{'real_pass'}) : md5_hex
($data->{'real_pass'});
403 my $str = join("/", @{$data}{qw(user cram_time expires_min payload)});
404 my $sum = md5_hex
($str .'/'. $real .('/sh.'.$array->[$rand1].'.'.$rand2));
405 if ($data->{'expires_min'} > 0
406 && ($self->server_time - $data->{'cram_time'}) > $data->{'expires_min'} * 60) {
407 $data->error('Login expired');
408 } elsif (lc($data->{'test_pass'}) ne $sum) {
409 $data->error('Invalid login');
413 ### looks like a normal cram
414 } elsif ($data->{'cram_time'}) {
415 $data->add_data(type
=> 'cram');
416 my $real = $data->{'real_pass'} =~ /^[a-f0-9]{32}$/ ? lc($data->{'real_pass'}) : md5_hex
($data->{'real_pass'});
417 my $str = join("/", @{$data}{qw(user cram_time expires_min payload)});
418 my $sum = md5_hex
($str .'/'. $real);
419 if ($data->{'expires_min'} > 0
420 && ($self->server_time - $data->{'cram_time'}) > $data->{'expires_min'} * 60) {
421 $data->error('Login expired');
422 } elsif (lc($data->{'test_pass'}) ne $sum) {
423 $data->error('Invalid login');
427 } elsif ($data->{'real_pass'} =~ m
|^([./0-9A-Za-z]{2})([./0-9A-Za-z
]{11})$|
428 && crypt($data->{'test_pass'}, $1) eq $data->{'real_pass'}) {
429 $data->add_data(type
=> 'crypt', was_plaintext
=> 1);
431 ### failed plaintext crypt
432 } elsif ($self->use_crypt) {
433 $data->error('Invalid login');
434 $data->add_data(type
=> 'crypt', was_plaintext
=> ($data->{'test_pass'} =~ /^[a-f0-9]{32}$/ ? 0 : 1));
436 ### plaintext and md5
438 my $is_md5_t = $data->{'test_pass'} =~ /^[a-f0-9]{32}$/;
439 my $is_md5_r = $data->{'real_pass'} =~ /^[a-f0-9]{32}$/;
440 my $test = $is_md5_t ? lc($data->{'test_pass'}) : md5_hex
($data->{'test_pass'});
441 my $real = $is_md5_r ? lc($data->{'real_pass'}) : md5_hex
($data->{'real_pass'});
442 $data->add_data(type
=> ($is_md5_r ? 'md5' : 'plaintext'), was_plaintext
=> ($is_md5_t ? 0 : 1));
443 $data->error('Invalid login')
447 ### check the payload
448 if (! $data->error && ! $self->verify_payload($data->{'payload'})) {
449 $data->error('Invalid payload');
457 return CGI
::Ex
::Auth
::Data-
>new(@_);
460 sub last_auth_data
{ shift-
>{'_last_auth_data'} }
464 my $data = shift || $self->last_auth_data;
465 die "Can't generate a token off of a failed auth" if ! $data;
469 ### do kinds that require staying plaintext
470 if ( (defined($data->{'use_plaintext'}) ? $data->{'use_plaintext'} : $self->use_plaintext) # ->use_plaintext is true if ->use_crypt is
471 || (defined($data->{'use_crypt'}) && $data->{'use_crypt'})
472 || (defined($data->{'type'}) && $data->{'type'} eq 'crypt')) {
473 $token = $data->{'user'} .'/'. $data->{'real_pass'};
475 ### all other types go to cram - secure_hash_cram, cram, plaintext and md5
477 my $user = $data->{'user'} || die "Missing user";
478 my $real = defined($data->{'real_pass'}) ? ($data->{'real_pass'} =~ /^[a-f0-9]{32}$/ ? lc($data->{'real_pass'}) : md5_hex
($data->{'real_pass'}))
479 : die "Missing real_pass";
480 my $exp = defined($data->{'expires_min'}) ? $data->{'expires_min'} : $self->expires_min;
481 my $load = $self->generate_payload($data);
482 die "Payload can not contain a \"/\. Please escape it in generate_payload." if $load =~ m
|/|;
483 die "User can not contain a \"/\." if $user =~ m
|/|;
486 if (! $data->{'prefer_cram'}
487 && ($array = eval { $self->secure_hash_keys })
489 my $rand1 = int(rand @$array);
490 my $rand2 = int(rand 100000);
491 my $str = join("/", $user, $self->server_time, $exp, $load);
492 my $sum = md5_hex
($str .'/'. $real .('/sh.'.$array->[$rand1].'.'.$rand2));
493 $token = $str .'/'. $sum . '/sh.'.$rand1.'.'.$rand2;
495 my $str = join("/", $user, $self->server_time, $exp, $load);
496 my $sum = md5_hex
($str .'/'. $real);
497 $token = $str .'/'. $sum;
501 if (my $key = $data->{'use_blowfish'} || $self->use_blowfish) {
502 $token = encrypt_blowfish
($token, $key);
504 } elsif (defined($data->{'use_base64'}) ? $data->{'use_base64'} : $self->use_base64) {
505 $token = encode_base64
($token, '');
511 sub generate_payload
{
514 return defined($args->{'payload'}) ? $args->{'payload'} : '';
520 if (my $meth = $self->{'verify_user'}) {
521 return $meth->($self, $user);
529 if (my $meth = $self->{'cleanup_user'}) {
530 return $meth->($self, $user);
535 sub get_pass_by_user
{
538 if (my $meth = $self->{'get_pass_by_user'}) {
539 return $meth->($self, $user);
542 die "Please override get_pass_by_user";
548 if (my $meth = $self->{'verify_payload'}) {
549 return $meth->($self, $payload);
554 ###----------------------------------------------------------------###
556 sub encrypt_blowfish
{
557 my ($str, $key) = @_;
559 require Crypt
::Blowfish
;
560 my $cb = Crypt
::Blowfish-
>new($key);
562 $str .= (chr 0) x
(8 - length($str) % 8); # pad to multiples of 8
565 $enc .= unpack "H16", $cb->encrypt($1) while $str =~ /\G(.{8})/g; # 8 bytes at a time
570 sub decrypt_blowfish
{
571 my ($enc, $key) = @_;
573 require Crypt
::Blowfish
;
574 my $cb = Crypt
::Blowfish-
>new($key);
577 $str .= $cb->decrypt(pack "H16", $1) while $enc =~ /\G([A-Fa-f0-9]{16})/g;
583 ###----------------------------------------------------------------###
587 return $self->{'login_template'} if $self->{'login_template'};
590 . $self->login_header
592 . $self->login_script
593 . $self->login_footer;
598 return shift-
>{'login_header'} || q
{
599 [%~ TRY
; PROCESS
'login_header.tt' ; CATCH %]<!-- [% error
%] -->[% END ~%]
604 return shift-
>{'login_footer'} || q
{
605 [%~ TRY
; PROCESS
'login_footer.tt' ; CATCH %]<!-- [% error
%] -->[% END ~%]
610 return shift-
>{'login_form'} || q
{
611 <div
class="login_chunk">
612 <span
class="login_error">[% error
%]</span
>
613 <form
class="login_form" name
="[% form_name %]" method="post" action
="[% script_name %][% path_info %]">
614 <input type
="hidden" name
="[% key_redirect %]" value
="">
615 <input type
="hidden" name
="[% key_payload %]" value
="">
616 <input type
="hidden" name
="[% key_time %]" value
="">
617 <input type
="hidden" name
="[% key_expires_min %]" value
="">
618 <table
class="login_table">
619 <tr
class="login_username">
621 <td
><input name
="[% key_user %]" type
="text" size
="30" value
=""></td
>
623 <tr
class="login_password">
625 <td
><input name
="[% key_pass %]" type
="password" size
="30" value
=""></td
>
627 <tr
class="login_save">
629 <input type
="checkbox" name
="[% key_save %]" value
="1"> Save Password
?
632 <tr
class="login_submit">
633 <td colspan
="2" align
="right">
634 <input type
="submit" value
="Submit">
645 [%~ IF
! use_plaintext
%]
646 <script src
="[% md5_js_path %]"></script
>
648 if (document
.md5_hex
) document
.[% form_name
%].onsubmit
= function
() {
649 var f
= document
.[% form_name
%];
650 var u
= f
.[% key_user
%].value
;
651 var p
= f
.[% key_pass
%].value
;
652 var t
= f
.[% key_time
%].value
;
653 var s
= f
.[% key_save
%] && f
.[% key_save
%].checked
? -1 : f
.[% key_expires_min
%].value
;
654 var l
= f
.[% key_payload
%].value
;
655 var r
= f
.[% key_redirect
%].value
;
657 var str
= u
+'/'+t
+'/'+s
+'/'+l
;
658 var sum
= document
.md5_hex
(str
+'/' + document
.md5_hex
(p
));
659 var loc
= f
.action
+ '?[% key_user %]='+escape
(str
+'/'+ sum
)+'&[% key_redirect %]='+escape
(r
);
669 ###----------------------------------------------------------------###
671 package CGI
::Ex
::Auth
::Data
;
675 'bool' => sub { ! shift-
>error },
677 '""' => sub { shift-
>as_string },
681 my ($class, $args) = @_;
682 return bless {%{ $args || {} }}, $class;
687 my $args = @_ == 1 ? shift : {@_};
688 @{ $self }{keys %$args} = values %$args;
694 $self->{'error'} = shift;
695 $self->{'error_caller'} = [caller];
697 return $self->{'error'};
702 return $self->error || ($self->{'user'} && $self->{'type'}) ? "Valid auth data" : "Unverified auth data";
705 ###----------------------------------------------------------------###
713 ### authorize the user
714 my $auth = $self->get_valid_auth({
715 get_pass_by_user => \&get_pass_by_user,
719 sub get_pass_by_user {
722 my $pass = some_way_of_getting_password($user);
728 CGI::Ex::Auth allows for auto-expiring, safe and easy web based logins. Auth uses
729 javascript modules that perform MD5 hashing to cram the password on
730 the client side before passing them through the internet.
732 For the stored cookie you can choose to use cram mechanisms,
733 secure hash cram tokens, auto expiring logins (not cookie based),
734 and Crypt::Blowfish protection. You can also choose to keep
735 passwords plaintext and to use perl's crypt for testing
738 A downside to this module is that it does not use a session to
739 preserve state so get_pass_by_user has to happen on every request (any
740 authenticated area has to verify authentication each time). A plus is
741 that you don't need to use a session if you don't want to. It is up
742 to the interested reader to add caching to the get_pass_by_user
751 Constructor. Takes a hashref of properties as arguments.
753 Many of the methods which may be overridden in a subclass,
754 or may be passed as properties to the new constuctor such as in the following:
757 get_pass_by_user => \&my_pass_sub,
758 key_user => 'my_user',
759 key_pass => 'my_pass',
760 login_template => \"<form><input name=my_user ... </form>",
763 The following methods will look for properties of the same name. Each of these will be
794 template_include_path
802 =item C<generate_token>
804 Takes either an auth_data object from a auth_data returned by verify_token,
805 or a hashref of arguments.
807 Possible arguments are:
809 user - the username we are generating the token for
810 real_pass - the password of the user (if use_plaintext is false
811 and use_crypt is false, the password can be an md5sum
812 of the user's password)
813 use_blowfish - indicates that we should use Crypt::Blowfish to protect
814 the generated token. The value of this argument is used
815 as the key. Default is false.
816 use_base64 - indicates that we should use Base64 encoding to protect
817 the generated token. Default is true. Will not be
818 used if use_blowfish is true.
819 use_plaintext - indicates that we should keep the password in plaintext
820 use_crypt - also indicates that we should keep the password in plaintext
821 expires_min - says how many minutes until the generated token expires.
822 Values <= 0 indicate to not ever expire. Used only on cram
824 payload - a payload that will be passed to generate_payload and then
825 will be added to cram type tokens. It cannot contain a /.
826 prefer_cram - If the secure_hash_keys method returns keys, and it is a non-plaintext
827 token, generate_token will create a secure_hash_cram. Set
828 this value to true to tell it to use a normal cram. This
829 is generally only useful in testing.
831 The following are types of tokens that can be generated by generate_token. Each type includes
832 pseudocode and a sample of a generated that token.
836 real_pass := "123qwe"
837 token := join("/", user, real_pass);
840 token == "paul/123qwe"
843 token == "cGF1bC8xMjNxd2U="
845 use_blowfish := "foobarbaz"
846 token == "6da702975190f0fe98a746f0d6514683"
848 Notes: This token will be used if either use_plaintext or use_crypt is set.
849 The real_pass can also be the md5_sum of the password. If real_pass is an md5_sum
850 of the password but the get_pass_by_user hook returns the crypt'ed password, the
851 token will not be able to be verified.
855 real_pass := "123qwe"
856 server_time := 1148512991 # a time in seconds since epoch
857 expires_min := 6 * 60
858 payload := "something"
860 md5_pass := md5_sum(real_pass) # if it isn't already a 32 digit md5 sum
861 str := join("/", user, server_time, expires_min, payload, md5_pass)
862 md5_str := md5(sum_str)
863 token := join("/", user, server_time, expires_min, payload, md5_str)
866 token == "paul/1148512991/360/something/16d0ba369a4c9781b5981eb89224ce30"
869 token == "cGF1bC8xMTQ4NTEyOTkxLzM2MC9zb21ldGhpbmcvMTZkMGJhMzY5YTRjOTc4MWI1OTgxZWI4OTIyNGNlMzA="
871 Notes: use_blowfish is available as well
875 real_pass := "123qwe"
876 server_time := 1148514034 # a time in seconds since epoch
877 expires_min := 6 * 60
878 payload := "something"
879 secure_hash := ["aaaa", "bbbb", "cccc", "dddd"]
880 rand1 := 3 # int(rand(length(secure_hash)))
881 rand2 := 39163 # int(rand(100000))
883 md5_pass := md5_sum(real_pass) # if it isn't already a 32 digit md5 sum
885 sh_str1 := join(".", "sh", secure_hash[rand1], rand2)
886 sh_str2 := join(".", "sh", rand1, rand2)
887 str := join("/", user, server_time, expires_min, payload, md5_pass, sh_str1)
888 md5_str := md5(sum_str)
889 token := join("/", user, server_time, expires_min, payload, md5_str, sh_str2)
892 token == "paul/1148514034/360/something/06db2914c9fd4e11499e0652bcf67dae/sh.3.39163"
894 Notes: use_blowfish is available as well. The secure_hash keys need to be set in the
895 "secure_hash_keys" property of the CGI::Ex::Auth object.
897 =item C<get_valid_auth>
899 Performs the core logic. Returns an auth object on successful login.
900 Returns false on errored login (with the details of the error stored in
901 $@). If a false value is returned, execution of the CGI should be halted.
902 get_valid_auth WILL NOT automatically stop execution.
904 $auth->get_valid_auth || exit;
906 Optionally, the class and a list of arguments may be passed. This will create a
907 new object using the passed arguments, and then run get_valid_auth.
909 CGI::Ex::Auth->get_valid_auth({key_user => 'my_user'}) || exit;
913 Called if login errored. Defaults to printing a very basic (but
914 adequate) page loaded from login_template..
916 You will want to override it with a template from your own system.
917 The hook that is called will be passed the step to print (currently
918 only "get_login_info" and "no_cookies"), and a hash containing the
919 form variables as well as the following:
921 =item C<login_hash_common>
923 Passed to the template swapped during login_print.
925 %$form, # any keys passed to the login script
926 error # The text "Login Failed" if a login occurred
927 login_data # A login data object if they failed authentication.
928 key_user # $self->key_user, # the username fieldname
929 key_pass # $self->key_pass, # the password fieldname
930 key_time # $self->key_time, # the server time field name
931 key_save # $self->key_save, # the save password checkbox field name
932 key_payload # $self->key_payload, # the payload fieldname
933 key_redirect # $self->key_redirect, # the redirect fieldname
934 form_name # $self->form_name, # the name of the form
935 script_name # $self->script_name, # where the server will post back to
936 path_info # $self->path_info, # $ENV{PATH_INFO} if any
937 md5_js_path # $self->js_uri_path ."/CGI/Ex/md5.js", # script for cramming
938 use_plaintext # $self->use_plaintext, # used to avoid cramming
939 $self->key_user # $data->{'user'}, # the username (if any)
940 $self->key_pass # '', # intentional blankout
941 $self->key_time # $self->server_time, # the server's time
942 $self->key_payload # $data->{'payload'} # the payload (if any)
943 $self->key_expires_min # $self->expires_min # how many minutes crams are valid
947 If the form hash contains a true value in this field name, the current user will
948 be logged out. Default is "cea_logout".
952 The name of the auth cookie. Default is "cea_user".
956 A field name used during a bounce to see if cookies exist. Default is "cea_verify".
960 The form field name used to pass the username. Default is "cea_user".
964 The form field name used to pass the password. Default is "cea_pass".
968 Works in conjunction with key_expires_min. If key_save is true, then
969 the cookie will be set to be saved for longer than the current session
970 (If it is a plaintext variety it will be given a 20 year life rather
971 than being a session cookie. If it is a cram variety, the expires_min
972 portion of the cram will be set to -1). If it is set to false, the cookie
973 will be available only for the session (If it is a plaintext variety, the cookie
974 will be session based and will be removed on the next loggout. If it is
975 a cram variety then the cookie will only be good for expires_min minutes.
977 Default is "cea_save".
979 =item C<key_expires_min>
981 The name of the form field that contains how long cram type cookies will be valid
982 if key_save contains a false value.
984 Default key name is "cea_expires_min". Default field value is 6 * 60 (six hours).
986 This value will have no effect when use_plaintext or use_crypt is set.
988 A value of -1 means no expiration.
992 The name of the html login form to attach the javascript to. Default is "cea_form".
994 =item C<verify_token>
996 This method verifies the token that was passed either via the form or via cookies.
997 It will accept plaintext or crammed tokens (A listing of the available algorithms
998 for creating tokes is listed below). It also allows for armoring the token with
999 base64 encoding, or using blowfish encryption. A listing of creating these tokens
1000 can be found under generate_token.
1002 =item C<cleanup_user>
1004 Called by verify_token. Default is to do no modification. Allows for usernames to
1005 be lowercased, or canonized in some other way. Should return the cleaned username.
1007 =item C<verify_user>
1009 Called by verify_token. Single argument is the username. May or may not be an
1010 initial check to see if the username is ok. The username will already be cleaned at
1011 this point. Default return is true.
1013 =item C<get_pass_by_user>
1015 Called by verify_token. Given the cleaned, verified username, should return a
1016 valid password for the user. It can always return plaintext. If use_crypt is
1017 enabled, it should return the crypted password. If use_plaintext and use_crypt
1018 are not enabled, it may return the md5 sum of the password.
1022 Returns a CGI::Ex object.
1026 A hash of passed form info. Defaults to CGI::Ex::get_form.
1030 The current cookies. Defaults to CGI::Ex::get_cookies.
1032 =item C<login_template>
1034 Should return either a template filename to use for the login template, or it
1035 should return a reference to a string that contains the template. The contents
1036 will be used in login_print and passed to the template engine.
1038 Default login_template is the values of login_header, login_form, login_script, and
1039 login_script concatenated together.
1041 Values from login_hash_common will be passed to the template engine, and will
1042 also be used to fill in the form.
1044 The basic values are capable of handling most needs so long as appropriate
1045 headers and css styles are used.
1047 =item C<login_header>
1049 Should return a header to use in the default login_template. The default
1050 value will try to PROCESS a file called login_header.tt that should be
1051 located in directory specified by the template_include_path method.
1053 It should ideally supply css styles that format the login_form as desired.
1055 =item C<login_footer>
1057 Same as login_header - but for the footer. Will look for login_footer.tt by
1062 An html chunk that contains the necessary form fields to login the user. The
1063 basic chunk has a username text entry, password text entry, save password checkbox,
1064 and submit button, and any hidden fields necessary for logging in the user.
1066 =item C<login_script>
1068 Contains javascript that will attach to the form from login_form. This script
1069 is capable of taking the login_fields and creating an md5 cram which prevents
1070 the password from being passed plaintext.
1074 Paul Seamons <perlspam at seamons dot com>
This page took 0.113038 seconds and 4 git commands to generate.