More source code commenting...

src/de/tudarmstadt/informatik/hostage/HoneyService.java

@@ -27,13 +27,20 @@ import de.tudarmstadt.informatik.hostage.logging.Logger;
 import de.tudarmstadt.informatik.hostage.logging.SQLLogger;
 import de.tudarmstadt.informatik.hostage.protocol.Protocol;
 import de.tudarmstadt.informatik.hostage.ui.MainActivity;
-
+/**
+ * Background service running as long as at least one protocol is active.
+ * Service controls start and stop of protocol listener.
+ * Notifies GUI about events happening in the background.
+ * Creates Notifications to inform the user what it happening.
+ * @author Mihai Plasoianu 
+ * @author Lars Pandikow
+ */
 public class HoneyService extends Service {
 
 	private ArrayList<HoneyListener> listeners = new ArrayList<HoneyListener>();
 	private NotificationCompat.Builder builder;
 	private SharedPreferences pref;
-	Editor editor;
+	private Editor editor;
 	private boolean stopped = false;
 
 	public List<HoneyListener> getListeners() {
@@ -56,8 +63,6 @@ public class HoneyService extends Service {
 
 	@Override
 	public IBinder onBind(Intent intent) {
-		NotificationManager mNotificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
-		mNotificationManager.cancel(2);
 		return mBinder;
 	}
 
@@ -88,12 +93,18 @@ public class HoneyService extends Service {
 		unregisterNetReceiver();
 	}
 	
-	// Delete session data
+	/**
+	 * Deletes all session related data.
+	 */
 	private void deleteSessionData(){
     	editor.clear();
     	editor.commit();
 	}
 	
+	/**
+	 * Register broadcast receiver for custom broadcast.
+	 * @see MainActivity#BROADCAST
+	 */
 	private void registerNetReceiver() {
 	    // register BroadcastReceiver on network state changes	    
 		IntentFilter intent = new IntentFilter();
@@ -101,15 +112,18 @@ public class HoneyService extends Service {
 	    registerReceiver(netReceiver, intent);
 	}
 
+	/**
+	 * Unregister broadcast receiver for custom broadcast.
+	 * @see MainActivity#BROADCAST
+	 */
 	private void unregisterNetReceiver() {
 		unregisterReceiver(netReceiver);
 	}
-	
-	private void mStopSelf(){
-		stopped = true;
-		stopSelf();	
-	}
 
+	/**
+	 * Receiver for custom broadcast.
+	 * @see MainActivity#BROADCAST
+	 */
 	private BroadcastReceiver netReceiver = new BroadcastReceiver() {
 		@Override
 		public void onReceive(Context context, Intent intent) {
@@ -124,7 +138,18 @@ public class HoneyService extends Service {
 				}
 		}
 	};	
+	
+	/**
+	 * Service stops himself.
+	 */
+	private void mStopSelf(){
+		stopped = true;
+		stopSelf();	
+	}
 
+	/**
+	 * Creates a Notification in the notification bar.
+	 */
 	private void createNotification() {
 		DatabaseHandler dbh = new DatabaseHandler(this);
 		boolean activeHandlers = false;
@@ -162,6 +187,9 @@ public class HoneyService extends Service {
 		mNotificationManager.notify(1, builder.build());
 	}
 	
+	/**
+	 * Updates the notification when a attack is registered.
+	 */
 	private void updateNotification() {
 		SharedPreferences defaultPref = PreferenceManager.getDefaultSharedPreferences(this);
 		String strRingtonePreference = defaultPref.getString("pref_notification_sound", "content://settings/system/notification_sound");  
@@ -170,6 +198,7 @@ public class HoneyService extends Service {
 				.setTicker("Honeypot under attack!")
 				.setContentText("Network is infected!")
 				.setSmallIcon(R.drawable.ic_service_red)
+				.setAutoCancel(true)
 				.setWhen(System.currentTimeMillis())
 				.setSound(Uri.parse(strRingtonePreference)); 
 		TaskStackBuilder stackBuilder = TaskStackBuilder.create(this);
@@ -186,6 +215,9 @@ public class HoneyService extends Service {
 		mNotificationManager.notify(1, builder.build());
 	}
 
+	/**
+	 * Cancels the Notification
+	 */
 	private void cancelNotification() {
 		NotificationManager mNotificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
 		mNotificationManager.cancel(1);
@@ -216,6 +248,10 @@ public class HoneyService extends Service {
 		mNotificationManager.notify(2, builder.build());
 	}
 
+	/**
+	 * Creates a instance of each protocol defined in /res/values/protocols.xml and puts it in a List
+	 * @return ArrayList of {@link de.tudarmstadt.informatik.hostage.protocol.Protocol}
+	 */
 	private ArrayList<Protocol> getProtocolArray() {
 		String[] protocols = getResources().getStringArray(R.array.protocols);
 		String packageName = Protocol.class.getPackage().getName();
@@ -233,6 +269,10 @@ public class HoneyService extends Service {
 		return protocolArray;
 	}
 	
+	/**
+	 * Determines if there are running listeners.
+	 * @return True if there is a running listener, else false.
+	 */
 	public boolean hasRunningListeners(){
 		for (HoneyListener listener : listeners) {
 				if (listener.isRunning())
@@ -241,8 +281,11 @@ public class HoneyService extends Service {
 		return false;
 	}
 
-	// IPC
-	
+	/**
+	 * Notifies the GUI about a event.
+	 * @param protocol The protocol where the event happend.
+	 * @param key The key for the event.
+	 */
 	public void notifyUI(String protocol, String key) {
 		// Send Notification
 		if (key.equals(MainActivity.HANDLER_COUNT)){
@@ -253,7 +296,9 @@ public class HoneyService extends Service {
 		LocalBroadcastManager.getInstance(this).sendBroadcast(intent);
 	}	
 	
-
+	/**
+	 * Starts all listeners which are not already running
+	 */
 	public void startListeners() {
 		for (HoneyListener listener : listeners) {
 			if(!listener.isRunning()){
@@ -263,6 +308,9 @@ public class HoneyService extends Service {
 		Toast.makeText(getApplicationContext(), "SERVICES STARTED!", Toast.LENGTH_SHORT).show();
 	}
 
+	/**
+	 * Stops all running listeners.
+	 */
 	public void stopListeners() {
 		for (HoneyListener listener : listeners) {
 			if(listener.isRunning()){
@@ -272,6 +320,10 @@ public class HoneyService extends Service {
 		Toast.makeText(getApplicationContext(), "SERVICES STOPPED!", Toast.LENGTH_SHORT).show();
 	}
 
+	/**
+	 * Starts the listener for the specified protocol.
+	 * @param protocolName Name of the protocol that should be started.
+	 */ 
 	public void startListener(String protocolName) {
 		for (HoneyListener listener : listeners) {
 			if (listener.getProtocolName().equals(protocolName)) {
@@ -283,6 +335,10 @@ public class HoneyService extends Service {
 		Toast.makeText(getApplicationContext(), protocolName + " SERVICE STARTED!", Toast.LENGTH_SHORT).show();
 	}
 
+	/**
+	 * Stops the listener for the specified protocol.
+	 * @param protocolName Name of the protocol that should be stopped.
+	 */ 
 	public void stopListener(String protocolName) {
 		for (HoneyListener listener : listeners) {
 			if (listener.getProtocolName().equals(protocolName)) {
@@ -294,6 +350,10 @@ public class HoneyService extends Service {
 		Toast.makeText(getApplicationContext(), protocolName + " SERVICE STOPPED!", Toast.LENGTH_SHORT).show();
 	}
 
+	/**
+	 * Toggles a listener for specified protocol.
+	 * @param protocolName Name of the protocol that should be toggled.
+	 */
 	public void toggleListener(String protocolName) {
 		for (HoneyListener listener : listeners) {
 			if (listener.getProtocolName().equals(protocolName)) {

src/de/tudarmstadt/informatik/hostage/commons/GetExternalIPTask.java

@@ -9,7 +9,12 @@ import org.apache.http.util.EntityUtils;
 import org.json.JSONObject;
 
 import android.os.AsyncTask;
-
+/**
+ * A {@link android.os.AsyncTask} that determines and returns the external IP address of the device.
+ * Therefore it uses a given URL to get a JSON Object containing the external IP address.
+ * @author Lars Pandikow
+ *
+ */
 public class GetExternalIPTask extends AsyncTask<String, Void, String> {
 	 @Override
     protected String doInBackground(String... url) {

src/de/tudarmstadt/informatik/hostage/commons/HelperUtils.java

@@ -31,7 +31,7 @@ import android.os.Environment;
 import android.text.TextUtils;
 
 /**
- * Helper class for some static methods.
+ * Helper class with some static methods for general usage.
  * @author Lars Pandikow
  * @author Wulf Pfeiffer
  *
@@ -63,7 +63,7 @@ public final class HelperUtils {
 
 	/**
 	 * Gets BSSID of the wireless network.
-	 * @param context Needs a context to get system recourses
+	 * @param context Needs a context to get system recourses.
 	 * @return BSSID of wireless network if connected, else null.
 	 */
 	public static String getBSSID(Context context) {
@@ -86,7 +86,7 @@ public final class HelperUtils {
 
 	/**
 	 * Gets internal IP address of the device in a wireless network.
-	 * @param context Needs a context to get system recourses
+	 * @param context Needs a context to get system recourses.
 	 * @return internal IP of the device in a wireless network if connected, else null.
 	 */
 	public static String getInternalIP(Context context) {
@@ -112,11 +112,6 @@ public final class HelperUtils {
 		return ipAddress;
 	}
 
-	/**
-	 * Unpacks the IP address
-	 * @param bytes
-	 * @return
-	 */
 	private static byte[] unpackInetAddress(int bytes) {
 		return new byte[] { (byte) ((bytes) & 0xff),
 				(byte) ((bytes >>> 8) & 0xff), (byte) ((bytes >>> 16) & 0xff),
@@ -124,9 +119,10 @@ public final class HelperUtils {
 	}
 
 	/**
-	 * 
-	 * @param context
-	 * @return
+	 * Determines and returns the external IP address of the device.
+	 * @param context  Needs a context to get system recourses.
+	 * @return A String representation of the external IP of the device.
+	 * @see GetExternalIPTask
 	 */
 	public static String getExternalIP(Context context) {
 		String ipAddress = null;
@@ -135,16 +131,18 @@ public final class HelperUtils {
 		try {
 			ipAddress =  task.get();
 		} catch (InterruptedException e) {
-			// TODO Auto-generated catch block
 			e.printStackTrace();
 		} catch (ExecutionException e) {
-			// TODO Auto-generated catch block
 			e.printStackTrace();
 		}
 		return ipAddress;
 	}
 	 
-	
+	/**
+	 * Updates the connextion info and saves them in the the SharedPreferences for session data.
+	 * @param context Needs a context to get system recourses.
+	 * @see MainActivity#SESSION_DATA
+	 */
 	public static void updateConnectionInfo(Context context) {	
 		SharedPreferences pref = context.getSharedPreferences(MainActivity.SESSION_DATA, Context.MODE_PRIVATE);
 		Editor editor = pref.edit();
@@ -155,7 +153,10 @@ public final class HelperUtils {
 		editor.commit();
 	}	
 
-	/* Checks if external storage is available for read and write */
+	/**
+	 * Checks if external storage is available for read and write.
+	 * @return True if external storage is available for read and write, else false.
+	 */
 	public static boolean isExternalStorageWritable() {
 		String state = Environment.getExternalStorageState();
 		if (Environment.MEDIA_MOUNTED.equals(state)) {
@@ -164,6 +165,11 @@ public final class HelperUtils {
 		return false;
 	}
 
+	/**
+	 * Creates a HttpClient with an own SSL Socket.
+	 * @return HttpsClient who accepts accepts all certificates.
+	 * @see MySSLSocketFactory
+	 */
 	public static HttpClient createHttpClient() {
 		try {
 			KeyStore trustStore = KeyStore.getInstance(KeyStore
@@ -192,7 +198,12 @@ public final class HelperUtils {
 		}
 	}
 	
-		public static byte[] concat(byte[]... bytes) {
+	/**
+	 * Concatenates several byte arrays.
+	 * @param bytes The byte arrays.
+	 * @return A single byte arrays containing all the bytes from the given arrays in the order they are given.
+	 */
+	public static byte[] concat(byte[]... bytes) {
 		int newSize = 0;
 		for (byte[] b : bytes)
 			newSize += b.length;

src/de/tudarmstadt/informatik/hostage/logging/Record.java

@@ -6,6 +6,8 @@ import java.net.InetAddress;
  * This class defines the attributes of a record.<br>
  * A Record is a single message exchanged between the application and an attacker.<br>
  * The class has no own functionality except for getter and setter methods.
+ * To change the logging mechanism you have to to change the logger in {@link de.tudarmstadt.informatik.hostage.HoneyService} and 
+ * {@link de.tudarmstadt.informatik.hostage.ui.ViewLog}
  * @author Mihai Plasoianu 
  * @author Lars Pandikow
  */

src/de/tudarmstadt/informatik/hostage/protocol/Protocol.java

@@ -3,57 +3,57 @@ package de.tudarmstadt.informatik.hostage.protocol;
 import java.util.List;
 
 /**
- * Interface for protocols that are used by hostage
- * @param <T> Denotes if the protocol is using Strings or ByteArrays
+ * Interface for protocols that are used by the application.
+ * @param <T> Denotes if the protocol is using Strings or ByteArrays.
  */
 public interface Protocol<T> {
 
 	/**
-	 * Represents who starts the communication once the connection is established
+	 * Represents who starts the communication once the connection is established.
 	 */
 	public static enum TALK_FIRST {
 		SERVER, CLIENT
 	};
 
 	/**
-	 * Returns the port on which the protocol is running
+	 * Returns the port on which the protocol is running.
 	 * @return the port used by the protocol (range: 0-65535)
 	 */
 	int getPort();
 
 	/**
 	 * Returns who starts the communication (server or client)
-	 * @return TALK_FIRST.server if the server starts or TALK_FIRST.client if the client starts
+	 * @return TALK_FIRST.server if the server starts or TALK_FIRST.client if the client starts.
 	 */
 	TALK_FIRST whoTalksFirst();
 
 	/**
-	 * Determines the next message that is sent by the server
-	 * @param message last message that was sent by the client
-	 * @return next message that will be sent
+	 * Determines the next message that is sent by the server.
+	 * @param message last message that was sent by the client.
+	 * @return next message that will be sent.
 	 */
 	List<T> processMessage(T message);
 
 	/**
-	 * Returns whether the communication is ended and the connection should be closed or not
-	 * @return true if the connection should be closed, else false
+	 * Returns whether the communication is ended and the connection should be closed or not.
+	 * @return true if the connection should be closed, else false.
 	 */
 	boolean isClosed();
 
 	/**
-	 * Returns if the protocol uses SSL/TLS connection or not
-	 * @return true if SSL/TLS is used, else false
+	 * Returns if the protocol uses SSL/TLS connection or not.
+	 * @return true if SSL/TLS is used, else false.
 	 */
 	boolean isSecure();
 
 	/**
-	 * Returns what type the protocol is using, Strings or ByteArrays
-	 * @return the class that the protocol is using
+	 * Returns what type the protocol is using, Strings or ByteArrays.
+	 * @return the class that the protocol is using.
 	 */
 	Class<T> getType();
 	
 	/**
-	 * Returns the name of the protocol
+	 * Returns the name of the protocol.
 	 * @return name of the protocol
 	 */
 	@Override 

src/de/tudarmstadt/informatik/hostage/ui/MainActivity.java

@@ -57,9 +57,14 @@ import de.tudarmstadt.informatik.hostage.logging.SQLLogger;
  */
 public class MainActivity extends Activity {
 	// String constants for whole application
+	/**
+	 * Used for Broadcast between service and GUI. String: "de.tudarmstadt.informatik.hostage.BROADCAST"
+	 */
 	public static final String BROADCAST = "de.tudarmstadt.informatik.hostage.BROADCAST";
+	/**
+	 * Used to store session related data in a SharedPrefereces. String: "de.tudarmstadt.informatik.hostage.SESSION_DATA"
+	 */
 	public static final String SESSION_DATA = "de.tudarmstadt.informatik.hostage.SESSION_DATA";
-	public static final String PERSISTENT_DATA = "de.tudarmstadt.informatik.hostage.SESSION_DATA";
 	public static final String LISTENER = "_LISTENER";
 	public static final String HANDLER_COUNT = "_HANDLER_COUNT";
 	public static final String SSID = "SSID";
@@ -67,9 +72,21 @@ public class MainActivity extends Activity {
 	public static final String INTERNAL_IP = "INTERNAL_IP";
 	public static final String EXTERNAL_IP = "EXTERNAL_IP";
 
+	/**
+	 * Integer representing a grey light.
+	 */
 	public static final int LIGHT_GREY = 0x01;
+	/**
+	 * Integer representing a green light.
+	 */
 	public static final int LIGHT_GREEN = 0x02;
+	/**
+	 * Integer representing a red light.
+	 */
 	public static final int LIGHT_RED = 0x03;
+	/**
+	 * Integer representing a yellow light.
+	 */
 	public static final int LIGHT_YELLOW = 0x04;
 
 	private HoneyService mService;
@@ -352,8 +369,8 @@ public class MainActivity extends Activity {
 	}
 
 	/**
-	 * Register broadcast receiver for costume broadcast.
-	 * @see BROADCAST
+	 * Register broadcast receiver for custom broadcast.
+	 * @see MainActivity#BROADCAST
 	 */
 	private void registerReceiver() {
 		LocalBroadcastManager.getInstance(this).registerReceiver(mReceiver,
@@ -370,6 +387,7 @@ public class MainActivity extends Activity {
 	
 	/**
 	 * Receiver for custom broadcast.
+	 * @see MainActivity#BROADCAST
 	 */
 	private BroadcastReceiver mReceiver = new BroadcastReceiver() {
 		@Override