Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Java GSS-API wrapper for the MIT Kerberos GSS-API library, usable with the Android NDK as well.
Java C++

This branch is 28 commits behind master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
examples
native
src
JavaBuild.sh
README
build.xml
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 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
support@yassl.com or the MIT Kerberos community.

October 25, 2012

Something went wrong with that request. Please try again.