General Description

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

• ark@heasarc.gsfc.nasa.gov

If you have any questions or comments or require assistance with the ARK E-mail Server, please contact the ARK Help Desk.

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 User Guide.

Instructions to Carry out Specific Tasks

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.

1. 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.

         <BEGIN>
         <PROJECT=SWIFTBA>
         <END>

2. 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.

         <BEGIN>
         <PROJECT=SWIFTBA>
         <OPTION=HELP>
         <END>

3. 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.

         <BEGIN>
         <PROJECT=SWIFTBA>
         <OPTION=VERIFY>

   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.
4. 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.

         <BEGIN>
         <PROJECT=SWIFTBA>
         <OPTION=SUBMIT>

ARK E-mail Server Syntax

The server uses a simple syntax of keywords and name-value pairs. Below is a description of the ARK server keywords.

<BEGIN>

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.

<PROJECT=name>

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.

<OPTION=keyword>

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.

<REPLY=keyword>

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.

<ECHO=ON|OFF>

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.

<COVER>

Specifies the beginning of the cover portion of the form. Subsequent lines are processed as the cover.

<TARGET>

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>

End of message. The remainder of the mail message, if any, is ignored. This keyword is always required.

ARK Authentication Using GPG/OpenPGP Signatures

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

• GPG Installation Instructions for Windows, Mac OS X, and Linux
• GPG How-To
• GPG User Guide
• GPG FAQs

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:

1. Create the ~/.gnupg directory. If you have ever run the gpg command before, this step may be unnecessary.

             gpg

2. Generate your public and secret keys.

             gpg --gen-key

   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) <heinrichh@duesseldorf.de>"
   
   Real name: Your Name Here
   Email address: your@email.address
   Comment:
   You selected this USER-ID:
       "Your Name Here <your@email.address>"
   
   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 <your@email.address>
        Key fingerprint = 1234 5678 9ABC DEF0 1234  5678 9ABC DEF0 1234 5678
   sub  1024g/DB544C9B 2004-06-28
   

3. 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 command:

             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.

4. 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
   

5. 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 one.

             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 <your@email.address>
   
   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 <your@email.address>"
   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 arise.

ARK E-mail Server Public Key

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:

• You can retrieve it from most GPG/OpenPGP public keyservers (e.g., subkeys.pgp.net or pgp.mit.edu):

  gpg --keyserver subkeys.pgp.net --recv-keys B60CA966

• You can download it from the HEASARC directly and import it into your public keyring:

  gpg --import ark-public-key.txt

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 ark@heasarc.gsfc.nasa.gov

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 ark@heasarc.gsfc.nasa.gov

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.

/usr/share/doc/mutt-1.2.5.1/gpg.rc
/usr/doc/mutt/samples/gpg.rc

source /usr/share/doc/mutt-1.2.5.1/gpg.rc

pgp_autosign = yes

Send message (unfiltered)?

pinegpg-install

# 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
sending-filters=/usr/bin/gpg-sign,
        /usr/bin/gpg-encrypt _RECIPIENTS_ your@email.address,
        /usr/bin/gpg-sign+encrypt _RECIPIENTS_ your@email.address