CF_EzPassword Documentation v1.0f
by Dan G. Switzer, II

CF_EzPassword is the easiest way to password protect areas of your site using ColdFusion. Not only is it the easiest and quickest way, it's the most versatile too!

Unlike other ColdFusion login tags available, CF_EzPassword does not require a database^* or client/session management to work! This means that you can set up CF_EzPassword quickly and run it on any server using ColdFusion (version 4 or higher) without any additional installation.

CF_EzPassword works by storing an encrypted^** string into the user's browser via a cookie. CF_EzPassword even allows you to specify the key to be used in the encryption, which nearly eliminates any chances of someone decrypting the string.

Using CF_EzPassword you'll be able to:

• Validate users quickly and easily
• Create basic security quickly and easily. No more turning to client management to handle a simple password protection scheme on one or two pages on your site.
• Tie in to existing user databases
• Expire "sessions" after a user-definied number of minutes

* NOTE: Although CF_EzPassword does not require a database to work, it's open architecture easily allows you to integrate it with your current user database. All that's required is that you pass CF_EzPassword a valid query name, with a "username" and "password" field, and CF_EzPassword can validate the user's information for you. This allows for maximum flexibility and expansion.

** NOTE: CF_EzPassword relies on the encryption function in ColdFusion to handle it's encryption algorithms. PengoWorks.com does not take responsibility for any problems that may occur from using this funtion.

CF_EzPassword requires the following:

• A licensed copy of ColdFusion (version 4.0 or higher)
• Cookies must be enabled in the user's browser

To install CF_EzPassword, do the following:

• Copy the file EzPassword.cfm to either your custom tags directory (i.e. C:\Cfusion\CustomTags\) or to the directory in which you plan on using CF_EzPassword.

Before getting started, there are a few important things to note. CF_EzPassword requires that cookies are enabled in the user's browser. If cookies are disabled, then the current revision of CF_EzPassword will not function properly.

NOTE: Most ColdFusion-based login tags use client variable which, by default, rely on cookies being enabled into the users browser.

Below is a listing of each attribute and an indepth description of what the attribute is.

Attribute		Description
QUERY		If you plan on using using an external datasource to verify user information, then use this attribute. When using a QUERY as your validation source, the query passed must have the fields "USERNAME" and "PASSWORD." If your current database schema does not match this syntax, no need to worry, use an alias! For example: <CFQUERY NAME="GetUsers" DATASOURCE="#myDataSource#">   SELECT userid AS USERNAME, userpwd AS PASSWORD, F_Name, L_Name, Access   FROM Users   WHERE Active = 1 </CFQUERY> The two areas in italics show how using the SQL aliasing technique you can format the query to match the requirements of CF_EzPassword.
USERNAME		If you're not using the QUERY attribute, then this attribute is required.. Fill in a delimited list of valid user names. This list must sync with the list provided to the PASSWORD attribute. You can specify as few (one) to as many user names as you like. (The default delimiter used is the pipe symbol ("|"). You can change this by using the DELIMITERS attribute.)
PASSWORD		If you're not using the QUERY attribute, then this attribute is required.. Fill in a delimited list of valid passwords. This list must sync with the list provided to the USERNAME attribute. You can specify as few (one) to as many user names as you like. (The default delimiter used is the pipe symbol ("|"). You can change this by using the DELIMITERS attribute.)
SECURENAME		This is essentially a "key" that locks the username and password to only being valid when compared against the same key. This allows you to use the same username and password combination on different areas of your site, but keeps the areas unique so that one user can't access the other user's information.
DELIMITERS		This attribute is used to define a custom delimiter for the USERNAME and PASSWORD attributes. By default the pipe symbol ("|") is used.
OUTPUT		This attribute is used to define the name of the query to be returned to the calling template. This query will return a query with one row, containing the columns "USERNAME, PASSWORD, LASTPAGEHIT". If you specified the QUERY attribute, then the output will also contain columns containing any additional information found within that query. The default variable returned is "ezPassword".
TIMEOUT		This attribute is used to expire a user's "session." This gives you the ability to expire a user's "session" after X number of minutes of inactivity. If left blank, the user's "session" will remain valid forever--or until the username/password requirements change.
FORCELOGOUT		This attribute allows you to expire a user's "session" manually. When the FORCELOGOUT attibute is set to "YES", the user's cookie is deleted. To redirect the user to another page at the same time you expire the cookie, use the LOGOUTURL attribute. (Valid options are "YES" or "NO".)
LOGOUTURL		This attribute allows you to assign a URL that the user should be redirect to, after the user has been logged off the system with the FORCELOGOUT attribute. LOGOUTURL uses the <META HTTP-EQUIV="REFRESH"> method and/or JavaScript to redirect the user to another page. Since EzPassword uses <CFCOOKIE> to track the user, you can not use a <CFLOCATION> tag on the same page as <CF_EzPassword>.
ENCRYPTKEY		This attribute allows you to define the a custom key that will be used within the encryption scheme. This allows you to specify your own key that is unique. (NOTE: If you change this key, then the user will be forced to re-log in. Changing keys after implementing CF_EzPassword is not recommended.)
LOGINSCRIPT		This attribute allows you to define a custom login script. This allows you to create your own HTML page, so you can maintain a specific look and feel. When creating your own login scripts you must name the USERNAME form field: "ezPwdUsername" and the PASSWORD form field: "ezPwdPassword". The value of the ACTION attribute in the <FORM> tag should be set to the ezPassword.Script_Name variable. If the user has attempted to log on, but the information they entered was invalid, then there will be a variable available to your script called "ezPassword.ErrorMessage". If the value is "USERNAME" then, the specified user name did not exist. If the value is "PASSWORD", then the user name provided exists, but does not match the password entered. The variables "ezPassword.Username" and "ezPassword.Password" contain the information entered into the form fields.
ERRORMESSAGE		This attribute allows you to define a custom error message that should be displayed to the user if their login information is incorrect. This message is used if either the user name specified does not exist or if the password does not match the user name entered.
AUTOCOMPLETE		The AUTOCOMPLETE attribute allows to enable or disable IE5's auto-complete form feature. The default value is "OFF". Valid options are "ON" and "OFF".
SECURECOOKIE		This attribute allows you to specify whether or not the cookie written to the browser should be written using SSL. The default value is "NO". Valid options are "YES" or "NO".
SAVECOOKIE		If set to "YES", then the cookie will be written to the user's hard drive, allowing them to close their browser and re-open and still access the page within the given TIMEOUT period. If set to "NO", then the cookie will only remain in the user's memory, which means that closing browser will close the session. The default value is "YES". Valid options are "YES" or "NO".
IPALLOW		This attribute allows you to define a comma-delimited list of IP Address that are allowed to access the page. This allows you to restrict access to just certain IP address or ranges. You can mask a full class by using the asterisk as a masking filter. The default value is "ALL", which means all IP addresses are allowed access to the scripts. (Example: The list "127.0.0.1,128.*.*.*" would include the local host IP address (127.0.0.1), plus any address within the class A of 128.)
IPRESTRICT		This attribute allows you to define a comma-delimited list of IP Address that are restricted from accessing the page. This list overwrites the IPALLOW setting. The default value is blank, which means no IP addresses are excluded. (Example: You could restrict access to a single class C, but also exclude certain IP within that class C by doing the following: <CF_EzPassword   USERNAME="guest"   PASSWORD="guest"   IPALLOW="127.0.0.*"   IPRESTRICT="127.0.0.3,127.0.0.4,127.0.0.5,127.0.0.6"   IPREDIRECT="http://www.pengoworks.com/"> This would allow anyone within the sub class C of 127.0.0.* to access the site—except computers with the IP address 127.0.0.3-6—provided they know the correct login and password. If the user comes from an invalid IP address, the user is sent to the home page for PengoWorks.com
IPREDIRECT		This attribute allows you to define the URL that the user should be redirected to if they fail the IP check. The default value for this is the root of the current server.

<CF_EzPassword 
	USERNAME="admin"
	PASSWORD="welcome"
	TIMEOUT="15"
	>

<CF_EzPassword 
	USERNAME="ColdFusion|guest"
	PASSWORD="Allaire|guest"
	>

<CF_EzPassword 
	USERNAME="cftalk|guest"
	PASSWORD="listserv|guest"
	TIMEOUT="15"
	>

<CF_EzPassword 
	QUERY="GetUsers"
	OUTPUT="UserInfo"
	TIMEOUT="30"
	>

<CF_EzPassword 
	QUERY="GetUsers"
	OUTPUT="UserInfo"
	TIMEOUT="30"
	LOGINSCRIPT="/login.cfm"
	>

<CF_EzPassword
	USERNAME="guest"
	PASSWORD="guest"
	IPALLOW="127.0.0.*"
	IPRESTRICT="127.0.0.3,127.0.0.4,127.0.0.5,127.0.0.6"
	IPREDIRECT="http://www.pengoworks.com/">

<CF_EzPassword 
	FORCELOGOUT="YES"
	>

<CF_EzPassword 
	FORCELOGOUT="YES"
	LOGOUTURL="/index.cfm"
	>