Introduction

The Astrophysics Research Knowledgebase (ARK) is a service provided by NASA's High Energy Astrophysics Science Archive Research Center (HEASARC). ARK provides a Web interface to submit and search information stored in a database. Registration is required to access the service. Users are given permissions to submit and/or search specific tables in the database based on their needs.

The service is located on the Web at

http://heasarc.gsfc.nasa.gov/ark/

Registration and Login

Invitation Request

Only registered users can access ARK. The registration process is initiated through an invitation sent to your e-mail address by an ARK administrator. To request an invitation, go the following link:

http://heasarc.gsfc.nasa.gov/ark/help/?subject=Account+Request

Enter your e-mail address in the top field and the request in the comment field, then press submit.

Your request will be reviewed by an ARK administrator and if it is accepted, you will receive an invitation e-mail containing a unique registration link. You may receive an e-mail with further questions regarding your account privileges before an invitation is sent.

The invitation contains a unique link which must be visited to begin the registration process. The invitation expires after thirty days. If you do not register while the invitation is valid, request another invitation.

 

Registration

Upon visiting the link from the invitation e-mail, the registration form is presented.

Fill in your contact information. Fields marked with an asterisk are required. Most of the fields are self-explanatory, however, field-specific help is accessed by clicking the text label of each field.

Once you are registered under a particular user id, it cannot be changed. All the data records you submit as an ARK user will be tagged with this user id.

Please make an effort to find your institution in the Institution selection list. If you enter an alternate spelling of your institution in the field, it may impact the usefulness of your account.

The "GPG/OpenPGP Key Fingerprint" field is only needed when data is submitted via e-mail. If you have a public key you may enter its fingerprint here, however, it is ok to leave this field blank and update it when necessary.

The checkbox at the bottom of the form labeled, "Please send an e-mail receipt to me for every data record I submit" is selected by default. If you do not wish to receive e-mail confirmation of your data entry, deselect the checkbox.

After completing the form, press the "Register" button.

If there is a problem upon submission, an error message will be printed followed by the registration form. Possible errors include: failing to enter a required field, entering a user id that has already been registered, and entering a password that is not at least 6 characters and does not contain at least one letter and either one number or symbol. Edit the form to correct the error and re-submit. Note: The "Password" and "Verify Password" fields must be entered again as their values are not retained.

The e-mail address to which your invitation was delivered is automatically associated with your account, however, it may be modified through Edit Profile.

Login

Once you have successfully registered an ARK account, you can access the service by logging into it. On the right side of the ARK home page is a login box.

Enter your user id and password. Then, press the 'Login' button.

Upon login, a session cookie is sent to your browser. ARK requires your browser to accept this cookie, otherwise you cannot use the service. Note, a session cookie only exists for the current browser session. If you exit your browser, the cookie is forgotten. If you leave your browser running, the cookie is still only valid for a 24 hour period from the moment you initially logged in.

Once logged in, several new buttons will appear in the ARK button bar:

To log out, deleting your ARK cookie, press the "Logout" button at the far right. We recommend that you logout when you are finished using ARK.

The remaining buttons are discussed later in this manual: Edit Profile, Change Password, My ARK.

Password Reset

If you have forgotten your password, select the "Forgot Password?" link at the bottom of the login box. From the Password Reset page, enter your user id and press "Submit" Your password will be reset and the new password will be mailed to the e-mail address associated with your account. Upon receipt of the e-mail, login with your new password and visit the Change Password page as soon as possible.

Request User ID

If you have forgotten your user id, select the "Forgot User ID?" link at the bottom of the login box. From the Request User Id page, enter the e-mail address that is associated with your account and press "Submit" A message containing your user id(s) will be mailed to the e-mail address associated with your account.

Edit Profile

If your contact information, such as phone, address, e-mail, etc., has changed or requires correcting, select the "Edit Profile" button while logged into ARK. The Edit Profile form will be presented:

The form should be familiar as it differs only slightly from the registration form. For example, your user id cannot be changed once you have registered. The e-mail to which your initial invitation was sent is associated with your account at registration, however, once registered it can be changed via the "Edit Profile" form. Also, changing your password is not available on this form, but rather through the "Change Password" button.

After editing the appropriate fields, press the "Update" button. If there is an error during the update process, the error message will be printed followed by the form with the values you recently submitted. Correct the error and re-submit.

Change Password

In order to change the password associated with your ARK account, select the "Change Password" button while logged into ARK. The Change Password form will be presented:

Enter the existing password for the account, then the new password twice for verification, and press the "Change" button. If there is an problem, an error message will be printed followed by the form. Possible errors include: incorrect existing password, mismatch between the new password and its confirmation, or the new password is not at least 6 characters and contains at least one letter and either one number or one symbol. Based on the error message, fill out the form again, and re-submit.

My ARK

Upon login from the ARK home page or selection of the "My ARK" button while logged in, the My ARK page is presented:

The page contains a list of links to the ARK groups of which you are a member. The format of each item in the list is "Group Name (GROUPID)" where "Group Name" is a description of the group and "GROUPID" is the short name identifier for the group. When submitting data via e-mail the short name is used.

From the list select the link for the group with which you are concerned. You will have the opportunity to search and/or contribute data to the group.

Selection/Search Page

Upon selection of a group, you will be presented with the group's page:

The top portion of the page is concerned with the management of data records contributed by you, while the bottom portion is used to find data records within the entire group. If the selected group is a read-only group, only the bottom search section will be presented.

 

Enter New Data

The topmost link, "Enter New Data," leads to the group's form with nothing pre-filled.

See Submission Form for instructions on using the form.

 

Modify Existing Data

If you have entered data into this group in the last month, a table listing the default parameters for each recently entered record is presented:

Under the recent activity table, select the "Show all records" link to display all the active records you have submitted to this group. To return to the default view of the last month of records, select the "Show only recent records" link. The table can be reordered by selecting an arrow icon in any column header. Selecting a down arrow causes the table to be sorted by that column in ascending order (increasing from top to bottom), while an up arrow sorts in descending order (increasing from bottom to top). The leftmost button associated with each record, View, lists all the parameters for that particular record when selected.

An existing record can be only modified or deleted by the user that inserted that record in ARK. A different user can add similar information by creating a new record. For example, if User A inserted information regarding a source X, indexed by ARK with a specific record number, User B cannot modify that record number but can enter a new record on source X. If User A wants to modify or amend his record on source X via the ARK e-mail server they have first to delete record via the web interface. Otherwise the database will contain two records on source X from User A with old or partial information in each of the records.

However if the database has restriction such that records have to be unique in one of the parameters, before making an update via the ARK e-mail server the user has to discard that record via the web interface first. Using the previous example, if the database has to contain only one record on source X, only the User A can update or delete that record and no other record from different users on source X will be allowed. If the update occurs via e-mail, User A has to first delete the record via the web on source X and after has to re-submit the e-mail. If the record is not discarded the user A will get an error message when submitting the e-mail.

When the Modify button associated with a particular record is selected, the group's form is presented with values pre-filled from the existing record. Upon successful submission the original record is discarded, replaced by the new entry.

See Submission Form for instructions on using the form.

Discard Existing Record

The rightmost button, Discard, is used to discard the record with which it is associated. Upon selection, a confirmation box is presented (provided your browser supports javascript).

If the OK button is selected, the record is marked as discarded and unavailable to future searches or modification. To avoid discarding the record, select the Cancel button.

Search

The parameters available in the search box varies based on the group, however, all group search boxes share a similar interface. In general a small number of search fields are provided for those parameters which are anticipated to be commonly searched.

Fields that are left blank are ignored. If multiple fields are filled, all parameters much match in a record to be returned in the search results.

 

If a desired parameter is not present in the standard search box, selecting the "Advanced Search" link will present a standard Browse interface for searching any parameter in the group table.

Select the View checkboxes to the left of the parameter names that are to be displayed in the results. The parameter names are linked to help on that particular parameter. Data may be exported for plotting or other analysis by changing the Output Format. For example, upon selecting Excel-compatible and initiating the search, a file usable in Microsoft Excel will be returned. Note, however, that there is a 256 column limit in Excel, so if more than 256 parameters are selected there will be data loss in the exported file.

 

Once submitted, the search results are presented in a format, which is familiar to users of Browse.

When finished viewing the results, use your browser's Back button or select the "Return to ARK" link to return to the current group's page. The data that is currently being displayed may be redisplayed in a different format, by selecting a format and pressing the Redisplay button. This capability is identical to the the Output Format option of the Advanced Search page.

Submission Form

After choosing to enter new data or modify existing data from the group page, you are presented with a group form.

Every group form has different data inputs, however, all forms share a familiar interface. The triangles preceding header text denote collapsible sections. If a triangle pointing to the right is selected, the contents of the section are revealed. If a triangle pointing down is selected, the contents are hidden.

Special group forms can have numbered sections that represent individual targets, observations, etc. Such numbered sections have additional control elements to manage section addition, duplication, deletion and re-ordering.

Immediately below the collapsible header of a multiple section form are two 'Add' buttons, one for adding new blank sections and one for cloning existing sections. When the button associated with "Add New Observation" is pressed, a blank observation is added to the end of the form. Cloning (i.e. duplicating or copying) an observation involves the selection of the number of the observation to be duplicated from the popup list and pressing the associated "Add" button. A new observation will be added to the end of the form with the contents copied from the original observation.

Immediately below the collapsible header for a numbered instance of a multiple section form are two toggles allowing you to delete or move that particular numbered section. In order to delete observations, change the "Do you want to delete this observation?" menu from 'N' to 'Y'. Upon pressing 'Verify' or any button in the form, the observations that have been set to 'Y' will be removed. Observations may also be re-ordered by changing the "Move this observation" toggle to a new position and pressing 'Verify' or any other button in the form. The final order will follow the move toggles that have been set with unspecified positions being filled based on the original order. For example, if you start out with five observations and set observation number three's move menu to 1, the new order will be 3, 1, 2, 4, and 5. Observation 3 will become the new number 1, 1 will be the new number 2 and so on. If multiple observations are requested to move to the same position onlythe first request will be honored. If there is only one observation, no move toggle will appear. Depending on the form, an observation may go by target or some other term.

 

Verify

Once the form is filled out, press the Verify button. Note there are identical "Verify" buttons at the top and bottom of the form.

If there are no problems, a "Form verified successfully" message will be printed above the form and the Submit button will appear next to the Verify button.

 

If, however, there are issues with the data entered, such as missing required fields or incorrect data formatting (e.g. characters entered in number fields), the errors will be listed before the form.

The error messages include the name of the field and the problem with that field separated by a colon. Correct the issue and press the Verify button. Continue this process until the form is successfully verified.

 

Submit

Once the form has been verified, press the Submit button. The form will be shown again with all the fields visible, but unchangeable.

If you have selected the "Please send an e-mail receipt to me for every data record I submit" checkbox in your account profile, an e-mail will be sent to you listing the information you have submitted. Note that the receipt is for informational purposes only. Its format is incompatible with submission via e-mail.

Selecting the "Return to Recent Activity" link will send you to the selection/search page. Your newly entered record should be at the top of the list.

Save and Reload

Although previously submitted records can be modified, you may still wish to save a partially completed form for later input.

After you have filled the form to the extent that you wish to in this session, press the 'Save' button. In most browsers, a dialog box will be presented so that you may indicate what to do with the saved form. Choose the option to save it to disk. Depending on your settings, some browsers will download the file directly into a designated folder as soon as the ARK "Save" button is pressed. The saved form is a text file containing each field in the form paired with the value you entered. This format is compatible with e-mail submission.

To resume filling out a previously saved form, press the "Reload" button. A new page containing a "Load File" input field will appear:

Select the file to be loaded. In most browsers this involves pressing the "Browse..." button, although there are variations such as "Choose File". Once the file has been selected, press the "Submit" button. The values from the ARK saved form will fill the input form.

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