[test suite] added tests/rijndael_hmac_fuzzing.pl file
[fwknop.git] / android / README
1 ===============================================================================
2 FWKNOP for Android
3
4 Max Kastanas <max2idea@users.sourceforge.net>
5
6 Based on fwknop C implementation by Damien Stuart
7 ===============================================================================
8
9 1. Requirements:
10
11     a. Apache Ant (1.7.1)
12         http://ant.apache.org/bindownload.cgi
13
14     b. Android NDK (Android r5-linux)
15         http://developer.android.com/sdk/ndk/index.html
16         Unzip the contents under a directory ie:
17         /home/yourname/tools/android-sdk-linux_86
18
19     c. Android SDK (Android r08-linux)
20         http://developer.android.com/sdk/index.html
21         Unzip the contents under a directory ie:
22         /home/yourname/tools/android-ndk-r5
23
24     d. Include the Android SDK tools directory in your user PATH variable:
25         export PATH=$PATH:/home/dev/tools/android-sdk-linux_86/tools:/home/yourname/tools/android-ndk-r5
26
27     e. Download an SDK Android platform, in a command shell type: "android &"
28        to start up the "Android SDK and AVD Manager".  Download an SDK
29        platform (Android 2.1 and above is recommended) under the
30        "Available Packages" section.
31
32     f. Java SDK (1.6 and above)
33         http://www.oracle.com/technetwork/java/javase/downloads/index.html
34
35     g. Netbeans (6.9 and above) - Optional if you want to use Netbeans as
36        the IDE:
37         http://netbeans.org/downloads/
38
39     h. Netbeans Android plugin (0.11 and above) - Optional if you are using
40        the Netbeans IDE:
41         http://kenai.com/projects/nbandroid/pages/Install
42
43 ===============================================================================
44 2. Setup
45
46     a. Untar the tar.gz file:
47         tar -zxf Fwknop-0.9.tar.gz
48
49     b. Update the properties files with the path to the sdk and ndk tools:
50         .../fwknop-android/project/build.properties
51             sdk.dir=/home/yourname/tools/android-sdk-linux_86
52             ndk.dir=/home/yourname/tools/android-ndk-r5
53
54     c. Include the Android SDK platform directory in your user PATH variable
55         export PATH=$PATH:/home/dev/tools/android-sdk-linux_86/platforms-tools
56
57     d. Create a new Android device, in a command shell type: "android".
58         This will start the android SDK and AVD Manager
59         Under Virtual Devices create an AVD device and name it as "Android2.1"
60
61     e. Update (if needed) project file with the right virtual device as above:
62         .../fwknop-android/project/nbproject/project.properties
63             platform.active=Android2.1
64
65     f. The relevant fwknop android C code can be found under the
66        ".../project/jni" directory:
67          1. The ".../project/jni/libfwknop" directory should contain all of
68             the .c and .h files from the main fwknop/lib/ directory (the
69             libfko source files.  You can copy all of the *.[ch] files from
70             .../fwknop.../lib manually, or use the "get_libfko_files.sh"
71             script.
72
73          2. The ".../project/jni/fwknop" directory contains the code for
74             the android-specific client code (with the Java Native Interface
75             hooks).
76
77 ===============================================================================
78 3. Build
79
80     a. To build the app make sure you're under the project directory:
81         $> cd /home/yourname/.../fwknop-android/project
82
83     b. To build the application type:
84         $> ant jar
85
86 ===============================================================================
87 4. Run
88
89     a. Now search under the .../fwknop-android/dist directory for a .apk
90        file.  You can copy the .apk file to your SD card by typing (make
91        sure the Android Emulator is on):
92             $> adb push Fwknop.apk /sdcard/
93
94     Then you can open it and install it from within your Android device
95     using a Filemanager like Astro. Make sure that you have turned on the 
96     "Unknown Sources" Option under Application settings.
97
98 ===============================================================================
99 5. Android Emulator
100
101     If you don't have a device you can install and run Fwknop in the Android
102     emulator. To do so follow these steps:
103         $> android
104
105     Under the virtual devices find your device "Android2.1" and start it up
106
107     In a command line type:
108         $> adb install Fwknop.apk
109
110     You can now find the Firewall Knock Operator app under the menu tap on
111     the icon to get started.
112
113 ===============================================================================
114 6. Developing with Netbeans
115
116 To develop and build with Netbeans make sure you have installed the nbandroid
117 plugin (see requirements. Once you have that install a new Java platform under
118 the Tool -> Java Platforms and choose a Google Android platform, navigate
119 under the SDK platform directory you downloaded under step 1e. Finally, just
120 open the .../fwknop-android/project directory as a Netbeans project.
121
122 ===============================================================================
123 7. Debugging
124
125 You can use gdb to debug the app.  Before you do so make sure you have the
126 following attribute in your AndroidManifest.xml file:
127     android:debuggable="true" 
128 Now rebuild the application and start the Android Emulator, then in a command
129 shell type:
130     $> ndk-gdb --project=<path-to>/android/project
131
132 This will start gdb in remote debugging, similarly you can follow the same
133 steps to debug a physical device
134
135 ===============================================================================
136 Changelog
137 v0.9 Dec 28 2010
138 1) Rijndael client support
139 2) Local and External IP resolution
140 2) Automatically start ConnectBot
141
142