Botan is a C++ crypto library with a wide range of supported cryptographic algorithms. In this article, I’ll walk you through building Botan for Android, so that it can be used in applications that are built with the Android NDK.
Preparations
In the following, I use Ubuntu 12.04 LTS (x86_64) with Eclipse as my development platform. If you use another operating system, the commands may differ.
First, we pull in the Java Development Kit (here: OpenJDK 6), some essential build tools and Python which is needed for the configure script:
sudo apt-get install openjdk-6-jdk build-essential python
We need to have the Android SDK and Eclipse with the Android Development Tools (ADT) installed. The easiest way to get both the SDK and Eclipse with ADT preinstalled is to get the ADT Bundle, extract it somewhere (I used /opt/adt-bundle) and run the eclipse/eclipse program from the resulting folder.
Next, we need to get the Android Native Development Kit (NDK) so that we can compile programs written in C or C++ for Android. I extracted it to /opt/android-ndk, but you can freely choose the location.
Generating the botan_all.* files
First, we download and extract the Botan sources. I recommend to get the Stable Series package, which is version 1.10 at the time of writing.
The configure script of Botan offers to put all of the code into one pair of .h/.cpp files, the botan_all.h and botan_all.cpp. This is called amalgamation and makes it easier to build Botan using the NDK, so we open a terminal, change to the Botan directory, and execute the configure script:
./configure.py --gen-amalgamation --cpu=armv5te --os=linux --cc=gcc --with-tr1=none
This works fine if we target ARM-based Android devices, which covers almost all devices out there. If you need to build for x86/Atom- or MIPS-based devices, you will likely need to adjust the argument to the –cpu parameter. The –with-tr1=none parameter seems to be necessary when using STLport instead of GNU STL (see below).
When the configure script is done, you should see the files botan_all.h and botan_all.cpp in the Botan folder.
Including Botan in an Android project
If you have not already started an Android project which should include Botan, create one now: In Eclipse/ADT, choose File -> New -> Android Application Project and follow the instructions.
Now that you created a project, create a subfolder named “jni” in the project folder which will hold the native code. Inside, create “Android.mk” and “Application.mk” files:
# jni/Android.mk:
include $(call all-subdir-makefiles)
# jni/Application.mk:
APP_ABI := armeabi
APP_CPPFLAGS += -fexceptions -frtti
APP_STL := stlport_shared
If you want to know more about these files, you can look it up in the docs folder of the Android NDK (files ANDROID-MK.html and APPLICATION-MK.html, or use the index in documentation.html in the NDK main directory). Basically, Android.mk tells the Android build system to look for makefiles in the subdirectories, while Application.mk introduces some settings that are used for all modules from the subfolders (ARM instruction set, allow C++ exceptions and RTTI, use STLport instead of the extremely restricted default Android STL).
When you have done this, it is time to create the directory “jni/botan”. Put the botan_all.* files in there and create another Android.mk file:
# jni/botan/Android.mk:
LOCAL_PATH:= $(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE := botan
LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)
LOCAL_SRC_FILES := botan_all.cpp
LOCAL_CPPFLAGS := -DBOTAN_USE_GCC_INLINE_ASM=0
include $(BUILD_SHARED_LIBRARY)
Again, detailed information can be found in ANDROID-MK.html. The LOCAL_CPPFLAGS line was necessary because, later on, the compiler complained about wrong assembler syntax when inline assembler was used.
Creating some native code that uses Botan
Now we need to build an interface so that our Java app can talk to our native code which will talk to Botan. We do this by creating a Native class which loads the necessary libraries in its static initializer, and which declares the methods that we intend to implement in C++, for example:
// src/de/tiwoc/botandemo/Native.java
package de.tiwoc.botandemo;
public class Native {
static {
System.loadLibrary("stlport_shared");
System.loadLibrary("botan");
System.loadLibrary("botandemo");
}
public static native String pbkdf2Demo(int iterations);
} The order of the loadLibrary statements is significant: botandemo uses botan, which uses stlport_shared, so stlport_shared must be loaded first, then botan, then botandemo.
botandemo will hold our glue code, so we need to create the folder “jni/botandemo” and create an Android.mk for this module:
# jni/botandemo/Android.mk
LOCAL_PATH:= $(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE := botandemo
LOCAL_SRC_FILES := botandemo.cpp
LOCAL_SHARED_LIBRARIES := botan
include $(BUILD_SHARED_LIBRARY)
The one new line in here is the LOCAL_SHARED_LIBRARIES statement which holds a list of the other modules which botandemo will use.
As a next step, we generate a header file corresponding to the Native class. To do this, we use a terminal to change to the bin/classes folder of the app and issue the javah command from the JDK:
javah -o ../../jni/botandemo/native.h de.tiwoc.botandemo.Native
Now, we can write a .cpp file which implements the definitions from the header. The following method will invoke the PBKDF2 key derivation algorithm with some test data:
// snippet from jni/botandemo/botandemo.cpp
JNIEXPORT jstring JNICALL Java_de_tiwoc_botandemo_Native_pbkdf2Demo
(JNIEnv * env, jclass cls, jint iterations)
{
try {
PBKDF* pbkdf = get_pbkdf("PBKDF2(SHA-256)");
AutoSeeded_RNG rng;
SecureVector<byte> salt = rng.random_vec(16);
OctetString aes256_key = pbkdf->derive_key(
32, "this_is_a_weak_password",
&salt[0], salt.size(), iterations);
return env->NewStringUTF(aes256_key.as_string().c_str());
} catch (...) {
std::string empty_str = "";
return env->NewStringUTF(empty_str.c_str());
}
} This does nothing particularly useful, but it shows how to bridge the gap between a Java app and the Botan library. A full and working example of this file is part of the example project that can be found on GitHub.
Building the library and testing the app
At this time, all of the native code can be built. We open a terminal, change to the main folder of our project (in this case: BotanDemo) and invoke the Android build system:
# $(NDK) denotes the main folder of the NDK
$(NDK)/ndk-build
This will put all of the native files in the right place inside the project folder, so that the ADT packages all of it into the .apk when building the app.
For the test project on GitHub, I added an Activity that invokes the pbkdf2Demo method:
After touching the button:
We’re done!
Get the demo project sources from Github!
Resources
The following web sites helped me a lot while I figured out how to do this: