Added esg documentation to generated documentation.

docs/esg.md

@@ -0,0 +1,220 @@
+Accessing ESG Data Through netCDF
+=================================
+
+[Introduction]()
+----------------
+
+It is possible to access Earth Systems Grid (ESG) datasets from ESG
+servers through the netCDF API. This requires building the netCDF
+library with DAP2 protocol support using the "--enable-dap" flag to the
+configure program.
+
+In order to access ESG datasets, however, it is necessary to register as
+a user with ESG and to setup your environment so that proper
+authentication is established between a netCDF client program and the
+ESG data server. Specifically, it is necessary to use what is called
+"client-side keys" to enable this authentication. Normally, when a
+client accesses a server in a secure fashion (using "https"), the server
+provides an authentication certificate to the client. With client-side
+keys, the client must also provide a certificate to the server so that
+the server can know with whom it is communicating.
+
+It is possible to set up the netCDF library to use client-side keys,
+although the process is somewhat complicated. The DAP2 support in netCDF
+uses the *curl* library and it is that underlying library that must be
+properly configured.
+
+[Terminology]()
+---------------
+
+The key elements for client-side keys requires the constructions of two
+"stores" on the client side.
+
+-   Keystore - a repository to hold the client side key.
+-   Truststore - a repository to hold a chain of certificates that can
+    be used to validate the certificate sent by the server to
+    the client.
+
+The server actually has a similar set of stores, but the client need not
+be concerned with those.
+
+[Initial Steps]()
+-----------------
+
+The first step is to obtain authorization from ESG. Note that this
+information may evolve over time, and may be out of date. This
+discussion is in terms of BADC ESG. You will need to substitute the ESG
+site for BADC in the following.
+
+1.  Register at http://badc.nerc.ac.uk/register to obtain access to badc
+    and to obtain an openid, which will looks something like:
+
+        https://ceda.ac.uk/openid/Firstname.Lastname
+
+2.  Ask BADC for access to whatever datasets are of interest.
+3.  Obtain short term credentials at
+    http://grid.ncsa.illinois.edu/myproxy/MyProxyLogon/ You will need to
+    download and run the MyProxyLogon program. This will create a
+    keyfile in, typically, the directory globus. The keyfile will have a
+    name similar to this: x509up\_u13615 The other elements in
+    \~/.globus are certificates to use in validating the certificate
+    your client gets from the server.
+4.  Obtain the program source ImportKey.java from this location:
+    http://www.agentbob.info/agentbob/79-AB.html (read the whole page,
+    it will help you understand the remaining steps).
+
+[Building the KeyStore]()
+-------------------------
+
+You will have to modify the keyfile in the previous step and then create
+a keystore and install the key and a certificate. The commands are
+these:
+
+        openssl pkcs8 -topk8 -nocrypt -in x509up_u13615 -inform PEM -out key.der -outform DER
+
+        openssl x509 -in x509up_u13615 -inform PEM -out cert.der -outform DER
+
+        java -classpath  -Dkeypassword="" -Dkeystore=./ key.der cert.der
+
+Note, the file names "key.der" and "cert.der" can be whatever you
+choose. It is probably best to leave the .der extension, though.
+
+[Building the TrustStore]()
+---------------------------
+
+Building the truststore is a bit tricky because as provided, the
+certificates in "globus" need some massaging. See the script below for
+the details. The primary command is this, which is executed for every
+certificate, c, in globus. It sticks the certificate into the file named
+"truststore"
+
+      keytool -trustcacerts -storepass "password" -v -keystore "truststore"  -importcert -file "${c}"
+
+[Running the C Client]()
+------------------------
+
+The file ".dodsrc" is used to configure curl. This file must reside
+either in the current directory or in your home directory. It has lines
+of the form
+
+-   KEY=VALUE, or
+-   \[http//x.y/\]KEY=VALUE
+
+The first form provides a configuration parameter that applies to all
+DAP2 accesses. The second form only applies to accesses to the server at
+"x.y".
+
+The following keys must be set in ".dodsrc" to support ESG access.
+
+-   HTTP.SSL.VALIDATE=1
+-   HTTP.COOKIEJAR=.dods\_cookies
+-   HTTP.SSL.CERTIFICATE=esgkeystore
+-   HTTP.SSL.KEY=esgkeystore
+-   HTTP.SSL.CAPATH=.globus
+
+For ESG, the HTTP.SSL.CERTIFICATE and HTTP.SSL.KEY entries should have
+same value, which is the file path for the certificate produced by
+MyProxyLogon. The HTTP.SSL.CAPATH entry should be the path to the
+"certificates" directory produced by MyProxyLogon.
+
+[Running the Java Client]()
+---------------------------
+
+If you are using the Java netCDF client, then you need to add some
+parameters to the "java" command. Specifically, add the following flags.
+
+       -Dkeystore="path to keystore file" -Dkeystorepassword="keystore password"
+
+[Script for creating Stores]()
+------------------------------
+
+The following script shows in detail how to actually construct the key
+and trust stores. It is specific to the format of the globus file as it
+was when ESG support was first added. It may have changed since then, in
+which case, you will need to seek some help in fixing this script. It
+would help if you communicated what you changed to the author so this
+document can be updated.
+
+    #!/bin/sh -x
+    KEYSTORE="esgkeystore"
+    TRUSTSTORE="esgtruststore"
+    GLOBUS="globus"
+    TRUSTROOT="certificates"
+    CERT="x509up_u13615"
+    TRUSTROOTPATH="$GLOBUS/$TRUSTROOT"
+    CERTFILE="$GLOBUS/$CERT"
+    PWD="password"
+
+    D="-Dglobus=$GLOBUS"
+    CCP="bcprov-jdk16-145.jar" 
+    CP="./build:${CCP}" 
+    JAR="myproxy.jar"
+
+    # Initialize needed directories
+    rm -fr build
+    mkdir build
+    rm -fr $GLOBUS
+    mkdir $GLOBUS
+    rm -f $KEYSTORE
+    rm -f $TRUSTSTORE
+
+    # Compile MyProxyCmd and ImportKey
+    javac -d ./build -classpath "$CCP" *.java
+    javac -d ./build ImportKey.java
+
+    # Execute MyProxyCmd
+    java -cp "$CP myproxy.MyProxyCmd
+
+    # Build the keystore
+    openssl pkcs8 -topk8 -nocrypt -in $CERTFILE -inform PEM -out key.der -outform DER
+    openssl x509 -in $CERTFILE -inform PEM -out cert.der -outform DER
+    java -Dkeypassword=$PWD -Dkeystore=./${KEYSTORE} -cp ./build ImportKey key.der cert.der
+
+    # Clean up the certificates in the globus directory
+    for c in ${TRUSTROOTPATH}/*.0 ; do
+        alias=`basename $c .0`
+        sed -e '0,/---/d' <$c >/tmp/${alias}
+        echo "-----BEGIN CERTIFICATE-----" >$c       
+        cat /tmp/${alias} >>$c
+    done
+     
+    # Build the truststore
+    for c in ${TRUSTROOTPATH}/*.0 ; do
+        alias=`basename $c .0`
+        echo "adding: $TRUSTROOTPATH/${c}"
+        echo "alias: $alias"
+        yes | keytool -trustcacerts -storepass "$PWD" -v -keystore ./$TRUSTSTORE -alias $alias -importcert -file "${c}"
+    done
+    exit
+
+[Change Log]()
+--------------
+
+**Version 1.0:**
+
+-   10/17/2013 – Initial Release
+
+[Document Information]()
+------------------------
+
+  ------------------------------------------------------------------------
+  Created:
+  10/17/2013
+
+  Last Revised:
+  10/17/2013\
+
+  Version:
+  1.0
+
+  Author:
+  Dennis Heimbigner
+
+  Affiliation:
+  Unidata/UCAR
+
+  email:
+  dmh@unida.ucar.edu
+  ------------------------------------------------------------------------
+
+