view release on metacpan or  search on metacpan

lib/Apache2/AuthCookieDBImg.pm  view on Meta::CPAN

#===============================================================================

=head1 NAME

Apache2::AuthCookieDBImg

=head1 PURPOSE

An AuthCookie module backed by a DBI database with second level
authentication via image matching.  This is very simple image
authentication scheme that is only meant to prevent robotic
logins to a web page by adding a 2nd level of authentication.

=head1 SYNOPSIS

    # In httpd.conf or .htaccess
        
    PerlModule Apache2::AuthCookieDBImg
    PerlSetVar WhatEverPath /
    PerlSetVar WhatEverLoginScript /login.pl

    # Optional, to share tickets between servers.
    PerlSetVar WhatEverDomain .domain.com
    
    # These must be set
    PerlSetVar WhatEverDBI_DSN "DBI:mysql:database=test"
    PerlSetVar WhatEverDBI_SecretKey "489e5eaad8b3208f9ad8792ef4afca73598ae666b0206a9c92ac877e73ce835c"

    # These are optional, the module sets sensible defaults.
    PerlSetVar WhatEverDBI_User "nobody"
    PerlSetVar WhatEverDBI_Password "password"

    PerlSetVar WhatEverDBI_UsersTable "users"
    PerlSetVar WhatEverDBI_UserField "user"
    PerlSetVar WhatEverDBI_PasswordField "password"
    PerlSetVar WhatEverDBI_CryptType "none"

    PerlSetVar WhatEverDBI_GroupsTable "groups"
    PerlSetVar WhatEverDBI_GroupField "grp"
    PerlSetVar WhatEverDBI_GroupUserField "user"

	 # These are optional, if all 3 are set
    # Image verification is performed
	 # The word is passed in via credential_2
	 # The key is passed in via credential_3
	 #
    PerlSetVar WhatEverDBI_ImgTable 		"images"
    PerlSetVar WhatEverDBI_ImgWordField 	"imageword"
    PerlSetVar WhatEverDBI_ImgKeyField 	"imagekey"

    PerlSetVar WhatEverDBI_EncryptionType "none"
    PerlSetVar WhatEverDBI_SessionLifetime 00-24-00-00

    # Protected by AuthCookieDBImg.
    <Directory /www/domain.com/authcookiedbimg>
        AuthType Apache2::AuthCookieDBImg
        AuthName WhatEver
        PerlAuthenHandler Apache2::AuthCookieDBImg->authenticate
        PerlAuthzHandler Apache2::AuthCookieDBImg->authorize
        require valid-user
        # or you can require users:
        require user jacob
        # You can optionally require groups.
        require group system
    </Directory>

    # Login location.
    <Files LOGIN>
        AuthType Apache2::AuthCookieDBImg
        AuthName WhatEver
        SetHandler perl-script
        PerlHandler Apache2::AuthCookieDBImg->login
    </Files>

=head1 DESCRIPTION

This module is an authentication handler that uses the basic mechanism provided
by Apache2::AuthCookie with a DBI database for ticket-based protection.  It
is based on two tokens being provided, a username and password, which can
be any strings (there are no illegal characters for either).  The username is
used to set the remote user as if Basic Authentication was used.

On an attempt to access a protected location without a valid cookie being
provided, the module prints an HTML login form (produced by a CGI or any
other handler; this can be a static file if you want to always send people
to the same entry page when they log in).  This login form has fields for
username and password.  On submitting it, the username and password are looked
up in the DBI database.  The supplied password is checked against the password
in the database; the password in the database can be plaintext, or a crypt()
or md5_hex() checksum of the password.  If this succeeds, the user is issued
a ticket.  This ticket contains the username, an issue time, an expire time,
and an MD5 checksum of those and a secret key for the server.  It can
optionally be encrypted before returning it to the client in the cookie;
encryption is only useful for preventing the client from seeing the expire
time.  If you wish to protect passwords in transport, use an SSL-encrypted
connection.  The ticket is given in a cookie that the browser stores.

After a login the user is redirected to the location they originally wished
to view (or to a fixed page if the login "script" was really a static file).

On this access and any subsequent attempt to access a protected document, the
browser returns the ticket to the server.  The server unencrypts it if
encrypted tickets are enabled, then extracts the username, issue time, expire
time and checksum.  A new checksum is calculated of the username, issue time,
expire time and the secret key again; if it agrees with the checksum that
the client supplied, we know that the data has not been tampered with.  We
next check that the expire time has not passed.  If not, the ticket is still
good, so we set the username.

Authorization checks then check that any "require valid-user" or "require
user jacob" settings are passed.  Finally, if a "require group foo" directive
was given, the module will look up the username in a groups database and

lib/Apache2/AuthCookieDBImg.pm  view on Meta::CPAN

=item C<WhatEverDBI_PasswordField>

The field in the above table that has the password.  This is not
required and defaults to 'password'.

=item C<WhatEverDBI_CryptType>

What kind of hashing is used on the password field in the database.  This can
be 'none', 'crypt', or 'md5'.  This is not required and defaults to 'none'.

=item C<WhatEverDBI_GroupsTable>

The table that has the user / group information.  This is not required and
defaults to 'groups'.

=item C<WhatEverDBI_GroupField>

The field in the above table that has the group name.  This is not required
and defaults to 'grp' (to prevent conflicts with the SQL reserved word 'group').

=item C<WhatEverDBI_GroupUserField>

The field in the above table that has the user name.  This is not required
and defaults to 'user'.

=item C<WhatEverDBI_ImgTable>

The table that has the image to word mapping information.  This is not required and
defaults to 'groups'.

=item C<WhatEverDBI_GroupField>

The field in the above table that has the group name.  This is not required
and defaults to 'grp' (to prevent conflicts with the SQL reserved word 'group').

=item C<WhatEverDBI_GroupUserField>

The field in the above table that has the user name.  This is not required
and defaults to 'user'.

=item C<WhatEverDBI_EncryptionType>

What kind of encryption to use to prevent the user from looking at the fields
in the ticket we give them.  This is almost completely useless, so don''t
switch it on unless you really know you need it.  It does not provide any
protection of the password in transport; use SSL for that.  It can be 'none',
'des', 'idea', 'blowfish', or 'blowfish_pp'.

This is not required and defaults to 'none'.

=item C<WhatEverDBI_SessionLifetime>

How long tickets are good for after being issued.  Note that presently
Apache2::AuthCookie does not set a client-side expire time, which means that
most clients will only keep the cookie until the user quits the browser.
However, if you wish to force people to log in again sooner than that, set
this value.  This can be 'forever' or a life time specified as:

    DD-hh-mm-ss -- Days, hours, minute and seconds to live.

This is not required and defaults to '00-24-00-00' or 24 hours.

=item C<WhatEverDBI_SessionModule>

Which Apache2::Session module to use for persistent sessions.
For example, a value could be "Apache2::Session::MySQL".  The DSN will
be the same as used for authentication.  The session created will be
stored in $r->pnotes( WhatEver ).

If you use this, you should put:

    PerlModule Apache2::Session::MySQL

(or whatever the name of your session module is) in your httpd.conf file,
so it is loaded.

If you are using this directive, you can timeout a session on the server side
by deleting the user''s session.  Authentication will then fail for them.

This is not required and defaults to none, meaning no session objects will
be created.

=item C<WhatEverDBI_SessionActiveReset>

Force the session cookie expiration to reset whenever user activity is
detected (new page loaded, etc.).  This allows a low expiration time (5 minutes)
that logs off when a session is inactive.  Active sessions will be granted
more time each time they perform an action.

This is not required and defaults to 0 (Expire X minutes after initial logon).

=cut

sub _dbi_config_vars($) {
    my( $r ) = @_;
    my %c; # config variables hash

    unless ( $c{ DBI_DSN } = _dir_config_var $r, 'DBI_DSN' ) {
        _log_not_set $r, 'DBI_DSN';
        return undef;
    }

    unless ( $c{ DBI_secretkey } = _dir_config_var $r, 'DBI_SecretKey' ) {
        _log_not_set $r, 'DBI_SecretKey';
        return undef;
    }

    $c{ DBI_user           } = _dir_config_var( $r, 'DBI_User'           )                || undef;
    $c{ DBI_password       } = _dir_config_var( $r, 'DBI_Password'       )                || undef;
    $c{ DBI_userstable     } = _dir_config_var( $r, 'DBI_UsersTable'     )                || 'users';
    $c{ DBI_userfield      } = _dir_config_var( $r, 'DBI_UserField'      )                || 'user';
    $c{ DBI_passwordfield  } = _dir_config_var( $r, 'DBI_PasswordField'  )                || 'password';
    $c{ DBI_crypttype      } = _dir_config_var( $r, 'DBI_CryptType'      )                || 'none';
    $c{ DBI_groupstable    } = _dir_config_var( $r, 'DBI_GroupsTable'    ) 					|| 'groups';
    $c{ DBI_groupfield     } = _dir_config_var( $r, 'DBI_GroupField'     ) 					|| 'grp';
    $c{ DBI_groupuserfield } = _dir_config_var( $r, 'DBI_GroupUserField' )						|| 'user';
    $c{ DBI_imgtable    	} = _dir_config_var( $r, 'DBI_ImgTable'		 ) 					|| '';
    $c{ DBI_imgkeyfield   	} = _dir_config_var( $r, 'DBI_ImgKeyField'	 )						|| '';
    $c{ DBI_imgwordfield   } = _dir_config_var( $r, 'DBI_ImgWordField'	 )						|| '';
    $c{ DBI_encryptiontype } = _dir_config_var( $r, 'DBI_EncryptionType' )    	         || 'none';
    $c{ DBI_sessionlifetime} = _dir_config_var( $r, 'DBI_SessionLifetime') 					|| '00-24-00-00';
    $c{ DBI_sessionmodule 	} = _dir_config_var( $r, 'DBI_SessionModule'  );
    $c{ DBI_SessionActiveReset } = _dir_config_var( $r, 'DBI_SessionActiveReset' ) 			|| 0;

    return %c;

    # If we used encryption we need to pull in Crypt::CBC.
    require Crypt::CBC if ( $c{ DBI_encryptiontype } ne 'none' );

    return %c;
}

#-------------------------------------------------------------------------------
# _now_year_month_day_hour_minute_second -- Return a string with the time in
# this order separated by dashes.

sub _now_year_month_day_hour_minute_second()
{
    return sprintf '%04d-%02d-%02d-%02d-%02d-%02d', Today_and_Now;
}

#-------------------------------------------------------------------------------
# _percent_encode -- Percent-encode (like URI encoding) any non-alphanumberics
# in the supplied string.

sub _percent_encode($)
{
    my( $str ) = @_;
    $str =~ s/([^\w])/ uc sprintf '%%%02x', ord $1 /eg;
    return $str;
}

#-------------------------------------------------------------------------------
# _percent_decode -- Percent-decode (like URI decoding) any %XX sequences in
# the supplied string.

sub _percent_decode($)
{
    my( $str ) = @_;
    $str =~ s/%([0-9a-fA-F]{2})/ pack( "c",hex( $1 ) ) /ge;
    return $str;
}

#===============================================================================
# P U B L I C   F U N C T I O N S
#===============================================================================

=head1 SUBCLASSING

You can subclass this module to override public functions and change
their behaviour.

=over 4

=item C<extra_session_info()>

This method returns extra fields to add to the session key.
It should return a string consisting of ":field1:field2:field3"
(where each field is preceded by a colon).

The default implementation does nothing.