
=head1 NAME

Nes::Obj::secure_login - Secure Login Nes Object.

=head1 SYNOPSIS

Checking for script handler:

    {: include ('{: * cfg_obj_top_dir :}/Nes/form/secure_login.nhtml',
                "
                  script_handler   => 'my_script_handler.pl',
                  function_handler => 'my_function_handler',
                  form_name        => 'my_form_1',
                "
               )         
    :}

Checking directly from a database:

    {: include ('{: * cfg_obj_top_dir :}/Nes/form/secure_login.nhtml',
                "
                  from_table         => 'table',
                  from_user_field    => 'table_field_user',
                  from_pass_field    => 'table_field_pass',
                  from_user_function => 'sql_function',
                  from_pass_function => 'sql_function',
                  form_name          => 'my_form_1',
                "
               )         
    :}

=head1 DESCRIPTION

Create a user session if the login is successful. Verification can be done 
with a script handle or directly from a database. The form prevents intrusion 
by the obfuscation of the fields, limiting the number of attempts and captcha.

=head1 PARAMETERS

=over 2

=item script_handler

The script that contains the "function_handler"

=item function_handler

Function to call to verify login. Receives the form fields user and password. 
Must return "user id" if successful or 0 if failure. Sample:

    sub check_user_login {
      my $user = shift;
      my $pass = shift;

      return 0 if !$user || !$pass;

      # check user and password in db or other
      ...

      return $user_id if $ok;
      return 0        if !$ok;
    }

=item from_table

Verify login to this table name. Sample:

    {: include ('{: * cfg_obj_top_dir :}/Nes/form/secure_login.nhtml',
                "
                  from_table         => 'users',
                  from_user_field    => 'user',
                  from_pass_field    => 'password',
                "
               )         
    :}

For these parameters secure_login make the following sql query:

    SELECT `user`  
    FROM  `users`
    WHERE ( 
           `user` = $user  AND 
           `password` = $pass
          )
    LIMIT 0,1;~;

=item from_user_field

The field name in the table corresponds to the "user".

=item from_pass_field

The field name in the table corresponds to the "password".

=item from_user_function

SQL function apply to "user" in SQL query.

=item from_pass_function

SQL function apply to "password" in SQL query. Sample:

    {: include ('{: * cfg_obj_top_dir :}/Nes/form/secure_login.nhtml',
                "
                  from_table         => 'users',
                  from_user_field    => 'user',
                  from_pass_field    => 'password',
                  from_pass_function => 'PASSWORD',
                "
               )         
    :}

For these parameters secure_login make the following sql query:

    SELECT `user`  
    FROM  `users`
    WHERE ( 
           `user` = $user  AND 
           `password` = PASSWORD($pass)
          )
    LIMIT 0,1;~;

=item DB_base

Database name. Usually DB_... must be previously defined in its nes.cfg, 
secure_login take these defaults. But if you need to consult another 
database, can DB_... as parameters.

Not a good idea to include passwords in files html:

    BAD:
    {: include ('{: * cfg_obj_top_dir :}/Nes/form/secure_login.nhtml',
                "
                  from_table         => 'users',
                  from_user_field    => 'user',
                  from_pass_field    => 'password',
                  DB_base            => 'basename',
                  DB_user            => 'baseuser',
                  DB_pass            => 'sakjuje7ey',
                "
               )         
    :}

Declare them as variables in their nes.cfg:

    # primary database
    DB_base    = basename
    DB_user    = username
    DB_pass    = password
    DB_driver  = mysql
    DB_host    = localhost
    DB_port    = 3306

    # database for login
    login_DB_base    = otherbasename
    login_DB_user    = username
    login_DB_pass    = password
    login_DB_driver  = mysql
    login_DB_host    = localhost
    login_DB_port    = 3306

And so:

    {: include ('{: * cfg_obj_top_dir :}/Nes/form/secure_login.nhtml',
                "
                  from_table         => 'users',
                  from_user_field    => 'user',
                  DB_base            => '{: * cfg_login_DB_base :}',
                  DB_user            => '{: * cfg_login_DB_user :}',
                  DB_pass            => '{: * cfg_login_DB_pass :}',
                "
               )         
    :}

=item DB_user

Database user.

=item DB_pass

Database password.

=item DB_driver

Database driver.

=item DB_host

Database host.

=item DB_port

Database port.

=item min_len_name

Min length of user.

=item max_len_name

Max length of user.

=item min_len_pass

Min length of password.

=item max_len_pass

Max length of password.

=item attempts

Attempts to show the captcha. Default 3.

=item form_attempts

Attempts/minutes, if we reach attempts, wait the time shown in "minutes". 
Default is '10/5'

=item form_location

Error out page, Default 'none'.

=item form_exp_last

Time to expire form in last step. Default '1m' one minute. Time suffix: 
s: seconds, m: minutes h: hours d: days, M: months, y: years. 

=item form_expire

Time to expire form. Default '10m' ten minutes. Time suffix: 
s: seconds, m: minutes h: hours d: days, M: months, y: years. 

=item form_name

Tag name property of form.

=item id_form

Tag id property of form.

=item class_form

Tag class property of form.

=item captcha_name

Tag name property of captcha.

=item captcha_type

ascii.

=item captcha_digits

Digit number captcha.

=item captcha_size

Captcha size.

=item captcha_noise

Captcha noise level.

=item captcha_sig

Character to the foreground

=item captcha_spc

Character to the background

=item captcha_expire

Time to expire captcha. Default '1m' one minute. Time suffix: 
s: seconds, m: minutes h: hours d: days, M: months, y: years. 

=item captcha_atempts

Attempts/minutes, if we reach attempts, wait the time shown in "minutes". 
Default is '10/5'

=item captcha_tag_start

HTML Tag for the design of the captcha.

=item captcha_tag_end

HTML Tag for the design of the captcha.

=item out_page

Out page. Default self.

=item expire_session

The session is created with this time expires. Default '12h'. Time suffix: 
s: seconds, m: minutes h: hours d: days, M: months, y: years. 

=item expire_session_re

The session is created with this time expires if 'remember' option is enable. 
Default '48h'. Time suffix: s: seconds, m: minutes h: hours d: days, 
M: months, y: years. 

=item msg_legend

Text to show in lengend tag.

=item msg_name

Text to show in user name field.

=item msg_pass

Text to show in password field.

=item msg_remember

Text to show in remember field. If empty, remember option is disable.

=item msg_login

Text to show in send button.

=item msg_captcha

Text to show in captcha field.

=item msg_error_form

Text to show error if user/password error.

=item msg_error_captcha

Text to show error if captcha error.

=item msg_error_name

Text to show error if user error. (min_len_name and max_len_name)

=item msg_error_pass

Text to show error if password error. (min_len_pass and max_len_pass)

=item tpl_errors

Template errors.

=item tpl_options

Template for options.

=back

=head1 AUTHOR

Skriptke: Enrique Castañón

=head1 VERSION

Version 1.03 April 2010

=head1 COPYRIGHT

Copyright (c) Enrique F. Castanon Barbero. All rights reserved.

=head1 LICENSE

This program is free software; you can redistribute it
and/or modify it under the same terms and conditions as
GNU Public License (GPL).

This means that you can, at your option, redistribute it and/or 
modify it under either the terms the GNU Public License (GPL), 
or under the Perl Artistic License.

See http://dev.perl.org/licenses/

=head1 DISCLAIMER

THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS
OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE.

Use of this software in any way or in any form, source or binary,
is not allowed in any country which prohibits disclaimers of any
implied warranties of merchantability or fitness for a particular
purpose or any disclaimers of a similar nature.

IN NO EVENT SHALL I BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
SPECIAL, INCIDENTAL,  OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OF THIS SOFTWARE AND ITS DOCUMENTATION (INCLUDING, BUT NOT
LIMITED TO, LOST PROFITS) EVEN IF I HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE

=head1 SEE ALSO

L<Nes>, L<Nes::Tutorial>, L<Nes::Singleton>, L<Nes::nes.cfg>, 
Sample to use Nes; L<http://nes.sourceforge.net/>

=cut

