Rivetz Brand Logo

The Rivetz Network

Transforming Risk to Trust

 Intro to Rivetz

This is a very early version of our developer documentation. More content will be available very soon!

Getting Started

It is strongly suggested that you familiarize yourself with the Rivetz objectives and technology by reading the Rivetz Technology Overview document on this website.

Note that Rivetz is currently available only on the Android platform. The minimum OS requirement is Android 7.0, API level 24 ("Nougat").

Rivet Installation Overview

In order to develop and run an application using the Rivetz Toolkit, you must first download and install the Rivetz Application (the Rivet). The Rivet serves as the middleware between your Android application and the trusted capabilities of the device it is running on. The installation steps below will walk you through how to download and then activate the Rivet.

  • Open the Google Play Store app on a TEE-compatible mobile device.

  • Search for 'Rivetz' in the Play Store.

  • Install the Rivetz App.

With the Rivet now installed, you are ready to begin to develop your application. Note that all examples in this document assume the use of Android Studio.

Even though there may be an Android virtual device that matches your hardware, the emulation does not support the functions needed to load and execute the TEE / TA. You'll need to connect your Rivetz activated device to the development environment. Please refer to 'Run apps on a hardware device' for instructions on how to connect your device to Android Studio. 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

Add Rivetz to your Project

Assuming you are using Android Studio, point to our code repository and declare dependencies on the RivetzJ API, Library and Android Bridge binaries. Add the following line to the project level build.gradle file to access the repository:

maven {
    url "https://s3-us-west-2.amazonaws.com/maven.rivetz.com/releases"
}

You should also add the following variable to your gradle.properties file to specify the current release version of the library; in this example, the current release is set to 1.0.5.

rivetzJVersion=1.0.5

Dependencies are declared inside the Module:app build.gradle file:

dependencies {
    implementation 'com.android.support:appcompat-v7:28.0.0'
    implementation 'com.rivetz:rivetz-api:{rivetzJVersion}'
    implementation 'com.rivetz:rivetz-bridge:{rivetzJVersion}@aar'
    implementation 'com.rivetz:rivetz-lib:{rivetzJVersion}'
}

Create a Rivet

Import the Rivetz API classes by adding the following imports to your Java source file. (Note that currently we are still accessing the Rivet class in the bridge module, but this will change in the future.)

import com.rivetz.api.RivetInterface;
import com.rivetz.api.KeyRecord;
import com.rivetz.api.SPID;
import com.rivetz.bridge.Rivet;

Next, instantiate the Rivet class. Note that this is an asynchronous task as it establishes a binding to the Rivet. You can provide a callback if you want to be notified when the binding is ready. In this example, we initialize the Rivet using the Service Provider ID SPID.DEVELOPER_TOOLS_SPID. This is a predefined service provider ID that can be used for experimentation.

import com.rivetz.api.SPID;

@Override
protected void onCreate(Bundle savedInstanceState) {
    // Create a new rivet using the developer SPID and pair it
    rivet = new Rivet(this, SPID.DEVELOPER_TOOLS_SPID);
    if (!rivet.isPaired()) { // Always false as binder.api is NULL until connected to Adapter
        rivet.pairDevice(this); // Set up intent and wait for activity completion
    }
}

You will want to get your own service provider ID when you are ready to begin developing your Rivetz application(s) for deployment. See Next Steps at the end of this document for more information on acquiring a service provider ID.

Pairing

The trust relationship between a device and service provider is established through a process called pairing, in which the Rivetz Network Registrar signs the service provider data and delivers it to the requesting device. Encrypted keys and other state information is stored on the device in a Rivetz maintained Service Provider Record. When a device pairs with a service provider, the service providers' public key is exchanged with the device public key. The SP private key is stored by the service itself, and the device private key is stored within the TEE.

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.

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    // Forward the onActivityResult to the base class method.
    super.onActivityResult(requestCode, resultCode, data);

    // Process all pair device request results and ignore all others.
    if (requestCode == Rivet.INSTRUCT_PAIRDEVICE) { // Pairing/bindToAdapter response
        // Check result of the PAIR instruction.
        if (resultCode == RESULT_OK)
            onRivetReady(); // Only now is the Rivet ready to use!
        else
            onRivetPairFailure(resultCode);
    }
}

Next Steps

Build and Run the Sample Applications

We have developed a collection of sample applications which demonstrate the use of the API's available to developers. There is also a template that can be used to as the starting point for a new app. Each sample includes both the source and build files. The repository is available on GitHub: https://github.com/rivetz/Core-Samples. The sample apps are ready to import into Android Studio, build and run.

We strongly recommend you download, build and run one or more of these applications as a way to verify that your development environment and target mobile device are configured properly.

IMPORTANT: As described earlier, the sample applications will not run on an Android Virtual Device. The test device must be physically connected. It must also have the Rivetz application installed and running as described at the beginning of this document, prior to executing the sample applications.

Create a Service Provider ID

In the above example we used a development (test) Service Provider. For a production deployment, you will want to acquire your own Service Provider ID (SPID). This will be used for such things as a service provider identity within the Rivetz Network, pairing and exchanging keys between mobile apps and cloud services, as well as signing and verifying instructions.

A SPID represents legal and cryptographic ownership over keys that are created or are applied while using it. In order to protect access to your Riveted keys you can require, via application of a usage policy, that all instructions using those keys be signed by your Service Provider Key.

The public Service Provider Key is established by creating a public / private key pair prior to registering with Rivetz. The public portion of the Service Provider Key pair is submitted in the SPID registration process described below.

As an example, to create a key pair 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.

WARNING: Note that the private key generated as a part of the key pair will be used by you, the Service Provider, to access both paired Riveted devices as well as various Rivetz Network services. Please take all necessary precautions to protect access to this key!

SPID Registration Process

In order to register and to prepare for the exchange of RvT tokens for a SPID, a ERC-20 capable wallet preloaded with at least 1000 RvT is required. Use of the Chrome browser with the MetaMask wallet plugin is currently the only configuration supported.

Navigate to https://registrar.rivetzintl.com where you will find instructions as well as the registration form. You will need to provide company and contact information, and also upload the public key created in the previous step.

You also will 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 the 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.

KYC/AML

Because Rivetz International is a Caymanian registered company, regulations require we perform a Know Your Customer / Anti-Money Laundering (KYC/AML) review for all individuals and companies requesting a SPID. This process is automatically initiated on submission of the SPID registration form. You will be contacted by our KYC/AML specialist for any required additional documentation. You will be assigned a SPID at the end of the registration process, but it will be disabled until the KYC/AML review is completed. Once approved, you will be notified and the SPID assigned at registration will be activated. In the meantime, you may continue to use the DEVELOPER_SPID to develop and test your applications.

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 configured 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.

See the link SDK Reference for full documentation of the Rivetz API classes.