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 wrapper around the the MIT Kerberos GSS-API library conforming to the GSS-API Java bindings via RFC 5653. It also exposes the standard GSS-API functions through a SWIG-generated interface. One of the main goals of this interface is to bring GSS-API functionality to Android, which up to this point has lacked both Kerberos and GSS-API support. Using this interface, Android developers will be able to use GSS-API functionality in their Android NDK applications. For a working example of an Android NDK application using the SWIG-generated GSS-API interface, please refer to the "Kerberos Android NDK" package on GitHub, here: https://github.com/cconlon/kerberos-android-ndk. =========================================================================== CONTENTS: 1. Requirements 2. Wrapper Design 3. Building 3.1 Desktop Environment 4. License 5. Support =========================================================================== REQUIREMENTS: You must have SWIG installed on your development machine in order to generate this GSS-API wrapper. 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 (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, here: https://github.com/cconlon/kerberos-android-ndk 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 allow the MIT Kerberos libraries to be cross-compiled for the Android platform. More detailed instructions can be found in the script comments. =========================================================================== WRAPPER DESIGN: This wrapper contains a few files which are used by SWIG to generate the Java GSS-API interface. A short description of those files along with descriptions of some of the key 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 Java interface for the MIT GSS-API library. gsswrapper_wrap.h ----------------- This is a header file that provides 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 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 MIT implementation of RFC 5653. src/java/org/ietf/jgss ---------------------- Location of the interface files as described by the IETF in RFC 5653. =========================================================================== 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. 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. (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 =========================================================================== 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. =========================================================================== 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. May 23, 2012