+Constructor. Takes a hashref of properties as arguments.
+
+Many of the methods which may be overridden in a subclass,
+or may be passed as properties to the new constuctor such as in the following:
+
+ CGI::Ex::Auth->new({
+ get_pass_by_user => \&my_pass_sub,
+ key_user => 'my_user',
+ key_pass => 'my_pass',
+ login_template => \"<form><input name=my_user ... </form>",
+ });
+
+The following methods will look for properties of the same name. Each of these will be
+defined separately.
+
+ cgix
+ cleanup_user
+ cookies
+ expires_min
+ form
+ form_name
+ get_pass_by_user
+ js_uri_path
+ key_cookie
+ key_expires_min
+ key_logout
+ key_pass
+ key_payload
+ key_redirect
+ key_save
+ key_time
+ key_user
+ key_verify
+ key_loggedout
+ bounce_on_logout
+ login_footer
+ login_form
+ login_header
+ login_script
+ login_template
+ handle_success
+ handle_failure
+ success_hook
+ failure_hook
+ no_cookie_verify
+ path_info
+ script_name
+ secure_hash_keys
+ template_args
+ template_include_path
+ text_user
+ text_pass
+ text_save
+ text_submit
+ hide_save
+ use_base64
+ use_blowfish
+ use_crypt
+ use_plaintext
+ verify_payload
+ verify_user
+
+=item C<generate_token>
+
+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_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 normal 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.
+
+ plaintext:
+ user := "paul"
+ real_pass := "123qwe"
+ token := join("/", user, real_pass);
+
+ use_base64 := 0
+ token == "paul/123qwe"
+
+ use_base64 := 1
+ token == "cGF1bC8xMjNxd2U="
+
+ use_blowfish := "foobarbaz"
+ token == "6da702975190f0fe98a746f0d6514683"
+
+ Notes: This token will be used if either use_plaintext or use_crypt is set.
+ The real_pass can also be the md5_sum of the password. If real_pass is an md5_sum
+ of the password but the get_pass_by_user hook returns the crypt'ed password, the
+ token will not be able to be verified.
+
+ cram:
+ user := "paul"
+ real_pass := "123qwe"
+ server_time := 1148512991 # a time in seconds since epoch
+ expires_min := 6 * 60
+ payload := "something"
+
+ md5_pass := md5_sum(real_pass) # if it isn't already a 32 digit md5 sum
+ str := join("/", user, server_time, expires_min, payload, md5_pass)
+ md5_str := md5(sum_str)
+ token := join("/", user, server_time, expires_min, payload, md5_str)
+
+ use_base64 := 0
+ token == "paul/1148512991/360/something/16d0ba369a4c9781b5981eb89224ce30"
+
+ use_base64 := 1
+ token == "cGF1bC8xMTQ4NTEyOTkxLzM2MC9zb21ldGhpbmcvMTZkMGJhMzY5YTRjOTc4MWI1OTgxZWI4OTIyNGNlMzA="
+
+ Notes: use_blowfish is available as well
+
+ secure_hash_cram:
+ user := "paul"
+ real_pass := "123qwe"
+ server_time := 1148514034 # a time in seconds since epoch
+ expires_min := 6 * 60
+ payload := "something"
+ secure_hash := ["aaaa", "bbbb", "cccc", "dddd"]
+ rand1 := 3 # int(rand(length(secure_hash)))
+ rand2 := 39163 # int(rand(100000))
+
+ md5_pass := md5_sum(real_pass) # if it isn't already a 32 digit md5 sum
+
+ sh_str1 := join(".", "sh", secure_hash[rand1], rand2)
+ sh_str2 := join(".", "sh", rand1, rand2)
+ str := join("/", user, server_time, expires_min, payload, md5_pass, sh_str1)
+ md5_str := md5(sum_str)
+ token := join("/", user, server_time, expires_min, payload, md5_str, sh_str2)
+
+ use_base64 := 0
+ token == "paul/1148514034/360/something/06db2914c9fd4e11499e0652bcf67dae/sh.3.39163"
+
+ Notes: use_blowfish is available as well. The secure_hash keys need to be set in the
+ "secure_hash_keys" property of the CGI::Ex::Auth object.
+
+=item C<get_valid_auth>
+
+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.