ARK E-Mail Server Interface Documentation
The ARK E-mail Server provides a facility for submitting ARK forms
via e-mail. It is an automated server that provides form verification
and submission using GPG/OpenPGP signatures for authentication.
All messages for the ARK E-mail Server must be sent to
If you have any questions or comments or require assistance with the ARK
E-mail Server, please contact the ARK Help
The e-mail server parses the incoming e-mail based on a very limited set
of commands. The required command keywords are <BEGIN> and <END>
(the server is not case-sensitive). The most commonly used command keywords,
in addition to <BEGIN> and <END>, are <PROJECT=x> and
<OPTION=x> where the value of "x" is supplied by the user.
The e-mail submission service can only be used to submit a new data
record. It cannot be used to modify an existing record. We recommend
that you keep your original submission e-mail in case changes are necessary.
If you do need to change a record you have already submitted, you will need
to use the Web interface. A description of how to modify an existing record
is in the Modifying Existing Data section of the ARK
This section lists specific sets of instructions to carry out the tasks
most commonly required during the form verification and submission process.
The subsequent section lists the complete command
syntax. In all of the examples below, SWIFTBA is specified for the project
name. For users submitting forms for other groups, simply substitute the
appropriate ARK unique group identifier for "SWIFTBA". A user can discover
the group identifier associated with an ARK group by going to the user's
My ARK Web page. The group identifier is listed
inside parentheses after each group name.
- Blank Forms
Users may request a blank ASCII form containing "name:value"
entries. Users may then use any editor to supply the necessary
values for the listed entries. To receive a blank form, send
the following message to the server at the address listed above.
- Form Documentation
Users may request an ASCII text file containing short descriptions of
all of the fields in the form. To obtain this document, send the
following message to the server.
- Form Verification
After the user enters all of the necessary values into the form, s/he
can e-mail this file to the server for verification. Verification will
identify required fields with missing values and incorrect values
(declinations larger than 90 degrees, for example). The form will be
sent back to the user indicating any errors detected. All error
messages are preceded with a ^ to make it easier for users to search
for them. To verify the form, e-mail the completed form to the server.
The following commands should be at the top of the form.
The "name:value" entries must then be listed, followed by an
<END> tag. The order of the entries is not important
and omitted names will be treated as blank.
- Form Submission
Once the user has verified the form, corrected any errors, and is
pleased with the results, the user should submit the form to the ARK
database. The user should use the SUBMIT option. The SUBMIT option will
perform a final verification (as a safety check). If no errors are
found, the form will be e-mailed to the appropriate database address
for that project. If errors were detected, the form is returned with
the errors flagged. To submit, insert the following lines at the top of
the completed form, sign the e-mail using GPG or OpenPGP and send the
result to the server.
The server uses a simple syntax of keywords and name-value pairs. Below
is a description of the ARK server keywords.
- Beginning of message. The remainder of the mail message is processed
until <END> is found or end of mail message file is reached.
This keyword is always required.
- Specifies the project name. If this is the only line in the mail
message, an empty form for the specified project will be returned.
Otherwise, the contents of the mail message will be processed as
the actual form.
- Specifies the option. Valid option keywords are HELP, SUBMIT,
and VERIFY. HELP option will return the help documentation for the
specified project, SUBMIT option will verify and submit the specified
form, and VERIFY option will verify the specified form. VERIFY
option is the default.
- Specifies whether the return message from the ARK e-mail server
should be signed, encrypted, and the method for doing so. Valid
REPLY option keywords are CLEAR_TEXT, ARMOR_SIGN,
ARMOR_SIGN_ENCRYPT, MIME_SIGN, and MIME_SIGN_ENCRYPT. The default is
MIME_SIGN which causes the return e-mail to have a MIME type of
multipart/signed according to the Internet standard RFC 3156. The
ARMOR_* options use the classic PGP ASCII methods for
signing/encrypting. The *_ENCRYPT methods will not work unless the
user's key has been verified and signed by a member of the ARK
team or the user's key is trusted according to the ARK GPG/OpenPGP
Web of Trust. Because of this, please do not use the *_ENCRYPT
methods unless you absolutely need complete privacy.
- Specifies the echo mode. If ON is specified, both user input and
processed results are returned. Otherwise, only the processed
results are returned. OFF is the default.
- <COMMENT=any text>
- Allows the user to specify any comments for their own use. It is
useful for tracking multiple versions of a form. Comment fields are
ignored by the verification system.
- Specifies the beginning of the cover portion of the form. Subsequent
lines are processed as the cover.
- Specifies the beginning of the target portion of the form. Subsequent
lines are processed as the target. Multiple targets may be specified
by beginning each target with this keyword.
- End of message. The remainder of the mail message, if any, is ignored.
This keyword is always required.
In order to submit a form using the ARK E-mail Server, you need to
attach a digital signature to your e-mail. A digital signature is an
electronic signature that is used to authenticate the identity of the sender
of the e-mail and to ensure that the original content of the message that has
been sent is unchanged when it is received. A digital signature can be used
with any kind of e-mail, whether it is encrypted or not. The ARK team
recommends GPG (GNU Privacy Guard, also
known as GnuPG), which is Free Software. PGP 6.5.x and higher have also been
successfully tested. Older versions of PGP may not fully work since they are
not compliant with the OpenPGP architecture. For example, PGP 2.6.2's ASCII
"clearsign" signature method ("
pgp -sat") is known to work, but
its public key encryption does not work with the ARK E-mail Server.
Detailed information on how to get started with GPG can be found at
Users should familiarize themselves with the GPG documentation before
starting. If you haven't used GPG before, you'll first need to generate your
public and secret keys, your revocation certificate, and upload your public
key to one of the public keyservers such as subkeys.pgp.net or pgp.mit.edu.
On many Unix-compatible systems the following steps apply:
Create the ~/.gnupg directory. If you have ever run the gpg command
before, this step may be unnecessary.
Generate your public and secret keys.
When you enter this command, GPG will ask a series of questions. For those
that have a default, select the default by simply pressing Return. Our
recommended responses are indicated in italics.
Please select what kind of key you want:
(1) DSA and ElGamal (default)
(2) DSA (sign only)
(5) RSA (sign only)
Your selection? 1
DSA keypair will have 1024 bits.
About to generate a new ELG-E keypair.
minimum keysize is 768 bits
default keysize is 1024 bits
highest suggested keysize is 2048 bits
What keysize do you want? (1024)
Requested keysize is 1024 bits
Please specify how long the key should be valid.
0 = key does not expire
<n> = key expires in n days
<n>w = key expires in n weeks
<n>m = key expires in n months
<n>y = key expires in n years
Key is valid for? 0
Key does not expire at all
Is this correct (y/n)? y
You need a User-ID to identify your key; the software constructs the user id
from Real Name, Comment and Email Address in this form:
"Heinrich Heine (Der Dichter) <firstname.lastname@example.org>"
Real name: Your Name Here
Email address: email@example.com
You selected this USER-ID:
"Your Name Here <firstname.lastname@example.org>"
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
You need a Passphrase to protect your secret key.
Enter passphrase: enter your passphrase here
Repeat passphrase: enter your passphrase again
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
At this stage, type random characters on the keyboard
public and secret key created and signed.
key marked as ultimately trusted.
pub 1024D/B5BDF007 2004-06-28 Your Name Here <email@example.com>
Key fingerprint = 1234 5678 9ABC DEF0 1234 5678 9ABC DEF0 1234 5678
sub 1024g/DB544C9B 2004-06-28
Copy the 50-character string of hexadecimal digits and spaces from the
output of gpg that follows "Key fingerprint = " and then paste it into the
"GPG/OpenPGP Key Fingerprint" field of your
ARK user profile and submit. Now,
whenever you send a signed e-mail to the ARK E-mail Server, ARK will be
able to associate your digital signature with your ARK account.
If you have an existing key and need to retrieve the fingerprint
of your key for adding to your ARK user profile, run the following
gpg --fingerprint $LOGNAME
If you have multiple keys associated with your login name or if you are
using a non-Unix platform, you may need to enter the complete e-mail address
you specified when you generated your key in place of $LOGNAME.
Now, upload your public key to a public keyserver, such as
subkeys.pgp.net or pgp.mit.edu:
gpg --keyserver subkeys.pgp.net --send-keys $LOGNAME
Although at this point everything should be in place to allow you to
submit data to ARK via e-mail, we recommend that you generate a revocation
certificate. If you ever forget your passphrase or lose your secret key, this
will allow you to revoke your public key and start over by generating a new
gpg --gen-revoke $LOGNAME
After you enter that command, you will be asked several questions. The
procedure for generating a revocation certificate is as follows:
sec 1024D/12345ABC 2004-06-28 Your Name Here <firstname.lastname@example.org>
Create a revocation certificate for this key? y
Please select the reason for the revocation:
0 = No reason specified
1 = Key has been compromised
2 = Key is superseded
3 = Key is no longer used
Q = Cancel
(Probably you want to select 1 here)
Your decision? 0
Enter an optional description; end it with an empty line:
>just press Return
Reason for revocation: No reason specified
(No description given)
Is this okay? y
You need a passphrase to unlock the secret key for
user: "Your Name Here <email@example.com>"
1024-bit DSA key, ID 12345ABC, created 2004-06-28
Enter passphrase: enter your passphrase here
ASCII armored output forced.
Revocation certificate created.
Please move it to a medium which you can hide away; if Mallory gets
access to this certificate he can use it to make your key unusable.
It is smart to print this certificate and store it away, just in case
your media become unreadable. But have some caution: The print system of
your machine might store the data and make it available to others!
Print the key block and/or store it in a text file, but keep it secret,
keep it safe. Consult the GPG documentation for instructions on how to use
the revocation certificate to revoke your public key should the need
Users interested in encrypting messages to the ARK E-mail Server or
verifying the digital signatures of the responses from the ARK E-mail
Server can obtain the ARK E-mail Server's GPG/OpenPGP public key in either
of the two following ways:
After the ARK public key has been added to your public keyring, you
should verify the fingerprint of the public key using the following command:
gpg --fingerprint firstname.lastname@example.org
Here is the fingerprint of the ARK public key:
4B15 6DEA BDCE E2F6 F718 943F 268B 6246 B60C A966
After verifying the fingerprint, you should sign it locally:
gpg --lsign-key email@example.com
You now have the ability to send encrypted e-mails to the ARK E-mail
Server. However, as noted above, your public key will not be trusted and
decryption will fail unless your public key has been verified and signed by a
member of the ARK team (contact the ARK Help
Desk). Alternatively, if your public key has already been signed by a
large number of people, it may be possible your key is trusted automatically
according to the ARK GPG/OpenPGP "Web of Trust." In any case, encryption is
not recommended for usage with the ARK E-mail Server unless one absolutely
needs complete privacy.
If the Mutt Compose menu (i.e. the screen from which you press 'y' to send a
message) has a 'PGP:' line your local mutt has already
been configured for PGP signing and encrypting.
If this is not the case, find the 'gpg.rc' file installed alongside the
Mutt documentation on your system. For example:
and add a line to your ~/.muttrc to source this file:
Alternatively, the contents of this file can be appended to your
Now, from the Compose menu, press 'p' then 's' to sign your mail message
before sending to the ARK E-mail Server. To sign all your mail, insert the
following line in your .muttrc:
pgp_autosign = yes
When you send a message (Control-X from the COMPOSE MESSAGE screen)
if the 'Send message' prompt in Pine, looks like this:
Send message (unfiltered)?
Press control-N to cycle through the available filters. If you see
gpg-sign, Pine is already configured to sign messages.
If this is not the case, execute the following from the command line:
This script will modify your .pinerc to add gpg-sign support.
If, however, this script is unavailable, modify your ~/.pinerc to
contain lines similar to the following:
# This variable takes a list of programs that message text is piped into
# after MIME decoding, prior to display.
display-filters=_LEADING("-----BEGIN PGP MESSAGE-----")_ /usr/bin/gpg-check,
_LEADING("-----BEGIN PGP SIGNED MESSAGE-----")_ /usr/bin/gpg-check
# This defines a program that message text is piped into before MIME
# encoding, prior to sending
/usr/bin/gpg-encrypt _RECIPIENTS_ firstname.lastname@example.org,
/usr/bin/gpg-sign+encrypt _RECIPIENTS_ email@example.com
After restarting pine, sign a message to the ARK E-mail Server by
pressing control-N at the 'Send message (unfiltered)?' prompt until
gpg-sign appears, and then pressing 'y'.
To make gpg-sign the default filter option, select
compose-send-offers-first-filter from the Setup/Config menu.
To use the Mail program that is installed with Mac OS X, the
must be installed.
Check the "PGP Signed" checkbox to sign a message to the ARK E-mail
Install the Enigmail extension. If browsing with Mozilla, this is a simple matter of pressing the appropriate Install button on the linked page. For Thunderbird, save the appropriate '.xpi' file from the linked page. Choose 'Tools/Extensions' from the Thunderbird menu. Press the 'Install' button, and then select the '.xpi' file. Exit Thunderbird and restart the application.
Sign a message by choosing 'Enigmail/Sign Message' from the menu when composing a message.