MIT Kerberos: Android NDK Example App

This is a sample Android NDK application which provides a GUI wrapper around the MIT Kerberos kinit, klist, kvno, and kdestroy client applications. It also provides a sample client which uses the Java GSS-API interface. The GSS-API interface is a Java interface for the existing native MIT GSS-API library.

This package includes cross-compiled versions of the MIT Kerberos libraries as well as the CyaSSL Embedded SSL Library. It should be helpful to Android developers who are interested in using the Kerberos libraries or the GSS-API interface in their own Android NDK Applications.

By default, this package uses pre-built static Kerberos and CyaSSL libraries which are needed in order to be linked to the KerberosApp application's native library (libkerberosapp.so).

For detailed information on the Java GSS-API interface, please see the GSSAPI_README file included in this project's root directory or see the kerberos-java-gssapi project on GitHub, here:

https://github.com/cconlon/kerberos-java-gssapi

Before building or installing this package, you must have the Android SDK and NDK installed and set up on your system. It is also helpful to have the Android Emulator setup and configured with an Android platform greater than or equal to version 2.3.3 (Gingerbread). For details on downloading and setting these up, please see the following links:

Android SDK: http://developer.android.com/sdk/index.html

Android NDK: http://developer.android.com/sdk/ndk/index.html

Android Emulator: https://developer.android.com/studio/run/emulator.html

SWIG will also need to be installed in order to build the underlying GSS-API wrapper. To download and install SWIG, please visit see the project homepage at http://www.swig.org. This project has been developed using SWIG version 1.3.40 running on Linux.

To build and install this package, including Java GSS-API bindings, run the following commands.

android update project -p . -s
swig -java -package edu.mit.jgss.swig -outdir ./src/edu/mit/jgss/swig
-o ./jni/gsswrapper_wrap.c ./jni/gsswrapper.i
ndk-build
ant debug

If you want to rebuild the pre-built Kerberos libraries, please use the android-config.sh shell script. 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.

To install this package in a running Android emulator, run:

ant <debug> install

Where <debug> is either "debug" or "release", depending on what build configuration used with ndk-build.

Before running the KerberosApp application, the user needs to install both a Keytab file and a Kerberos configuration file. Reference the MIT Kerberos documentation for guidelines for creating these files. Once created, they can be installed using the adb push command, using:

adb push <local-file-path> <destination-file-path>

For example, to load a krb5.conf and krb5.keytab file from the current directory to an Android emulator under the /data/local/kerberos directory, run:

adb push krb5.conf /data/local/kerberos/
adb push krb5.keytab /data/local/kerberos/

If the application is set to use a client keytab instead of a password, the keytab file needs to contain an entry for the client principal (whose TGT will be obtained by using the "kinit" button in the sample Application).

NOTE: hosts file

If you need to edit the hosts file on the android emulator to accommodate for KDC locations, use the following steps:

emulator -avd <name> -partition-size 128
adb remount
adb pull /system/etc/hosts ./
<< edit hosts file on local machine >>
adb push ./hosts /system/etc

This NDK application's GUI is split into three tabs:

Client Info
Server Info
Client App

These tabs should be addressed in the order they are listed above. A short summary of each is below.

Client Info
This tab displays the wrappers around native kinit, klist, kvno, and kdestroy application code. It provides the functionality to get a ticket for a given client principal using either a keytab or password for principal authentication. The default configuration file and credential cache locations are listed on this screen as well.
Server Info
This tab allows the user to enter information about the server which the client application will attempt to make a GSS-API connection with in Tab 3. Server principal name, IP address, and port number should be given in this tab.
Client App
This tab allows the user to start the client GSS-API application. The client application will attempt to connect to the GSS-API server given in Tab 2, using the client principal info gathered in Tab 1. This client application was designed to connect to the example server from the kerberos-java-gssapi package. The client app will do the following:
a. Establish a GSS-API context with the example server
b. Sign, encrypt, and send a message to the server
c. Verify the signature block returned by the server

CyaSSL Embedded SSL Library
* Copyright (C) 2006-2012 Sawtooth Consulting Ltd.
*
* CyaSSL is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* CyaSSL is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA

MIT Kerberos Libraries and Application Code:
* 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.

Introduction

Table of Contents

1. Requirements

2. Building

3. Installing

4. Usage

5. Default Storage Locations

6. Library Versions

7. Licenses

8. Support

9. References