Java GSS-API wrapper for the MIT Kerberos GSS-API library, usable with the Android NDK as well.
Fetching latest commit…
Cannot retrieve the latest commit at this time
MIT Kerberos GSS-API Java Interface NOTICE: This branch (jgss) is under development and may not build or run correctly. Please use the master branch for a stable build and more complete documentation. This package provides a Java GSS-API wrapper around the the MIT Kerberos GSS-API native library. This wrapper conforms to the GSS-API Java bindings via RFC 5653. One of the main goals of this project is to bring GSS-API functionality to the Android platform, which previous to this project lacked both Kerberos and GSS-API support. Using this project, Android developers are able to use GSS-API functionality in their Android NDK applications. For a working example of an Android NDK application using this Java GSS-API interface, please reference the "Kerberos Android NDK" project hosted on GitHub: https://github.com/cconlon/kerberos-android-ndk. This project provides a sample Android NDK application showing how to use MIT Kerberos and GSS-API functionality in an Android application. =========================================================================== CONTENTS: 1. Requirements 2. Project Design 2.1 Project Contents 3. Building 3.1 Desktop Environment 3.2 Android NDK Environment 5. License 6. Support =========================================================================== 1. REQUIREMENTS: You must have SWIG installed on your development machine in order to build this GSS-API wrapper. The Java GSS-API bindings are wrapped around a native SWIG-generated layer that then in turn interfaces to the native Kerberos GSS-API library. To download and install SWIG, please see the project homepage at http://www.swig.org/. This project has been developed using SWIG version 1.3.40 running on Linux. To use this interface in your Android NDK application, you need to include cross-compiled versions of the MIT Kerberos libraries for Android in your project. For details about these libraries and an example of how to include them in your project, please see the "Kerberos Android NDK" application on GitHub: https://github.com/cconlon/kerberos-android-ndk for both pre-compiled libraries and instruction on how to compile them manually. If you want to rebuild the pre-built Kerberos libraries, please use the android-config.sh shell script found in the above noted project. This will setup the correct autoconf environment for the MIT Kerberos libraries to be cross-compiled for the Android platform. More detailed instructions can be found in the script comments. The development machine must also have a working Java implementation installed in order to compile the source and examples. =========================================================================== 2. PROJECT DESIGN: This project is composed of several layers - most of which are invisible to the end Java API user. The individual layers are visualized in the following figure. The native MIT GSS-API library is first wrapped using SWIG to form a temporary C/Java layer (LAYER 1). This first layer may be used directly, but is more tedious and less standardized than the org.ietf.jgss interface. A top-level Java API is then wrapped around the SWIG-generated layer. This top-level Java API (LAYER 2) conforms to the org.ietf.jgss interface specification. The interface is located in the org.ietf.jgss package while the implementation is located in the edu.mit.jgss package. (LAYER 2) Java GSS-API interface (org.ietf.jgss, edu.mit.jgss) | |-----> (LAYER 1) SWIG-generated interface layer handling C-Java interaction | |-----> Native MIT Kerberos/GSS-API libraries 2.1 Package Contents: --------------------- A short description of the main file and directory structures in this package are below. gsswrapper.i ------------ This is the SWIG interface file. It contains all of the code and typemaps needed by SWIG to generate the corresponding "LAYER 1" Java interface for the MIT GSS-API library. gsswrapper_wrap.h ----------------- This is a header file that contains function prototypes for the SWIG-generated C wrapper functions. If functions are changed in gsswrapper.i, this file should be updated to match accordingly. src/java/edu/mit/jgss/swig -------------------------- Location of the SWIG-generated .java files which provide "LAYER 1" Java access to the native MIT GSS-API library using a similar interface to GSS-API C bindings. src/java/edu/mit/jgss --------------------- Location of the "LAYER 2" MIT Java GSS-API implementation of RFC 5653. src/java/org/ietf/jgss ---------------------- Location of the Layer 2 Java GSS-API interface files as outlined in RFC 5653. =========================================================================== 3.0 BUILDING: The Java GSS-API interface can currently be built for use on a standard desktop environment. Android support will come in the near future. 3.1 Desktop Environment ----------------------- To build the GSS-API interface and examples on a desktop environment, (1) cd to the directory containing gsswrapper.i 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 file using the ant build system uisng 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 3.2 Android NDK Environment --------------------------- <Documentation Coming Soon!> =========================================================================== NOTES: (1) Because the org.ietf.jgss package already exists on most desktop Java installations, it is necessary to set the bootclasspath variable when running applications built with MIT's org.ietf.jgss package. To see an example of this, please reference the test example scripts in ./examples (ie server.sh, client.sh). When using the bootclasspath, the MIT org.ietf.jgss classes are treated as system classes. All system classes will only lookup shared libraries in $JAVA_HOME/bin. As such, one of several actions needs to be done when using this package with bootclasspath: a) Install gsswrapper.so library into $JAVA_HOME/bin b) Set the sun.boot.library.path to include the gsswrapper.so library path. The syntax is: java -Dsun.boot.library.path=$JAVA_HOME/bin:/path/to/gsswrapper.so The need to use bootclasspath should not be necessary on Android, as the platform doesn't have an existing org.ietf.jgss package installed. (2) The Layer 2 MIT GSS-API Java implementation does not have support for the SPI framework that is specified in RFC 5653. This framework is specified as optional in the RFC. The current edu.mit.jgss package wraps directlly around the Layer 1 SWIG Java GSS-API package (edu.mit.jgss.swig). =========================================================================== LICENSES: MIT Kerberos Libraries: --------------------------------------------------- * Copyright (C) 2012 by the Massachusetts Institute of Technology. * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * * Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * * Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in * the documentation and/or other materials provided with the * distribution. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED * OF THE POSSIBILITY OF SUCH DAMAGE. =========================================================================== SUPPORT: If you have any questions or comments, please contact firstname.lastname@example.org or the MIT Kerberos community. October 25, 2012