Client Tools and Directories

--------------------------------------------
DIRECTORIES AND FILES USED BY GREENPASS
--------------------------------------------

GreenpassWebApps/

   Contains most stuff that's necessary for the Greenpass Web apps.
   However, see also the directory tempca/ described below.

GreenpassWebApps/prefs

   Various preferences that might change depending on what machine
   you're serving the Web apps from and what directory they're in.

GreenpassWebApps/setenv.sh

   Sets environment variables needed to run things in the daemons/
   directory, and also the two utility programs in the lib/spkilib/
   directory.  Modify to suit your needs.

   NOTE: On gpcentral, the appropriate script is just in
   /home/gpadmin/setenv.sh.  (duplication of this one?)

GreenpassWebApps/web/

   Actual Web content of the Web apps, including CGI scripts; Apache
   configuration should point here.

GreenpassWebApps/web/cgi-bin/

   Contains three CGI scripts (grandcentral.py, getdelegated.py,
   delegate.py) that provide the front end to the three Web apps.
   Also two "auxiliary" scripts (visprint.py, getcert.py).

GreenpassWebApps/web/htdocs/app.css

   Stylesheet for the Web apps.  Fairly important, actually.

GreenpassWebApps/web/htdocs/sdtool.jar

   Signed bytecode for the delegation applet.  See discussion below
   for how it gets built (under new/appletbuild/).

GreenpassWebApps/lib/

   Python modules that actually do things, including the page logic
   code for the three Web apps.

GreenpassWebApps/lib/spkilib/

   A bit of S-expression code for actually creating public key values
   as canonical S-expressions and then hash them; the Web apps
   subsequently use hashes of users' public keys to identify users.

   Two scripts in here that can come in handy:

      x509subj.py [-h] some_x509_cert.pem:

         Extracts an RSA public key from an X509 cert and prints its
         SPKI representation.  If the -h option is given, prints the
         MD5 hash of the public key instead.  The output is a
         canonical S-expression; pipe into "sexp -a" (if you've
         installed Ron Rivest's S-expression library) to "see" the
         result as an "advanced" (readable) S-expression.

      x509hash.py some_x509_cert.pem:

         Shows the MD5 hash of the public key in an X509 cert as both
         a hex string (e.g., "f568014cb04693a90822f255c192db02") and
         as a Base64 string (e.g., "|9WgBTLBGk6kIIvJVwZLbAg==|").

GreenpassWebApps/lib/plugins/

   Bare bones implementation of plugins that let some things happen in
   different ways.  If you stick a "plugin_dir" option into the [main]
   section of the Greenpass prefs file, modules in there of the same
   name as plugins in here (ccache.py, enroll.py, introduce.py) should
   override the ones in here.  (We've never actually tested this,
   though.) The ones in here are "default" implementations that
   work with the XML-RPC daemons in the GreenpassWebApps/daemons/
   directory.

GreenpassWebApps/templates/

   Albatross templates for various pages.  Look an awful lot like
   HTML, but with special Albatross tags.

GreenpassWebApps/patches/

   Patches for M2Crypto and Visprint.

GreenpassWebApps/daemons/

   Python daemons that MUST run for the Web tools to work (also, the
   Greenpass prefs file must be set up to point to the daemons).  Make
   sure to run the setenv.sh script first!  Then run these using,
   simply, ./scriptname_d.py.

      introcache_d.py:

         Stores X.509 certificates of guests who have just introduced
         themselves; delegators pick up guests' certificates
         (containing their public keys) from here.

      tempca_d.py:

         Wraps the OpenSSL dummy CA.  See description of tempca/
         directory below.

GreenpassWebApps/jdaemons/

   Contains JSDSIAuthServer, a Java XML-RPC daemon that runs the
   "authorization cache" described in Nick Goffee's thesis.  Run it using:

      $ java JSDSIAuthServer 

   where  is the name of a file that contains an
   S-expression of the trust root's (i.e., source-of-authority's)
   public key.

   Make sure to source the setenv.sh script above, then compile using
   javac JDSIAuthServer.java.

GreenpassWebApps/jdaemons/scripts

   Contains utility scripts that call the authorization cache XML-RPC
   daemon from the command line.

      bootstrap.sh:  example of how to call bootstrap.py

      addcert.sh:    example of how to call addcert.py

   "cat" the above bash scripts to see what's really going on.

   [Note: rootcert and roscoecert are examples that will expire eventually!]

tempca/

   Contains certs, private keys, etc. for the "dummy CA".  See
   GreenpassWebApps/daemons/tempca_d.py for more information.

delegtool/

   Java source hierarchy for the delegation applet.  Don't delete this
   directory, but for work I've been using new/delegtool and
   new/visprint, which symlink to a place in here that's actually
   useful.

new/setenv.sh

   Be sure to source this before compiling the stuff below!  Notice
   that the applet depends on LiveConnect code, only available in the
   Java plugin libraries, not in the standard set of Java libraries.

new/delegtool (symlink)

   Source for the delegation applet.  To build, just cd into each
   directory and do a javac *.java.  Don't forget to javac
   DToolApplet.java in the top-level directory.  I'd suggest this
   order:

      util/             Random utility classes.

      sexp/             Minimal code for generating canonical
                        S-expressions.

      prefs/            Preferences support.

      kswrap/           Keystore wrappers (just PKCS#12 for now).

      uimod/            Logic ("models") for things the user has to
                        manipulate.  Notice there's stuff for
                        PGPfone-style word list fingerprints in
                        here, just not in ui/.  ;-)

         
      ui/               Swing UI code.  Wraps stuff in uimod/.

      tests/            Tests that may have worked at some point when
                        I was testing individual windows at a time.
                        Of main interest might be DToolApp, which is
                        just a full-application version of
                        DToolApplet.

   I originally used DToolApp to create "root" certificates (actually
   delegating from the SOA to myself) that are in
   GreenpassWebApps/jdaemons/scripts.  It might be easier to just rip
   the code out of uimod/DToolModel that generates the certs and
   write a command-line Java application to generate the initial
   "bootstrap" certificate or three.

new/visprint/

   Visprint code ported from C.

authserver/
delegtool/
dtool/
sd/
ssltospki/
spkitool/
etc.

   Old ("prototype", as opposed to "pilot") stuff.  Might be useful
   for hints on how things were done or how things evolved.