Get Started

Rivetz is currently available on the Android platform. Support for PC's is under development.

Before you Begin

You'll need an Android device that supports Rivetz and basic experience programming with Android.

Check Device Compatibility

We are working on qualifying a broad range of phones. This includes the Samsung S6 and S5 as well as the Note 4 and Avant. The HTC One and LG Leon or Stylo from T-Mobile are also suitably equipped.

How to find Model Number
1. On 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 will also 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 support@rivetz.com so we can add your device's google account to the beta testers group.

For help getting access, see Beta Test Setup Instructions.

Get the apk from:
https://play.google.com/store/apps/details?id=com.rivetz.adapter.

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 Rivet Code 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.0.9@aar'
    compile 'com.rivetz:rivetz-lib:0.0.9'               
}
Current release version is 0.0.9.

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 KeyType's

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, etc. 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. And soon, we will provide features for sharing Riveted keys among cryptographically paired devices.

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

Developer Guide