ASForm: Introduction and Features

Introduction

ASForm is a general-purpose, powerful, highly configurable HTML form-to-email processor for use on the World Wide Web and/or intranets. It was developed by Art Sackett of Art Sackett Professional Web Design for free distribution to meet the needs of many who have been unable to find a similar tool that adequately meets their needs.

ASForm includes a debugging utility that is, to the best of the developer's knowledge, unique in the free CGI application arena. Once ASForm is runnable, switching on the debug mode and invoking (running) ASForm will cause it to analyze your installation and configuration, and explain it to you in English as plain as is possible. Anything that might keep ASForm from working as you expect is called to your attention and explained, and the tests it performs are explained as they're done. You shouldn't have to guess why the thing might be doing things you didn't intend. As an aid in developing configuration files, debugging can be switched on in any configuration files you need to debug, while leaving those that are working in normal operation. You can be processing forms from the web normally while you create and test new configuration files without affecting those "live" configurations. The only exception to this is the main, default configuration -- setting debugging to on in this configuration turns it on for all configurations.

ASForm is at present a single-user, single domain application. Although it will support as many individual configurations as you care to write for it, it is not designed for a multi-user environment, as would be required by an ISP who needs to provide its functionality for many different users. A multi-user version will eventually follow, based upon the final release. (At this time, ASForm is in beta release. There may be bugs, but there are none that are known as of this writing. The intent is that the final release will be compatible with the beta version's configuration files, but this is not in any way guaranteed.)

Please note that although the distribution is free, ASForm comes with some restrictions regarding how you can use it, the Term of Use:

1. ASForm is and must remain freely distributed. You may distribute it in any form you wish, but you may not receive any compensation for doing so. You may not charge a fee for the media that ASForm is distributed on, even if ASForm is bundled with other software.
2. You may use ASForm for any purpose, even commercial purposes, so long as you are not selling ASForm or the media it is distributed on. The only exception to this is if you are selling a used computer system upon which ASForm is installed and ASForm is not a consideration in the price set.
3. ASForm comes with no warranty or guarantee of any kind. If it breaks anything, you get to keep whatever little pieces may be left behind. The developer does not accept any liability whatsoever for any damage, either direct or consequential, that may be caused by ASForm.
4. ASForm must not be deployed in any way that it's failure may cause or exacerbate a threat to the safety of persons or property.
5. ASForm comes with no support from the developer except for paying clients of Art Sackett Professional Web Design.
6. You may not alter or edit ASForm in any way, or create derivative works based upon it. Certain lines of code must be altered in some cases to configure ASForm to work in a given installation, and those lines are referenced within the documentation that comes with ASForm. All others are off limits. If you find a bug, report it to the developer.
7. You may charge a fee for professional services rendered installing, configuring, and/or supporting ASForm. You must make your client aware that ASForm comes with no guarantee of any kind from the developer, and that he is not purchasing ASForm itself.
8. Your possession of an unaltered copy of ASForm is your license to use it. No one can take that license away from you if you have not violated these terms of use. Period.

If it happens that you really like ASForm, especially if it helps you to make money, feel free to send a postcard, preferably with a picture of your home town on it, to the address that's all over at http://www.artsackett.com -- and feel free to contact Art Sackett Professional Web Design for your custom CGI application programming needs. ;-)

ASForm is like most other free CGI applications, in that it comes with absolutely no guarantees whatsoever. If it breaks things, you get to keep whatever little pieces might be left. It comes with no support unless you are or are willing to become a client of Art Sackett Professional Web Design. During the beta period for ASForm, feel free to send an email to cgibugs@artsackett.com if you are pretty certain that you've found a bug or need a quick question answered, after checking at http://www.artsackett.com/freebies/asform for a more recent version than the one you have. (The version number will always appear in the output of debug mode and in the headers of mail from ASForm.) Whether or not you hear back from me in a timely fashion, or at all, will be determined by my workload. We all gotta make a living.

ASForm is intended to be about as secure as any similar application can be, but at this time it still won't run with perl's -T flag set. This is mainly because it's time for me to get on with paying work, and will eventually be corrected. As ASForm runs, it is just looking for an excuse to die, and will not allow some of the more common security mistakes to be made. It checks to make sure that it ought to be sending files that are either mailed or returned to the internet user, and it refuses to cooperate if it finds that it lives in a file that is writable by the HTTP ("web") server. Because it does not accept email addresses for form submission report recipients from the web, it is not really very abusable. It does not expose recipients' email addresses on the web for harvesting spambots, and includes a very configurable HTTP_REFERER filter to ensure that other sites can't count on abusing your installation. It is simply not possible for a remote site to use ASForm as a conduit to your SMTP server for spamming -- with the exception of the address accepted from the web for Autoresponder messages, the only possible recipients of mail from ASForm are those you list in your configuration file(s). Because ASForm does not rely upon any Mail Transfer Agent (such as sendmail) it does not expose any security holes that are part and parcel of the "piped open" that has to happen if an MTA is used. ASForm is its own MTA, and talks to the SMTP server itself -- attempts to get a "shell" will end up as email if the transaction completes at all.

As an aid to maintaining security, once ASForm is properly configured, any event that causes a fatal error is handled by rejecting the transaction, returning an error message to the internet user, and sending an email to the webmaster (named in the configuration file(s)) explaining what went wrong. Optionally, if a transaction is rejected because the non-null value of the HTTP environment variable HTTP_REFERER did not match against the filtering you defined, an Abuse Report can be mailed to the webmaster(s). In short, if someone does manage to get into your installation somehow, all it takes is one mistake on their part and you'll hear about it.

Features

• Processes HTML forms, forwards results via email; optionally, appends reports to a file and/or writes a comma-separated file suitable for processing by other software that knows how to work with a comma-separated flat-file database table.

   

• Unlike many other free form processors, ASForm does not make the user wait until the last step of the process for a redirection to the "success" page. In many cases, doing so leaves the internet user with a timed-out transaction that usually results in multiple submissions and makes you look bad. As soon as ASForm has checked for the presence of all required fields and confirmed the proper formation of email addresses in the user provided data, it sends the user on his way and continues processing "behind the scenes".

  (Those timed-out transactions that other form processors often provide are due to the program waiting on a Mail Transfer Agent, such as sendmail, to return an acknowledgment that it has accepted the mail. On a heavily used system, this can sometimes take several minutes. Time that your users don't want to spend hanging around waiting for their browsers to time out. ASForm has to hang around waiting on the SMTP server to achnowledge that it has accepted the data, but it gets the user on his way first.)

  ASForm is a fairly large program that does a lot of things, but by getting the user on his way as quickly as possible, it appears to be pretty zippy, especially if your server is configured to keep a perl interpreter running all the time. The only time you might run into trouble is if your installation of ASForm is running very many copies at once, to the point where your system has to start swapping it out to the hard drive(s). This will certainly cause sluggish response.

  Also unlike many other free form processors (and part of the reason that ASForm is so big), ASForm does not expect you to put all of the configuration information for a transaction into the HTML form. Usually, you can expect a hard drive access to be a lot faster than the network connection -- so ASForm takes advantage of this by requiring only a couple of things to be in your HTML, and keeping the rest in files on the server's hard drive(s).

   

• Provides for multiple recipients, with the option to select whether all recipients receive all reports, or selected recipients may be identified within your HTML form. Email addresses need not be exposed to the web.

   

• Supports required fields, data sorting, hiding data from the Autoresponder, an option to suppress null (undefined) form data, and the capture of HTTP environment data (such as the IP address of the user).

   

• Provides an Autoresponder, for which you may write your own reply messages. Those messages you write are parsed, and using HTML-like syntax you can include individual data elements from your form into your document template. For instance, if your form has an element "name" that the user provided the value "John Doe" for, you can insert the value from a form submission into the Autoresponder message thusly:
  Dear <name>:
  and in the Autresponder reply it will appear as:
  Dear John Doe:

  There are additional tags that ASForm makes available to you that need not appear in your form data, such as <time>.

  The Autoresponder can be enabled, disabled, or set to "user mode" within your configuration file(s). In user mode, your HTML form dictates whether or not an Autoresponder message should be sent, and you can then leave it to the discretion of either the internet user or to a hidden form field whether to send or suppress the Autoresponder message.

  If you don't want to write your own Autoresponder message, a default can be generated -- you can opt to send or suppress a data "echo", which is a dump of raw form data. The mail From address must be configured within the configuration file, but may also appear in your document template which will override that specified in the configuration file. (It must appear in your configuration file so that if your template cannot be used for some reason and the default message must be sent, it has a return address to use.)

   

• Form submission reports can likewise be written using a template you provide, or a default can be generated. If you desire a raw data dump in your custom reports from a template, all it takes is to include the <dump> tag in your report template. To determine if the user requested or was sent an Autoresponder message, the tag <ar_result> will include a sentence indicating the success or failure of the Autoresponder to hand off the Autoresponder message to the SMTP server. (ASForm won't know if the mail bounced, but if you provide a valid From: address for ASForm to use, bounced mail will go to that account.)

  If you use a mail file and/or a data file, the default message will indicate that the mail/data was copied to the file(s) -- at this time, it is just assumed to have been successful if the program gets to the point that it sends you mail.

   

• As noted above, ASForm is its own Mail Transfer Agent. If you configure it to do so, ASForm will "cache" undeliverable mail and attempt to deliver it the next time the application runs. If five attempts to mail to a given recipient fail, the webmaster address(es) in your configuration file will be added to the list of recipients for that message to allow for manual forwarding by the webmaster. If for some reason an instance of ASForm can't clean up the temporary files it creates while preparing the cache file, another instance of ASForm running later will clean up after it and get those messages into the primary cache file.

  Messages that are undeliverable for any reason (excluding Autoresponder messages) get a one-line message placed at the top, telling when the delivery was attempted and why delivery failed, for each time they fail. You should only expect mail to be undeliverable if the SMTP server is down or rejects a recipient's address for some reason. ASForm will make several attempts before considering a message undeliverable, and first tries to use the SMTP server with the more efficient multiple recipients mode, and failing that falls back to mailing the recipients individually.

  (Autoresponder messages either go or don't, and are not cached. If for some reason an Autoresponder message is rejected by the SMTP server, the default report configuration, and any well-written report template, will tell you.)

  Because ASForm is its own MTA, it doesn't rely upon a "piped open" to a program like sendmail -- a security hole that is never opened is pretty darned hard to exploit. (If you don't know what a "piped open" is, don't sweat it.)

   

• Always with an eye toward security, ASForm requires that if it's used with a secure (HTTPS) server, it's invoked with the request method POST. If you try to use a GET in a secure environment, ASForm will not cooperate -- thereby keeping sensitive user information out of the browser cache and out of the URL in the location bar where it can be snooped very easily.

  As noted above, if ASForm discovers that it came from a file that is writable by the server, it will only return error messages -- and it will send an email to the webmaster(s) named in the configuration file telling how to fix the insecure installation. In debug mode, it will only return a message indicating the problem and how to fix it, and will refuse to complete the debug run.

   

• Error messages returned to the internet user are customizable. You can specify the background image and/or color, text and link colors, etc. You may provide a header and/or footer for the error messages generated by ASForm to provide a consistent presentation with the rest of your site. The error message is presented in a table set to a width of 65%, placed after your error header and before your error footer. Key elements of the error message are highlighted in a color that you can define, to call the user's attention to them.

   

• A configurable referrers filter, once configured, ensures that only your site can invoke ASForm. Optionally, you can choose to accept or reject any transaction that does not indicate the URL of the referring page. Also optionally (on by default), you can choose to have the webmaster(s) mailed an Abuse Report if a transaction is rejected on the basis of a non-null (defined) value of HTTP_REFERER. Although it is not so difficult to spoof the value of HTTP_REFERER, there is really no point in trying to abuse ASForm -- it doesn't accept email addresses from the web except for that used by the Autoresponder. Every invocation of ASForm results in a message to one of your named recipients -- hardly a spammer's delight. Of course your form can accept any number of email addresses you care to ask for, but only one is used to send the Autoresponder message, and the recipients of form submission reports are identified in your configuration file(s).

  ASForm knows without your telling it the name of the server (or virtual host) it is installed on, and will not cooperate with any hosts outside of its own domain. You can configure the filter to work with any host in your domain, and then with referrers from only certain directories within each host's file system. Although it is very flexible and powerful, the configuration of the filter is straightforward.

   

• If ASForm is misconfigured or encounters a fatal error, it sends an email message to the webmaster (named in the configuration file) explaining what went wrong and how to correct it. In conjunction with debug mode, this is a very powerful combination that is designed to take the guesswork out of making the application run properly.

   

• To support email sorting software, you can specify another address for ASForm to use as a From: address in email to form submission report recipients that is different that that used to mail to Autoresponder recipients. This is also useful if you want bounced form reports to be delivered to a different account than that of bounced Autoresponder messages.

   

• You can have as many configuration files as you care to write, so you install one copy of ASForm and can then configure it to behave differently for your different needs. Every configuration parameter can be overridden by an alternate "named" configuration -- you can even use different SMTP (mail) servers depending upon which configuration is used. All it takes to enable a named configuration is to mention it in the default configuration file, and then to identify it using an input (that may be a hidden input) in your HTML form.

   

• Finally, ASForm, as mentioned before, comes with a built-in debugging utility designed to make testing configuration files quick and easy. The debugging utility is turned on and off by changing a configuration variable's argument from "off" to "on" and running ASForm. ASForm then tests each of the parameters in a configuration file, including the availability of the SMTP server and its acceptance of your named recipients' addresses by it. Anything that might make ASForm behave in a way other than what it appears you intended is flagged and explained in English as plain as possible. The majority of the debugging portion of the software is kept in a file external to the main program to eliminate as much overhead from the normal operation as possible -- the code is only loaded as it is needed. Some of the debugging code is embedded within the main program out of necessity, but is bypassed if debugging is not enabled.

With all of these features, ASForm is a big dude, but it ought to do what you want done, and without any guesswork or frustrating debugging as so often is required when deploying free CGI applications. If you're reading this because you have downloaded your own copy of ASForm, I hope you find it easy to deploy and powerful enough to meet your needs. Enjoy!

© 1999 - Art Sackett