Digest::Auth / Reference

For the latest version of documentation for Digest::Auth please view the POD documentation that is included with the Perl Module.

Methods:

1. new()
2. Set()
3. Get()
4. Initialize()
5. Validate()
6. Authorize()
7. AutoAuth()
8. TableMake()
9. UserAdd()
10. SQL_Die()
11. DebugAdd()
12. DebugShow()
13. CookieGet()
14. CookieSet()
15. WriteScript()
16. JS_Digest()
17. Keygen()

1. dbh
2. debug
3. debuginfo
4. cookiename
5. domain
6. usecookies
7. digest
8. connection
9. validation
10. idletime
11. initcertretry
12. forgiverate
13. maxconperip
14. maxconperuser
15. maxbadpass
16. compatmode
17. locklength
18. datamapping

Here is a simplistic script that utilizes the base functions of Digest::Auth

Code:

Declaring a new instance of Digest::Auth is easy.

This declares a new instance of Digest::Auth. You can pass any number of Parameters to it in this method however at minimum it is a good practice to pass the database handel Parameter since most of the other functions requrire it to work properly.

Code:

Digest::Auth keeps tabs on how long sessions are allowed to last. To change or set options you can use the Set() and Get() methods. Set() takes one or multiple arguments as a Hash.

Code:

Digest::Auth keeps tabs on how long sessions are allowed to last. To change or set options you can use the Set() and Get() methods. Get() takes single variable arguements.

Code:

Establish a session with Initialize(). Ideally you would next use WriteScript() next unless compatmode is on to convert the users credentials to secure hashes before submitting the data back for validation.

Code:

Use Validate() to authorize the users credentials after a session has been initalized. Depending on the setting of compatmode there is a different argument you need to supply. Arguements are in a hash format. See below:

Code:

This takes the users credentials and attempts to authorize the validated user. It takes only two arguements, the userid and hash. If usecookies is off the you will need to call this function with arguments as below, if usecookies is on then it can be called without arguments.

Code:

Method to checks to see if based on the ruleset a session can be established. This is automatically called but can also be called manually. Returns a Hash.

Code:

Logs entry of a bad session attempt.

Code:

Creates a lockout for a username/ip.

Code:

Expires a lock entry.

Code:

This is an experimental automatic authorization method that chooses which functions are required. I would reccomend not using it until the method becomes more stable.

Code:

To make your life easier if you don't have an existing table structure you can make all the tables for your database by just calling the TableMake() method.

Code:

This method simplifies adding a new user to the user table. Like all the other methods, they respect the datastructure, which means if you change the datamapping of user to myusers for the table name it will populate the myusers table instead.

Code:

This is a debugging tool that helps neatly print SQL statements out in HTML when module for debug messages.

Code:

A debugging tool that appends data to the debug info.

Code:

A debugging tool that prints out the debug information.

Code:

Retreives cookie information. Note: when using usecookies you do not have to parse this and put it into the Authorize hash since it is done automatically for you.

Code:

Set some hash data into the cookie for reuse. Note: when using usecookies you do not have to take the hash results of Authorize() and put it into this method since it is done automatically for you.

Code:

Returns a javascript formatted to print out.

Code:

Returns Javascript clientside code to produce hashes.

Code:

The Keygen() method takes two arguements; Key Length (1 to 128) and Complexity (1 to 3). Key length is the length or number of characters you would like to have returned. Complexity is what type of data (1 Upper case letters, 2 uppercase letters and numbers, 3 uppercase letters, lowercase letters and numbers). By design Digest::Auth uses complexity 3. Since we are using by default 10 digit alpha-numeric random keys we are looking at around 1 in 58 to the power of 10 (about 1 in 430,804,206,899,405,800).

Code:

Passes an open Database handel to the Digest::Auth perl module. If you dont have access to a database server there is a great module called SQLite (http://www.sqlite.org/) that will do the trick, all it requires is downloading the Perl Module and reading a few peices of documentation. This module was designed to originally work with MySQL, however any SQL compliant Database provided there is a DBI/DBD connecter should work.

Code:

Debug mode spews additional information. Use 1=on or 0=off. Default is off.

Code:

This variable stores Debug information in HTML format when the parameter debug is is active. While you can't set this variable information, you can retrive it easily.

Code:

Cookie name to use for authorization. This variable dertermines the name of the cookie that maintains user session credentials. In most cases you can leave it as is.

Code:

Domain name to use for the for cookie, etc. If you are using cookies it is required for them to work properly.

Code:

Use cookies to maintain sessions. By default to make programmers lives easier

Code:

Hash Digest to use. An internal function DigestMake() looks at the digest Parameter and will try to make a new instance via SomeDigest->new(), then it trys to add data via SomeDigest->add(), and will finally try to get a hex digest by calling SomeDigest->hexdigest(). This basically means that if you make an object oreinted digest with these standard functions it will tie in without any problems.

Code:

Maximum total length of time a session is allowed to be. Default is 86400 seconds (24 hours). To disable change to -1. This will expire an active session if it exceedes this amout of time which helps to prevent some bot/macro'ed actions that would keep the user active indefinately. The user should be able to log back in afterwards immediatly. This combined with a Human Readable Identification code will keep people from abusing login times. For help with random text you can use the Keygen() method.

Code:

Amount of time a user has to enter a username and password and submit it back to the server before their validation cert/key becomes invalid. Default is 600 seconds (10 minutes). To disable change to -1.

Code:

Amount of time a user has to idle in the system without their session expiring. Default time is 3600 seconds (60 minutes). To disable change to -1.

Code:

Number of times to retry intitializing a session if the key is a duplicate. Note that a collision in cert keys is extreemly rare. Since we are using by default 10 digit alpha-numeric random keys we are looking at around 1 in 58 to the power of 10 (about 1 in 430,804,206,899,405,800).

Code:

This variable controls how long it takes for bad login attempts to expire. This is applies to loggin in on an invalid session hash, username, ip address, etc.

Code:

Maximum connections/sessions per IP address. Default is 1. For an unlimited number of sessions per IP address (Highly unreccomended) use the value of -1. If you were working with serveral machines that were NAT'ed behind a router you would want to have one entry per user beihnd that single IP address. Typically this is not a big deal for big businesses that have a huge block of IP's, but when working with small businesses you may want to have this set from 10 to 50 for companies that use one external IP off a T1/DSL/Cable line for 10 to 50 users (after which usually the companies tend to grow and buy a block of IP addresses). Setting this above 1 tends to reduce security by opening a possible man in the middle attack. Then again it may be the lesser of two evils where people would share a single username and password circumventing security in a worse way.

Code:

Maximum connections/sessions per user name. Default is 1. For an unlimited number of sessions per IP address (Highly unreccomended) use the value of -1.

Code:

Maximum number of times a user can enter a bad password before they get banned/locked out. Default is 5. For an unlimited number of sessions per IP address (Highly unreccomended) use the value of -1.

Code:

WARNING: THIS REDUCES SECURITY: Change to 1 to enable compatibility for non-javascript browsers. Instead the password will be passed in plaintext to the server with the other credentials which makes a hash out of the credential data and compairs it to the stored user credentials and the session credentials to attempt to validate or authorize the users.

Code:

This determines how bans/locks for rule violations are handeled. In most cases you can just leave these as is. The ban length goes up with each additional rule violation that occours within the forgiverate. This is one of the trickier items to configure.

The defaults are: 5 min, then 15 min, then 1 hr, then 1 day, then permenent. You can add or remove levels in between each section if you want for the ban length rules. All times are in seconds, and you can use -1 for permenent. The library expects concurrently increasing ban lengths.

Code:

Optionally use this option if you are using this module with an existing user database. It allows you to modify the column names the module utilizes. The first level of the hash array corrosponds. The changes are immediatly respected.

Code: