Skip to content
This repository

Java GSS-API wrapper for the MIT Kerberos GSS-API library, usable with the Android NDK as well.

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 examples
Octocat-spinner-32 native
Octocat-spinner-32 src
Octocat-spinner-32 JavaBuild.sh
Octocat-spinner-32 README
Octocat-spinner-32 build.xml
Octocat-spinner-32 gsswrapper.i
README
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
support@yassl.com or the MIT Kerberos community.

May 23, 2012

Something went wrong with that request. Please try again.