PGPform FAQ

What is pgpform?

pgpform is a simple CGI (Common Gateway Interface) script which Vineyard.NET customers can use to accept information from an HTML form in a reasonably secure fashion.

When you are accepting sensitive data (e.g. credit card numbers) from clients on the Internet, you want to make sure that the sensitive info cannot be viewed at any stage of the path from the client to your desk. Using SSL to encrypt the data from the client's desk to VNI's server (while critical) does not protect the entire path. By the time the data finally gets to your web site, it is clear text (unencrypted) again (our web server has to unencrypt the data so your form can do something with it). You need to further encrypt the data before you move it the rest of the way to your desk. pgpform is one way to provide the rest of the needed encryption.

pgpform attempts to be easy to use and as generic as possible. However, some of this may prove daunting to folk who are less technically inclined. In which case it is appropriate to make use of the expertise of a Vineyard.NET Reseller for assistance.

About pgp

Pretty Good Privacy (commonly known as pgp) is a robust method of encryption used to secure files and communications from unauthorized viewing. Phil Zimmerman wrote the program and up until late 1994 all his work was available in the public domain and free for use by all. Mr. Zimmerman started a commercial company, PGP Corporation, which provides commercial versions of pgp.

There are a number of free versions of pgp available. Mr. Zimmerman's original work is still available and is known as PGP2. It is still considered to be quite secure; but it uses the idea encryption algorithm and as such, you have to get a license from the patent holder for commercial use. There are more recent versions also available at pgpi.org. The good folks at GNU have their own version of pgp known as GnuPG or gpg.

VNI currently recommends using the email program Thunderbird with the Thunderbird extension Enigmail and GnuPG. This combination works on both Windows and Mac OSX as well as the BSD and Linux systems. The Enigmail folks have written some good install instructions.

A thorough discussion of pgp is beyond the scope of this FAQ.

Setting up your account for pgpform

Before pgpform will work for your site, you need to set up a few things.

pgp needs to be able to find your public encryption key.

By default, if you choose to use GnuPG this is found in a file (your public keyring) named pubring.gpg in a special directory, .gnugp, in your home directory. If you would rather keep it somewhere else, you need to specify to pgpform by passing in the parameter pgppubring with a pathname to the directory containing your public key ring. More on passing parameters is written below.

If you are prefer to use an older version of pgp, the public file may have a different name. e.g.: version 2.6 looks for .pgp/pubring.pgp.

pgpform can save an archival copy of your message.

If you specify, pgpform will attempt to save a copy of your e-mail in your home directory. This is done on the presumption that anything you feel is important enough to encrypt is probably important enough to archive. Bear in mind that this will build up over time; and may start to consume appreciable disk space. If you choose to archive copies, pgpform will create a directory called pgparchive in your home directory.

Setting up your HTML form for pgpform

pgpform will require an SSL connection (it fails with an error message if an attempt is made to use it without SSL).

Your form tag needs to specify pgpform as action with the post method as follows:

<Form method="post" action="https://www.vineyard.net/cgi-bin/pgpform">

If you have arranged with Vineyard.NET to use your own SSL certificate, you can substitute your host name for www.vineyard.net. However, if you have not purchased a certificate of authentication (even if you have your own domain running at Vineyard.NET), attempting to substitute your own host for the one we have listed in our certificate will cause an error in most browsers. You can purchase a certificate from a number of different companies. Vineyard.NET is an OpenSRS reseller.

You will need to pass parameters into pgpform. All parameters passed into pgpform which it does not recognize as instructions to itself will be collated into a list and sent to you in the encrypted e-mail message. Control options intended to modify the behavior of pgpform are best passed as hidden items, e.g.:

<input type=“hidden” name=“pgpuser” value=“username”>
<input type=“hidden” name=“pgptitle” value=“PhredsForm”>
<input type=“hidden” name=“pgpsort” value=“1”>

There are several control options. All are listed here. The first one, pgpuser is required. All options begin with the characters pgp. All parameters beginning with the characters pgp are reserved for future use (if you use such a spelling, it will not be included in your collated report).

pgpuser=username

Required. pgpuser should be a valid Vineyard.NET account name. It is used to determine the recipient's e-mail address, and to find the customer's home directory.

pgpemail=e-mail address

Optional. The final pgp encrypted message will be mailed to this address instead of the default pgpuser@vineyard.net.

pgpsuccessurl=Closing web page

Optional. After the encrypted message is sent, the user needs a little feedback. If you don't specify this parameter, pgpform will generate a simple page which says something polite about the message being sent. If you create your own response page, you can specify with this parameter.

pgptitle=title

Optional. pgptitle is an identifier for your own use. If you use more than one form, you can give each of them different titles to help you distinguish between them. pgptitle is added in clear text to each of the e-mail messages, and also used to name your archival copy. Unless specified otherwise, the value of pgpuser will be used as your title.

pgparchive=1

Optional. pgparchive specifies to pgpform that it should save an archival copy of the encrypted message.

pgpsort=1

Optional. pgpform will list your form items in the same order presented to it by the customer's browser. Most browsers do return form items in the same order that you write them in your HTML, but this is not specified in the protocol and not all browsers make this effort. If it is important for you to consistently see your items in a fixed order, you can pass in an optional parameter, pgpsort=1, which will cause pgpform to collate your items in alphabetical order.