Authentication test tools

INTRODUCTION

  This test code forms a counterpart to the gss-client and gss-server 
  programs found elsewhere in the authtest package. It exercises the
  GSSAPI security layer and is useful as a simple demonstration that
  secure contexts may be established and messages securely exchanged.

INSTRUCTIONS

  After compiling the Java stand-alone client and server as described
  below, you can then run them either with Sun's built-in GSSAPI or with
  Quest Software's VSJ (Vintela Single Sign-on for Java).

  These instructions assume you are using the host "server.example.com" 
  as a server.

  The client assumes you have a valid credential cache with a TGT,
  while the server assumes you have read access to a keytab with
  valid entries.

---------
Compiling
---------

  The target/authtest-java-1.0.jar file is usually bundled with the
  distribution, so compilation is normally not required. When you see
        -cp target/\*
  used in the examples below, it is referring to that JAR.

  However, if you have modified source files, and want to rebuild the
  JAR, you have various ways to do it.

  1) In the source root directory, run
        $ configure
        $ make gssapi/java/target/authtest-java-1.0.jar

  2) OR, in this directory, run
        $ mvn install

  3) OR, in this directory, run
        $ mkdir -p target/classes
        $ javac -d target/classes src/main/java/*.java
        $ jar fc target/authtest-java-1.0.jar -C target/classes .

---------------------------
Using SUN's GSSAPI provider
---------------------------

  Sun's GSSAPI provider comes built-in with most JREs, so this needs no other
  configuration except for the editing of the jaas-krb5.conf file.
  In it you will need to modify the principal and keyTab parameters 
  to match your server:

        com.sun.security.jgss.accept  {
          com.sun.security.auth.module.Krb5LoginModule required
          storeKey=true
          principal="host/server.example.com@EXAMPLE.COM"
          useKeyTab=true
          keyTab="./host.keytab"
          debug=true
          ;
        };

  Run the server with:
    $ java \
        -Djava.security.auth.login.config=jaas-krb5.conf \
        -Djavax.security.auth.useSubjectCredsOnly=false \
        -cp target/\* \
        Server

  and run the client in another window with:
    $ java \
        -Djava.security.auth.login.config=jaas-krb5.conf \
        -Djavax.security.auth.useSubjectCredsOnly=false \
        -cp target/\* \
        Client host/server.example.com

  Cut and paste the BASE-64 encoded tokens complete with trailing period '.'
  between the two programs. Note that sometimes a program may send two
  consecutive tokens.

  You will probably need to edit jaas-krb5.conf to change principal name 
  used by the server.

KNOWN PROBLEMS

  There appears to be a problem with host.keytabs written by QAS
  that contain removed entries. Java 1.5 and Java 6's kerberos libraries
  do not appear to understand the removed entries and will randomly
  report that they cannot find the service principal in the default keytab.
  The reason is that the Heimdal code used by VAS writes negative record 
  lengths for deleted records.

  Workarounds: 
    - unjoin, delete the keytab and re-join the server
    - use the ktedit tool to dump and undump the keytab to a local file, 
      and then use the keyTab= parameter in jaas-krb5.conf to specify its 
      location:
        $ sudo ktedit -k /etc/opt/quest/vas/host.keytab dump | 
          ktedit -k host.keytab undump

DEBUGGING

  Add debug=true to either or both clauses in jaas-krb5.conf

---------------------------
Using VSJ's GSSAPI provider
---------------------------

  (VSJ is an Active Directory authenticator product intended for
  use with J2EE servlets.)

  First, obtain the VSJ standard edition JAR and a license JAR. This example
  assumes they are named as follows:

        vsj/vsj-standard-3.3.jar
        vsj/vsj-license-no-expiry.jar

  Review the file vsj.security which overrides a particular part of 
  $JAVA_HOME/lib/security/java.security. Its job is to replace the entry
  that is Sun's GSS provider. You may have to vary the number at the end
  of the key if it isn't working.

  Run the server with:
    $ java \
        -cp vsj/\*:target/\* \
        -Djava.security.properties=./vsj.security \
        -Djcsi.kerberos.principal=host/server.example.com \
        -Djcsi.kerberos.keytab=./host.keytab \
        Server

  And run the client in another window with:
    $ java \
        -cp vsj/\*:target/\* \
        -Djava.security.properties=./vsj.security \
        Client host/server.example.com

DEBUGGING

  Add -Djcsi.kerberos.debug=true