SVMP Android Client

Setup

Prerequisites

Up-to-date Android SDK with at least API level 17, with ANDROID_HOME environment variable set correctly
Oracle JDK 6, with JAVA_HOME environment variable set correctly
ant

Build Steps

Check out the SVMP client and protocol to a directory of your choice

$ cd ${SVMP}
$ git clone https://github.com/SVMP/svmp-protocol-def.git
$ git clone https://github.com/SVMP/svmp-android-client.git

Build the client using ant. For example:

$ cd ${SVMP}/svmp-android-client
$ ant release

See Building and Running from the Command Line for additional commands.

Configuration

Server Trust

There are three ways to configure server trust in the client.

Pinned Trust Store

If res/raw/client_truststore.bks is not empty, the client will use it as the pinned trust store. This means that only certificates that validate through that trust store will be accepted.

By default, the file is empty. If you want to use this option you must place the certs to trust in the server_certs/ directory before compiling the client. The build process will import all files with the .pem extension from the server_certs/ directory.

If you encounter errors related to the keystore password, ensure the value for TRUSTSTORE_PASSWORD in the file src/org/mitre/svmp/common/Constants.java matches the client.truststore.password property in custom_rules.xml.

The build process will attempt to download the Bouncy Castle crypto provider jar needed for creating the keystore. If this fails, check that your http proxy settings for ant are correct.

Certificate Dialog

If the Pinned Trust store is not used, and the "Connection" -> "Show certificate dialog" preference is enabled, the user will be given a prompt when an unknown certificate is encountered. The prompt options allow the user to Abort, accept Once, or accept Always.

If you want to use this option you must enable the aforementioned preference. By default, the preference is disabled.

Default Trust Store

If the Pinned Trust Store and the Certificate Dialog are not used, the client will use the system trust store. This consists of normal trusted Android CA certs. This is the default server trust option.

Performance Instrumentation

If the "Performance" -> "Take measurements" preference is enabled, the client will record performance instrumentation measurements. These are stored in the client's SQLite database. By default, measurements are taken every 1 second. Measured values include: FrameCount, SensorUpdates, TouchUpdates, CPUUsage, MemoryUsage, WifiStrength, BatteryLevel, CellNetwork, CellValues, and Ping.

Measurement records are separated every time the client connects to a server. In Preferences, you can export measurement data to CSV files or wipe existing performance data from the database.

Sensor Data

In the "Sensors" preferences, you can adjust what sensors are polled to send data to the server. You can also adjust how often sensor data is sent. Note: sending too much sensor data can result in poor performance. We recommend leaving these values set to their defaults.

IDEs

First, check out the code as above. If you plan on using self-signed certificates for your SVMP servers, you should create a Pinned Trust Store to compile into the client. To do this, generate a Bouncy Castle trust store:

Check out the code as above.
Navigate into the code directory.
Copy any .pem certificate files (for your CA, or preferably for individual servers) into the server_certs/ directory.
Run the following command to generate the trust store:

$ ant import_client_truststore_certs

Now, Proceed to build the client with the IDE of your choice.

Eclipse with the ADT:

In Eclipse, select File -> New -> Project -> Android Project from Existing Code
Set the Root Directory to where the client code is checked out (${SVMP}/svmp-android-client).
The project list should now populate. Ensure the svmp-android-client and MemorizingTrustManager entries are checked. Edit the 'New Project Name' to your liking.
Click Finish.
Add ${SVMP}/svmp-protocol-def/protobuf-2.5.0/protobuf-java-2.5.0.jar to the project as an external library
Add ${SVMP}/svmp-protocol-def/src as an addtional source path to the project
Under Build Path -> Order and Export, check the box next to the protobuf-java-2.5.0.jar entry

IntelliJ IDEA:

In IDEA, select File -> Import Project (or, from the Welcome Screen, select Import Project)
Set the Root Directory to where the client code is checked out (${SVMP}/svmp-android-client)
Select Create project from existing sources -> Next
Edit the Project name to your liking, then select Next
Ensure that the project directory and src directories are checked, then select Next
Select Next at the prompts for the libraries and module structure
Select an Android platform for your SDK, then select Next (or, if you don't have one listed, select + to add a new SDK)
Ensure that both AndroidManifest.xml files are checked, then select Finish
Select File -> Project Structure..., then select Modules -> svmp-protocol-def, then select the Dependencies tab, then select + -> Library... -> protobuf-java-2.5.0 -> Add Selected
Select Modules -> svmp-android-client, then select the Dependencies tab, then select + -> Library... -> protobuf-java-2.5.0 -> Add Selected, then select OK
Select Run -> Edit Configurations..., under Target Device select Show chooser dialog to allow for target device selection, then select OK

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

pks-os / svmp-android-client Goto Github PK