MIT KERBEROS: JAVA GSS-API WRAPPER

To build the GSS-API interface and examples on a desktop environment,

1. Change directory (cd) to the root package directory and edit the JavaBuild.sh file to match your system's Java and Kerberos configuration.
   NOTE: If building on OS X, the Java include directory will most likely be something similar to:
   /System/Library/Frameworks/JavaVM.framework/Versions/A/Headers
   For OS X, you'll also need to change the extension of the shared library being compiled by SWIG to .dylib (libgsswrapper.dylib) instead of .so which is used by standard Linux environments.
   If building on Linux, the Java include directory may be similar to:
   /usr/lib/jvm/java-6-openjdk/include
2. Verify that the library being loaded by the SWIG wrapper (gsswrapper.i) is the correct one. This should be the name of the library being created by the JavaBuild.sh script.
3. Run ./JavaBuild.sh
   This will run the correct SWIG command, create libgsswrapper.so (.dylib) as well as generate and compile all the necessary JNI and Java files needed for the interface and examples.
4. You may need to set LD_LIBRARY_PATH to include paths to the MIT Kerberos libraries on your system as well as the location of the SWIG-generated library. For example, something similar to:
   Linux:
   export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib:
   /home/myuser/kerberos-java-gssapi/
   Mac:
   export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/usr/local/lib:
   /Users/myuser/kerberos-java-gssapi/
5. Build the .java source files using the ant build system with the following command (issued from the package root directory). Compiled .class files will be placed into the ./build and ./examples/build directories.
   ant
6. To easily clean up the package and return it to its original state, run the following commands from the package root directory. This will delete all compiled Java source files and the SWIG-generated .java files located in src/java/edu/mit/jgss/swig and native/.
   ant clean
   ant cleanswig

The client example expects that the user has already run kinit to receive a TGT for the client principal. The client principal name, server service name, server address, and the server port need to be set to the correct values in client.java before it is compiled.

When running the client in a desktop environment, after starting the example server (server.java), run:

./examples/client.sh

from the root kerberos-java-gssapi directory. After the client has been started, it will do several things, including:

1. Establish a GSSAPI context with the example server
2. Sign, encrypt, and send a message to the server using gss_wrap.
3. Verify the signature block returned by the server with gss_verify_mic.
4. Repeat steps (2) and (3) but using gss_seal / gss_verify.
5. Perform misc. GSSAPI function tests

The server example is designed to be run on a standard desktop environment and has been tested on Linux. It is located in server.java and will connect to the example client (client.java). The server and server service name should be modified to the desired values before compiling the example.

On a desktop environment, after configuring and compiling the server, start it using:

./examples/server.sh

from the root kerberos-java-gssapi directory. Once started, the server will wait for a client connection. When a connection is received, the server will do several things, including:

1. Establish a GSS-API context with the example client
2. Receive and unwrap a wrapped message from the client
3. Generate and send a signature block for the received message.

For Android, the functionality of this client application has been built into the Android NDK sample application (KerberosAppActivity.java) in the kerberos-android-ndk repository. The client is also provided as a standalone Java example which may be run on standard desktop operating environments.

The client example expects that the user has already run kinit to receive a TGT for the client principal. The client principal name, server service name, server address, and server port need to be set to the correct values in gssClient.java before compilation.

When running the client in a desktop environment, after starting the example server (gssServer.java), run:

./examples/gssClient.sh

from the kerberos-java-gssapi root directory. After the client has been started, it will do several things, including:

1. Establish a GSSAPI context with the example server.
2. Sign, encrypt, and send a message to the server.
3. Verify the signature block returned by the server.

GSS-API structures/objects can be created like normal Java objects. For example to create a gss_OID and a gss_cred_id_t object, you would use:

gss_OID_desc myoid = new gss_OID_desc();
gss_cred_id_t_desc mycreds = new gss_cred_id_t_desc();

A list of GSS-API objects which are available through the Java interface include:

gss_OID_desc() / gss_OID_desc(String mechanism)
                mechanism = optional mech string to initialize the OID with
                (ex: "{ 1 2 840 113554 1 2 2}").
gss_OID_set_desc()
gss_buffer_desc() / gss_buffer_desc(String value)
                value = optional string to initialize the buffer with.
gss_channel_bindings_struct()
gss_cred_id_t_desc()
gss_ctx_id_t_desc()
gss_name_t_desc()

All GSS-API constants, including calling errors, routine errors, supplementary info bits, etc, are located in the gsswrapperConstants.java file. If your application code implements this file, the constants can be used directly. For example, if a Java class implements gsswrapperConstants:

public class myClass implements gsswrapperConstants
{
   ...
}

Then the constants can be used directly inside of that class:

if (maj_status != GSS_S_COMPLETE) { ... }

GSS-API macros that test status codes for error conditions are located in gsswrapper.java. Specific details can be seen in either gsswrapper.java or gsswrapper.i. The macros included are:

GSS_CALLING_ERROR
GSS_ROUTINE_ERROR
GSS_SUPPLEMENTARY_INFO
GSS_ERROR
GSS_CALLING_ERROR_FIELD
GSS_ROUTINE_ERROR_FIELD
GSS_SUPPLEMENTARY_INFO_FIELD

GSS-API macros that test status codes for error conditions are located in gsswrapper.java. Specific details can be seen in either gsswrapper.java or gsswrapper.i. The macros included are:

GSS_CALLING_ERROR
GSS_ROUTINE_ERROR
GSS_SUPPLEMENTARY_INFO
GSS_ERROR
GSS_CALLING_ERROR_FIELD
GSS_ROUTINE_ERROR_FIELD
GSS_SUPPLEMENTARY_INFO_FIELD

[ gss_display_status_wrap ]

This method has been included in the GSS-API Java interface to provide a wrapper around the standard GSS-API gss_display_status function. It is needed because Java passes in a long for min_status instead of a pointer to an OM_uint32. The Java prototype for this method is:

public static long gss_display_status_wrap(
       long min_status,
       long status_value,
       int status_type,
       gss_OID_desc mech_type,
       long[] message_context,
       gss_buffer_desc status_string);

[ getDescArray ]

This method allows the easy retrieval of gss_buffer_t value by Java. In the example Kerberos Android application it is used to get the value of an outputToken (gss_buffer_desc) as a Java byte[] to send across the network. The Java prototype for this method is:

public static byte[] getDescArray(gss_buffer_desc buffer);

[ setDescArray ]

This method allows the value of a gss_buffer_t object to be set from Java using a Java byte[] as input. In the example Kerberos Android application, it is used to set the value of an inputToken after it has been received as a byte[] from the example server. The Java prototype for this method is:

public static int setDescArray(gss_buffer_desc buffer, byte[] javaArray);

[ gss_OID_set_desc.getElement ]

This method is used to get a specific member of a gss_OID_set_desc object. It takes an offset as input and returns a gss_OID_desc object. The Java prototype is:

public gss_OID_desc getElement(int offset);

[ gss_OID_desc.equals ]

This is a comparison function for a gss_OID_desc and input mech string. It returns 1 if the two are equal, otherwise 0. The Java prototype is:

public int equals(String mechString_in);