About PassWear

PassWear is a wearable authentication technology that increases the security of a mobile device or app while reducing mobile user dependency on passwords. Sometimes a password on your mobile is not enough, think mobile banking, corporate and social media apps, here you need two step verification, a second factor of authentication.

About the SDK

The PassWear SDK allows developers to harness the power of PassWear's strong mobile authentication solution in their own applications without writing a single line of wearable code.

Right now, the SDK is still in alpha so while PassWear is tried and tested, there might be bugs or improvements to be made. We'd love your feedback, so if you have a question, issue or suggestion then please .

What do I need?

To start developing, you'll need the following hardware:

• Android Wear, Samsung Gear or Pebble (currently only Pebble Time is supported) wearable.
• Android mobile device running Android 5.0 (Lollipop) or greater.

You'll also need:

• Your development environment set up for Android development. Full details of downloading the SDK and platform tools are available here.
• The PassWear SDK, currently packaged as 2 aars passwear-sdk-1.0.0 and passwear-core-1.0.0. These aars are also currently embedded in the sample app repository, though we aim to remove them eventually. Javadoc jars for sdk and core are also available.
• The PassWear Management application installed. This is available to download in the Google Play Store.
• PassWear application for your wearable device. If you're using Android Wear there's no need to do anything, it will be automatically installed with the management application. If you're using Samsung Gear or Pebble, visit these appstores from your mobile.

Quickstart

The best way to get familiar with PassWear is to take a look at and build our sample application. This is a fork of the excellent open source social media application andStatus which has been secured using PassWear.

1. Grab the source for the application from the Mobbu github. Alternatively use a prebuilt apk
2. Ensure the PassWear management application is installed on your device and PassWear is installed on your wearable.
3. Install the app on your phone. From source you can do this with gradle installRelease. If you have the apk you can do adb -d install <PATH_TO_APK.apk>.
4. Follow the onscreen instructions to provision your wearable and authenticate - once successful you'll have access to the application.
5. You're done - now every time you open the application, you'll need to authenticate in order to gain access.

Securing your own applications

Out of the box we provide a Passwear activitiy which takes care of the authenticating the user. In the sample app we use this as the main activity and delegate to the main application activity once the user is authenticated.

Securing your own application in this way with PassWear is the simplest way to get started.

1. Add the Passwear AAR libraries to your project. Currently you'll need 2 aars: passwear-sdk-1.0.0 and passwear-core-1.0.0. Copy both of these into the libs folder of your project. You'll need to add the following to your top level Gradle file:

   allprojects {
           repositories {
               jcenter()
               flatDir {
                   dirs 'libs'
               }
           }
       }

   Then add the following dependencies to your project Gradle file:

   compile(name:'passwear-sdk-1.0.0-SNAPSHOT', ext:'aar')
       compile(name:'passwear-core-1.0.0-SNAPSHOT', ext:'aar')
       compile 'com.google.guava:guava:18.0'
       compile ('org.simpleframework:simple-xml:2.7.1') {
           exclude group: 'stax', module: 'stax-api'
           exclude group: 'xpp3', module: 'xpp3'
       }

   In the future we intend to reduce the burden of these multiple dependencies.

2. Generate a RFC 4122 Section 4 compliant GUID. An easy way to do this is to use an online generator such as guidgenerator.com. The standard Java UUID class is also capable of generating an appropriate value.

3. To configure PassWear, you'll need to create a file passwear.xml in the res/raw folder of your project with the following format:

   <?xml version="1.0" encoding="utf-8"?>
       <config>
           <guid><YOUR_GUID></guid>
           <authType><AUTH_TYPE></authType>
       </config>

   authType controls the level of security of Passwear. Acceptable values are QR, BT, BC. See Authentication Types for an explanation of these values. If you don't like xml config files or want more control over the config see the following section on customising your config.

4. Add the PassWear activity to your AndroidManifest.xml and ensure that it is set to be the main activity of your application:

   <activity android:name="com.mobbu.passwear.sdk.ui.PasswearActivity" android:label="@string/app_name">
           <intent-filter>
               <action android:name="android.intent.action.MAIN" />
               <category android:name="android.intent.category.LAUNCHER" />
           </intent-filter>
       </activity>

5. Finally, to define what activity should launch once PassWear is successfully provisioned and authenticated, you should add an intent filter to the chosen activity in your AndroidManifest.xml:

   <intent-filter>
           <action android:name="<YOUR_PACKAGE_ID>.PASSWEAR_COMPLETE"/>
           <category android:name="android.intent.category.DEFAULT"/>
       </intent-filter>

   At this point your application should show the passwear activity on startup and delegate to your application once it has done it's work.

Customising the config

By default the PasswearActivity uses the xml config to configure Passwear.

If you wish to configure Passwear in code then extend the PasswearActivity and override the initialisePasswearConfig method to return your own custom implementation of PasswearConfig which currently looks like this:

public interface PasswearConfig {
        public UUID getGuid(Context ctx);
        public AuthType getAuthType(Context ctx);
    }

As each method takes a context parameter you can pass arbitrary information into each of these calls, for instance to dynamically change the authentication type based on arbitrary parameters.

Using the API

For a more customised implementation, there are a number of API methods available for provisioning and authenticating with a wearable and you can use these to build a more custom application. Here's a basic tutorial, for more details on methods see the JavaDoc for the SDK.

First, we create a new Passwear object:

Passwear passwear = new Passwear();

Then we initialise with some configuration, in this case by defining our own config programatically. A simple config looks like this:

PasswearConfig config = new PasswearConfig() {
        @Override
        public UUID getGuid(Context context) {
            return UUID.fromString("ae4c31b0-bb5b-4937-855c-adff7c4f4efd");
        }
        @Override
        public AuthType getAuthType(Context context) {
            return AuthType.QR;
        }
    };

For all of the API calls we need to specify a callback, this needs to implement the PasswearCallback interface with the onResult method.

PasswearCallback myCallback = new PasswearCallback() {
        @Override
        public void onResult(Object data, Error error) {
            if (error == null) {
               Log.d(TAG, "OK!");
            } else {
                Log.e(TAG, "Error! " + error);
            }
        }
    };

We can then pass both of these to our init method along with our context and application name.

passwear.init(getApplicationContext(), "My Secured App", config, myCallback);

From here, the pattern is much the same, we can provision a wearable as follows:

passwear.provision(myCallback);

And then authenticate either specifying an authentication type or allowing it default to the one specified in our config:

passwear.authenticate(myCallback);
    passwear.authenticate(AuthType.BC, myCallback);

Authentication Types

PassWear can be configured to use a number of different authetication options, depending on your security requirements or user's preference. The following options are available:

QR Authentication

When authenticating a QR code will be displayed on the wearable. To authenticate, simply scan this with the provided scanner which will be displayed. This is the most secure method of authentication but is also the most involved for a user.

AuthType.QR

Bluetooth Confirmation (Tap to Auth) Authentication

Authentication is carried out securely over bluetooth, the user won't need to scan a QR code, but they will need to either accept or decline the authentication request on their wearable. They'll be notified of this by a short vibration.

AuthType.BC

Bluetooth Authentication

Authentication is carried out securely over bluetooth and the user won't need to scan or confirm. The user will still be notified by a short vibration, but they won't need to interact with the wearable. This is the most transparent form of authentication.

AuthType.BT
        

Known Issues

There is a known issue with Services on Android needing to be initialised by a user before any events can be broadcast to them. This means the user must open the PassWear Management application once to allow the underlying service to restart. Users should also not force stop the management application or it will also need to be manually opened once to restart the service.