Rivetz is currently available on the Android platform. Support for PCs and servers is under development.

Before You Begin

Check Device Compatibility

We are working on qualifying a range of phones. We expect that the minimum OS requirement will be Android 7.0 ("Nougat"). This allows us to focus our development and testing on the most recent models with the best security implementations.

How to Find Your Model Number

  1. On your Android device, select 'Apps'.

  2. Locate Settings in the apps menu. This often looks like a gear icon.

  3. Locate and select 'About Phone' or 'About Tablet' or 'About Device' (name is different for all devices).

  4. Look for 'Model Number' or 'Model'. Examples of model numbers are 'SCH-i535', etc.

If your device is a Samsung, you also will need to ensure you have the required security policy. In the same Settings→About screen described above, check that the Security Enhancements for Android is enforcing a policy from July 17th, 2015, or later.

Get the Rivetz APK

The Rivetz app is still in beta, please contact us at TBD@rivetz.com so we can add your device’s Google Play account to the beta testers group.

Note: if you open this link in a browser you must have an active session with the Google account you supplied to us. Otherwise you will get a page not found error.

Connect your device to the Android development environment. Please refer to http://developer.android.com/tools/device.html. Once your device is visible from the desktop using adb devices you’re all set. For example.

user@host:~$ adb devices
List of devices attached
LGH345c670f255	device

Test Rivetz on your Device

Launch the Rivetz app and slide left to the Tools panel. Click Activate Developer Tools. This will pair the device with the generic "developer" Service Provider and trigger loading of the TA. The process takes about 30 seconds.

Once complete there will be two "Riveted Apps", RivetzNet and Developer Tools. You can tap these to see the keys they contain.

Add Rivetz to your Project

Assuming you are using Android Studio, point to our code repository and declare a dependency to the RivetJ Library and Rivetz Android Bridge. For example, in app/build.gradle add the following lines

repositories {
    maven {url "http://dl.bintray.com/rivetz/maven"}
}
dependencies {
    compile 'com.rivetz:rivetz-bridge:0.2.3@aar'
    compile 'com.rivetz:rivetz-lib:0.2.3'
}

Current release version is 0.2.3.

Create a Rivet

Import the Rivetz bridge library by adding com.rivetz.bridge to your class file

import com.rivetz.bridge.Rivet

Instantiate the Rivet class. Note that this is an asynchronous task as it establishes a binding to the Rivetz Adapter. You can provide a callback if you want to be notified when the binding is ready. In this example, we initialize the rivet with the Developer SPID (Service Provider ID). The Developer SPID is a common ID that can be used for experimentation. You will want to get your own ID if you have a real project in mind.

Rivet rivet = new Rivet(getApplicationContext(), Rivet.DEVELOPER_SPID);

Every Service Provider has a ServiceProviderRecord maintained by Rivetz on the device. This is used to store (encrypted) keys and state. The ServiceProviderRecord is established through a process called pairing, in which rivetz.net signs the service provider data and delivers it to the device. This establishes a trust relationship between the device and the service provider.

The pairing process involves user consent, and thus a UI element, but it only needs to happen once per device. You can test rivet.isPaired() or call pair() with the silent flag to just test if pairing is already done.

rivet.pair(getApplicationContext());

You call the Rivet to create a key and then do something with it. There are a number of different KeyTypes

rivet.createKey(KeyType.ECDSA_DFLT, "mykey");
String signature = rivet.sign("mykey","I yam what I yam");

Here’s the full source for MainActivity.java integrating a basic Rivet. The full project is available on Github: https://github.com/rivetz/SampleApp

package com.rivetz.sampleapp;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.widget.Toast;

import com.rivetz.lib.KeyRecord;
import com.rivetz.bridge.Rivet;
import com.rivetz.lib.Utilities;

public class MainActivity extends Activity {
    Rivet rivet;
    String keyName = "MyKey";

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        rivet = new Rivet(this, Rivet.DEVELOPER_SPID);
    }

    public void doPair(View v) {
        rivet.pairDevice(this);
    }

    public void doCreateKey(View v) {
        KeyRecord key = rivet.createKey(KeyType.ECDSA_DFLT,keyName);
        if (key != null) {
            Toast.makeText(this, key.name + " has been created", Toast.LENGTH_LONG).show();
        } else {
            Toast.makeText(this, "Error creating key: "+rivet.status, Toast.LENGTH_LONG).show();
        }
    }

    public void doSign(View v) {
        byte[] signature = rivet.sign(keyName,"this is a string");
        Toast.makeText(this, Utilities.bytesToHex(signature), Toast.LENGTH_LONG).show();
    }

    public void doDelete(View v) {
        rivet.deleteKey(keyName);
    }
}

Next Steps

In the above example we used the simplest interface and a Test Service Provider. For a production deployment, you will want to create your own Service Provider ID and sign instructions sent to the Rivet.

Create a Service Provider ID

A Service Provider represents legal and cryptographic ownership over keys created and applied using the SPID. In order to protect access to your Riveted keys you can require that all instructions using those keys be signed by your Service Provider Key. The Service Provider Key is established prior to registering with Rivetz and supplied in the registration process.

To create your key on a Linux system you can use ssh-keygen.

$ ssh-keygen -t ecdsa
Generating public/private ecdsa key pair.
Enter file in which to save the key (/home/user/.ssh/id_ecdsa): rivetz-key
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in rivetz-key.
Your public key has been saved in rivetz-key.pub.

Navigate to http://rivetz.com/docs/registration.html and fill out the registration form. You will need to provide company information and upload the key created in the last step.

You will also be asked to provide a logo for your app. This is an important visual identifier that is signed by Rivetz so it can’t be spoofed, particularly when used with Trusted User Interface. The logo should be a 256x256 pixel PNG file. Ideally the logo should be simple so the file size is kept to a minimum. White (#FFFFFF) is the default background color.

As a result of registration you will be emailed a newly minted Service Provider ID. Congratulations!

Sign your instructions

In the above example, the calls to Rivetz are made directly within the client Android App. Generally, you will want to create Rivet instructions on your server so you can sign them first. A key can be configure to only accept signed instructions.

The Rivetz Code Library is used by your server code to construct an instruction. This instruction is a byte array, which is signed and then passed down to the device. The instruction is invoked using rivet.execute(). A result record is returned, signed by the service provider unique device identity key, if present.

Further documentation coming soon!

Discover Rivetz

Rivetz is intended to be a very simple way to get very real keys for identity, encryption, transactions, and more. You can create keys of various types. (If you want to suggest a type we don’t support, contact us at support@rivetz.com.) You can attach rules to keys such as Require Trusted User Interface Confirmation. Soon, we will provide features for sharing Riveted keys among cryptographically paired devices.

The Reference Guide provides full documentation of the Rivetz API classes.