STAMP - Secure, Template-Aware Mail Processor
$Revision: 1.9 $
$Date: 2001/10/01 21:09:40 $
STAMP is a secure, generic HTML form mailer written in Perl. It is easy to set up and provides security against your system being used as a spam gateway. STAMP also lets you customize generated email submissions using templates, and provides optional PGP encryption of email messages.
STAMP provides secure form processing and email generation, and supports using templates to control and customize the generated email message. It is more secure than the standard FormMail script because it relies on a server-side configuration file to set the recipient and subject of an email message; this makes it impossible for spammers to use your mail processing system as a spam gateway.
STAMP also allows you to PGP-encrypt all messages sent through the system. This functionality requires that you have the Crypt::OpenPGP module installed on your server; Crypt::OpenPGP provides a pure-Perl implementation of the OpenPGP standard, and is compatible with all PGP implementations (PGP, GnuPG, etc.).
STAMP provides many configuration options to customize the appearance of the email messages it generates. Foremost among these options is the ability to use user-defined templates to control the appearance. These templates act like form letters, in that they contain hooks to insert the values of the fields on your form.
STAMP uses server-side configuration files with hard-coded recipient and subject values to provide security against spammers. In addition to those fields, configuration files are used to set many other form-specific options.
The configuration file has the following format:
Empty lines and lines starting with # are comments.
All other lines are of the format keyword arguments. Possible keywords are:
Delimits the configuration section for one form; the following declarations, up to the next Form keyword, will be applied to the form name given after the keyword. The form name must exactly match the _form value (from your HTML form).
To include configuration settings for multiple forms in one config file, use the Form keyword to start each section. For example:
Form foo
To foo@bar.com
Redirect http://www.foo.com/
Form bar
To bar@bar.com
Redirect http://www.bar.com/
The indentation is not required, but it can be helpful in providing visual cues as to which settings apply to which form.
Specifies the email address of the recipient(s) of this form
submission. You can use either Recipient or To. Multiple recipients can be specified by separating the email addresses
with commas (,).
This keyword is required for each form.
Specifies the URL of the page to which the user will be redirected after submitting the form. This should be an absolute URL.
This keyword is required for each form.
Specifies the subject of the email message containing the form submission.
This keyword is optional; the default is WWW Form Submission, though this may change in the future.
A comma-separated list of required fields on your form; if any of these fields are not filled out, the user will get an error.
This keyword is optional.
A comma-separated list of valid referrers. If present, the referrer (the
HTTP_REFERER environment variable) will be checked against each of these; if it does not
match, the user will get an error.
NOTE that a referrer can be forged relatively easily, so you should rely on this only as a first measure of security.
This keyword is optional.
The filesystem path to an HTML::Template template, from which the form submission email message will be generated.
This keyword is optional. If not specified, the email message will simply be a dump of the form fields and their values.
Specifies a sort order for the form fields to appear in the form submission email message. This option only applies if you have not specified a MailTemplate for this form.
The argument for Sort can be either alphabetical, which will sort the field names alphabetically; or you can use a custom
sorting order by listing the field names in the order in which you'd like
them to appear, separated by commas, and prefixed by order:. For example:
Sort order:foo,bar,baz
This keyword is optional. If not specified, the form fields will be in an undefined order; generally, this order is the order in which they appeared in the form, but you should not count on this.
By default, when not using a mail template (MailTemplate, above), blank form fields will be omitted from the email message. You can force their inclusion by setting this option to 1:
PrintBlankFields 1
This keyword is optional; the default is to exclude blank fields.
Turns on encryption for STAMP email messages. If set, the value for this option should be either the key ID or the email address of the intended recipient; this will be used to look up the recipient's public key in the public keyring. That public key will then be used to encrypt the message.
Obviously, if you wish to be able to decrypt the message, the value for EncryptKey should be the key ID or email address for your public key.
Note that encryption requires that your server have Crypt::OpenPGP installed; this module is available on CPAN (http://www.cpan.org/).
Note also that if you supply the EncryptKey parameter, you must also supply the EncryptPublicKeyRing and EncryptCompat options.
This keyword is optional; the default is no encryption.
If using encryption (see EncryptKey, above), specifies the path to your public keyring, or your exported public key. All PGP applications allow you to export your key; you can export it in either ASCII-armoured text, or plain binary format. STAMP will understand either format.
You could also simply set the path to your entire public keyring. This is not advised, however, as it will slow down STAMP, because STAMP must then look through all of the keys in your public keyring until it finds the key for the intended recipient.
This keyword is required if using encryption, ignored otherwise.
If using encryption (see EncryptKey, above), specifies the compatibility mode for encryption. STAMP (or, rather, Crypt::OpenPGP, which STAMP
uses for all PGP functionality) is compatible with all PGP implementations
that support the OpenPGP standard. The compatibility mode gives hints to
Crypt::OpenPGP as to which symmetric cipher to use, which compression algorithm to use,
etc. The value for EncryptCompat should be one of the following strings: GnuPG, PGP2, or PGP5. You should set the value to the PGP implementation that you will use for
decrypting the messages; note that if you are using a version of PGP
greater than 5, just set this value to PGP5.
This keyword is required if using encryption, ignored otherwise.
Specifies the method by which you'd like the email message to be sent.
Possible values are: sendmail, to send through the Unix sendmail
program; smtp, to send through an SMTP server (see SMTPServer, below); and mail, to send through the Unix mail program.
This keyword is optional; the default method used is sendmail.
If you select a transfer method of smtp, you may also need to set the address of your SMTP server.
This keyword is optional; the default server used is localhost.
To set up encryption of all messages sent through STAMP, you must first ensure that your server has Crypt::OpenPGP installed. Talk to your system administrators if you're not sure.
Once you know that Crypt::OpenPGP is installed, follow these instructions to set up encryption:
Export your PGP public key. You should not include the private/secret key part of your key; only the public part is required.
Upload the exported key to your webserver, and take not of the location where you uploaded it.
Open your STAMP configuration file.
Add an EncryptKey directive, specifying the email address associated with the public key that you exported--this is probably your personal email address. For example:
EncryptKey foo@bar.com
Add an EncryptPublicKeyRing directive, specifying the path to the exported key you uploaded in Step 2. For example:
EncryptPublicKeyRing /path/to/key.asc
Add an EncryptCompat directive, specifying the compatibility mode for the encryption; this should correspond to the PGP implementation that you will be using to decrypt encrypted STAMP messages. Take a look at the documentation for EncryptCompat, above, for a list of possible values. For example:
EncryptCompat PGP2
That's it, you're done! All mail sent through the particular STAMP form for which you set up encryption will now be encrypted.
A mail template for email generation might look like this:
Hi,
This is an automated message generated from a form
submission on your web site. The form was submitted
by <TMPL_VAR NAME="fname"> <TMPL_VAR NAME="lname">, who
is interested in the <TMPL_VAR NAME="interest"> aspect
of your business.
Here is the information posted through the form:
First Name <TMPL_VAR NAME="fname">
Last Name <TMPL_VAR NAME="lname">
Age <TMPL_VAR NAME="age">
Phone Number <TMPL_VAR NAME="phone">
Email Address <TMPL_VAR NAME="email">
Please contact this person as soon as possible.
In the above examples, the labels like fname, lname, etc. should match the labels for the fields in your form. The <TMPL_VAR NAME=``foo''>
statements will be completely replaced by the values of those fields, when
the form is submitted. For example, if you have a form field called age:
<input name="age" size="3">
and a user fills in the value 56, the Age line above will read
Age 56
To use STAMP, your HTML form must contain a field called _form; this will generally be a hidden input field, and it tells STAMP which form was submitted, so that it can pull the necessary information out of the configuration file.
The _form field might look like this:
<input type="hidden" name="_form" value="form1">
In addition, if you'd like the From address of the generated email message to contain the user's email address, you should create an email field in your form for the user to fill in:
<input name="email">
The value of this field will be used as the From address.
Benjamin Trott, ben@rhumba.pair.com
Except where otherwise noted, STAMP is Copyright (c) 2001, Benjamin Trott. All rights reserved. STAMP is free software; you may redistribute it and/or modify it under the same terms as Perl itself.