CGI::Ex::Auth allows for auto-expiring, safe and easy web based logins. Auth uses javascript modules that perform MD5 hashing to cram the password on the client side before passing them through the internet.

For the stored cookie you can choose to use simple cram mechanisms, secure hash cram tokens, auto expiring logins (not cookie based), and Crypt::Blowfish protection. You can also choose to keep passwords plaintext and to use perl's crypt for testing passwords. Or you can completely replace the cookie parsing/generating and let Auth handle requesting, setting, and storing the cookie.

A theoretical downside to this module is that it does not use a session to preserve state so get_pass_by_user has to happen on every request (any authenticated area has to verify authentication each time - unless the verify_token method is completely overridden). In theory you should be checking the password everytime a user makes a request to make sure the password is still valid. A definite plus is that you don't need to use a session if you don't want to. It is up to the interested reader to add caching to the get_pass_by_user method.

In the end, the only truly secure login method is across an https connection. Any connection across non-https (non-secure) is susceptible to cookie hijacking or tcp hijacking - though the possibility of this is normally small and typically requires access to a machine somewhere in your TCP chain. If in doubt - you should try to use https - but even then you need to guard the logged in area against cross-site javascript exploits. A discussion of all security issues is far beyond the scope of this documentation.

Takes either an auth_data object from a auth_data returned by verify_token, or a hashref of arguments.

Possible arguments are:

user - the username we are generating the token for
real_pass - the password of the user (if use_plaintext is false
and use_crypt is false, the password can be an md5sum
of the user's password)
use_blowfish - indicates that we should use Crypt::Blowfish to protect
the generated token. The value of this argument is used
as the key. Default is false.
use_base64 - indicates that we should use Base64 encoding to protect
the generated token. Default is true. Will not be
used if use_blowfish is true.
use_plaintext - indicates that we should keep the password in plaintext
use_crypt - also indicates that we should keep the password in plaintext
expires_min - says how many minutes until the generated token expires.
Values <= 0 indicate to not ever expire. Used only on cram
types.
payload - a payload that will be passed to generate_payload and then
will be added to cram type tokens. It cannot contain a /.
prefer_simple_cram
- If the secure_hash_keys method returns keys, and it is a non-plaintext
token, generate_token will create a secure_hash_cram. Set
this value to true to tell it to use a simple_cram. This
is generally only useful in testing.

The following are types of tokens that can be generated by generate_token. Each type includes pseudocode and a sample of a generated that token.

Performs the core logic. Returns an auth object on successful login. Returns false on errored login (with the details of the error stored in $@). If a false value is returned, execution of the CGI should be halted. get_valid_auth WILL NOT automatically stop execution.

$auth->get_valid_auth || exit;

Optionally, the class and a list of arguments may be passed. This will create a new object using the passed arguments, and then run get_valid_auth.

Called if login errored. Defaults to printing a very basic (but adequate) page loaded from login_template..

You will want to override it with a template from your own system. The hook that is called will be passed the step to print (currently only "get_login_info" and "no_cookies"), and a hash containing the form variables as well as the following:

Works in conjunction with key_expires_min. If key_save is true, then the cookie will be set to be saved for longer than the current session (If it is a plaintext variety it will be given a 20 year life rather than being a session cookie. If it is a cram variety, the expires_min portion of the cram will be set to -1). If it is set to false, the cookie will be available only for the session (If it is a plaintext variety, the cookie will be session based and will be removed on the next loggout. If it is a cram variety then the cookie will only be good for expires_min minutes.

This method verifies the token that was passed either via the form or via cookies. It will accept plaintext or crammed tokens (A listing of the available algorithms for creating tokes is listed below). It also allows for armoring the token with base64 encoding, or using blowfish encryption. A listing of creating these tokens can be found under generate_token.

Called by verify_token. Given the cleaned, verified username, should return a valid password for the user. It can always return plaintext. If use_crypt is enabled, it should return the crypted password. If use_plaintext and use_crypt are not enabled, it may return the md5 sum of the password.

Alternately, get_pass_by_user may return a hashref of data items that will be added to the data object if the token is valid. The hashref must also contain a key named real_pass or password that contains the password. Note that keys passed back in the hashref that are already in the data object will override those in the data object.

Called by verify_token. Passed the password to check as well as the auth data object. Should return true if the password matches. Default method can handle md5, crypt, cram, secure_hash_cram, and plaintext (all of the default types supported by generate_token). If a property named verify_password exists, it will be used and called as a coderef rather than using the default method.

Called by verify_token. Passed the password to check as well as the auth data object. Should return true if the payload is valid. Default method returns true without performing any checks on the payload. If a property named verify_password exists, it will be used and called as a coderef rather than using the default method.

Should return either a template filename to use for the login template, or it should return a reference to a string that contains the template. The contents will be used in login_print and passed to the template engine.

Default login_template is the values of login_header, login_form, login_script, and login_script concatenated together.

Values from login_hash_common will be passed to the template engine, and will also be used to fill in the form.

The basic values are capable of handling most needs so long as appropriate headers and css styles are used.

Should return a header to use in the default login_template. The default value will try to PROCESS a file called login_header.tt that should be located in directory specified by the template_include_path method.

It should ideally supply css styles that format the login_form as desired.

An html chunk that contains the necessary form fields to login the user. The basic chunk has a username text entry, password text entry, save password checkbox, and submit button, and any hidden fields necessary for logging in the user.

Disables simple cram type from being an available type. Default is false. If set, then one of use_plaintext, use_crypt, or secure_hash_keys should be set. Setting this option allows for payloads to be generated by the server only - otherwise a user who understands the algorithm could generate a valid simple_cram cookie with a custom payload.

Another option would be to only accept payloads from tokens if use_blowfish is set and armor was equal to "blowfish."