NAME

Apache::AuthCookiePAM - An AuthCookie module backed by a PAM .

VERSION

        $Revision: 1.0 $

SYNOPSIS

        # In httpd.conf or .htaccess
        # This PerlSetVar MUST precede the PerlModule line because the
        # key is read in a BEGIN block when the module is loaded.
        PerlSetVar WhatEverPaM_SecretKeyFile /etc/httpd/acme.com.key
        PerlSetVar WhatEverPAM_service login

        PerlModule Apache::AuthCookiePAM
        PerlSetVar WhatEverPath /
        PerlSetVar WhatEverLoginScript /login.pl

        # Optional, to share tickets between servers.
        PerlSetVar WhatEverDomain .domain.com
        PerlSetVar WhatEverChangePwdScript /changepwd.pl
        
        # These are optional, the module sets sensible defaults.
        PerlSetVar WhatEverPAM_SessionLifetime 00-24-00-00

        # Protected by AuthCookiePAM.
        <Directory /www/domain.com/authcookiepam>
                AuthType Apache::AuthCookiePAM
                AuthName WhatEver
                PerlAuthenHandler Apache::AuthCookiePAM->authenticate
                PerlAuthzHandler Apache::AuthCookiePAM->authorize
                require valid-user
        </Directory>

        # Login location.  *** DEBUG *** I still think this is screwy
        <Files LOGIN>
                AuthType Apache::AuthCookiePAM
                AuthName WhatEver
                SetHandler perl-script
                PerlHandler Apache::AuthCookiePAM->login
        </Files>

        <Files ChangePwd>
                AuthType Apache::AuthCookiePAM
                AuthName WhatEver
                SetHandler perl-script
                PerlHandler Apache::AuthCookiePAM->changepwd
        </Files>

DESCRIPTION

This module is an authentication handler that uses the basic mechanism provided by Apache::AuthCookie with PAM (based on DBI) . 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 verfied using PAM. 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" . If checks pass, the document requested is displayed.

If a ticket has expired or is otherwise invalid it is cleared in the browser and the login form is shown again.

APACHE CONFIGURATION DIRECTIVES

All configuration directives for this module are passed in PerlSetVars. These PerlSetVars must begin with the AuthName that you are describing, so if your AuthName is PrivateBankingSystem they will look like:

        PerlSetVar ProvateBankingSystemLoginScript /bvsm/login.pl

See also Apache::Authcookie for the directives required for any kind of Apache::AuthCookie-based authentication system.

In the following descriptions, replace "WhatEver" with your particular AuthName. The available configuration directives are as follows:

WhatEverPAM_SecretKeyFile

The file that contains the secret key (on the first line of the file). This is required and has no default value. This key should be owned and only readable by root. It is read at server startup time. The key should be long and fairly random. If you want, you can change it and restart the server, (maybe daily), which will invalidate all prior-issued tickets.

This directive MUST be set before the PerlModule line that loads this module, because the secret key file is read immediately (at server start time). This is so you can have it owned and only readable by root even though Apache then changes to another user.

WhatEverPAM_SessionLifetime

How long tickets are good for after being issued. Note that presently Apache::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.

WhatEverPAM_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'.

WhatEverPAM_service

The service that will be using PAM libraries for authentication. These will be one of the services configured in /etc/pam.conf or /etc/pam.d/<service>

This directive defaults to "login"

COPYRIGHT

Copyright (C) 2002 SF Interactive.

LICENSE

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

AUTHOR

Vandana Awasthi

SEE ALSO

Apache::AuthCookie(1)