Rivetz Android Client

Intent Interface

Introduction

As an alternative to the AIDL (rpc) interface one can issue commands to the Rivetz Adapter through Intent call. Intent call are processed asynchronously and return status and data through Android's onActivityResult() callback.

For example:

public void doSign(String mySPID, String keyName, byte[] thingToSign) {
    Intent intent = new Intent(Rivet.RIVET_INTENT)
        .putExtra(Rivet.EXTRA_INSTRUCT, Rivet.INSTRUCT_SIGN)
        .putExtra(Rivet.EXTRA_SPID, mySPID)
        .putExtra(Rivet.EXTRA_MESSAGE, "My Message to be Signed")
        .putExtra(Rivet.EXTRA_KEYNAME,keyName);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent,Rivet.INSTRUCT_SIGN);
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if (requestCode == Rivet.INSTRUCT_SIGN && resultCode == RESULT_OK) {
        String signature = data.getStringExtra(Rivet.EXTRA_SIGNATURE);
        /* do stuff */
    }
}

Rivetz instruction types and parameters are defined in the Rivetz Stub which is available as an Android Archive library from our Maven Repository at https://code.rivetz.com/. Add this repository in your project and add a dependency to com.rivetz:stub:0.9.1@aar. See GetStarted for examples.

The Rivetz App encapsulates the creation and management of privacy, identity and coin keys. These keys are generated and applied in isolated and protected device hardware called the Trusted Execution Environment (TEE).

Signed Instructions

While the Rivet supports local requests for key applications, this does not protect from rogue applications also applying those keys. In some use cases this may not be important to a service provider, but ideally the instruction is generated server-side, signed and delivered to the Rivet through INSTRUCT_EXECUTE. This ensures the provenance of the request and the response with identity keys established during registration.

Rivetz provides the RivetzEncoder to prepare and sign instructions. The RivetzEncoder is library code provided in a number of languages (initially just Python). RivetzEncoder is not yet released but coming soon.

INSTRUCT_CREATEKEY

Create a key of the specified type. Rivetz stores the key in a local hardware encrypted storage space unique to the Service Provider. Keys are named for future reference.

Extras

EXTRA_INSTRUCT int Rivet.INSTRUCT_CREATEKEY
EXTRA_SPID string The unique identifier assigned to a ServiceProvider by RivetzNet.
EXTRA_KEYTYPE int Rivetz provides a flexible architecture that supports a wide variety of different algorithms, curves, key sizes and usage rules. However, most applications just need keys that are well-protected and are used properly. To simplify the API, we use pre-defined key types that cover the majority of use cases.
EXTRA_KEYNAME string An arbitrary string assigned to a key created in the Rivet. If no value is provided a random name will be generated and returned.
EXTRA_USAGERULES bytearray An array of KeyUsageRule that determines how a key may be applied
EXTRA_CALLID int Optional reference field that is set by the caller and passed back with the result in order to match results.

Returns

EXTRA_CALLID int Optional reference field that is set by the caller and passed back with the result in order to match results.
EXTRA_KEYNAME string An arbitrary string assigned to a key created in the Rivet. If no value is provided a random name will be generated and returned.
EXTRA_RESULTDATA bytearray The raw result data returned from Rivetz call. Includes a device signature if the device id key is available

ResultCode is returned in the intent callback.

Example

Intent intent = new Intent(Rivet.RIVET_INTENT)
    .putExtra(Rivet.EXTRA_INSTRUCT, Rivet.INSTRUCT_CREATEKEY)
    .putExtra(Rivet.EXTRA_SPID, MySPID)
    .putExtra(Rivet.EXTRA_KEYTYPE,Rivet.KEYTYPE_ECDSA_DFLT)
    .putExtra(Rivet.EXTRA_KEYNAME,"My Crypto Key");
if (intent.resolveActivity(getPackageManager()) != null) {
    startActivityForResult(intent,Rivet.INSTRUCT_CREATE_KEY);
}

INSTRUCT_DECRYPT

Decrypts the given data object with the named key

Intent Extras

EXTRA_INSTRUCT int Rivet.INSTRUCT_DECRYPT
EXTRA_SPID String The unique identifier assigned to a ServiceProvider by RivetzNet.
EXTRA_KEYNAME String An arbitrary string assigned to a key created in the Rivet. If no value is provided a random name will be generated and returned.
EXTRA_BLOB byte[] The object to be decrypted in a byte array
EXTRA_CALLID String Reference field that will be passed back with the result in order match requests to results

Returns

EXTRA_CALLID String Optional reference field set by the caller when the Intent was created
EXTRA_BLOB byte[] The decrypted object provided in the request
EXTRA_RESULTCODE int Contains the result status of the request

INSTRUCT_ENCRYPT

Encrypts the given data object with the named key. Generally this is used with a public key loaded through INSTRUCT_LOADKEY.

Encryption using a public key is not necessary to secure. However, the Rivet supports this request for convenience. Encryption with a symmetric key, on the other hand, does need to be shielded from the outside OS.

Intent Extras

EXTRA_INSTRUCT int Rivet.INSTRUCT_ENCRYPT
EXTRA_SPID String The unique identifier assigned to a ServiceProvider by RivetzNet.
EXTRA_KEYNAME String An arbitrary string assigned to a key created in the Rivet. If no value is provided a random name will be generated and returned.
EXTRA_BLOB byte[] The object to be encrypted in a byte array
EXTRA_CALLID String Reference field that will be passed back with the result in order match requests to results

Returns

EXTRA_CALLID String Optional reference field set by the caller when the Intent was created
EXTRA_BLOB byte[] The encrypted object provided in the request
EXTRA_RESULTCODE int Contains the result status of the request

INSTRUCT_GETADDRESS

Retrieve a coin address from a KeyName.

Intent Extras

EXTRA_INSTRUCT int Rivet.INSTRUCT_GETADDRESS
EXTRA_SPID String The unique identifier assigned to a ServiceProvider by RivetzNet.
EXTRA_COIN String Coin type to use when returning the public coin address
EXTRA_CALLID String Reference field that will be passed back with the result in order match requests to results

Returns

EXTRA_CALLID String Optional reference field set by the caller when the Intent was created
EXTRA_RESULTCODE int Contains the result status of the request
EXTRA_COIN_ADDRESS String Coin public address for KeyName

Example



INSTRUCT_GETKEY

Gets the key data from the named key stored in the Rivet. The response intent will contain the public key of the KeyRecord. The ResultData will contain the entire KeyRecord. Private key data will have been encrypted by the device hardware keys.

Intent Extras

EXTRA_INSTRUCT int Rivet.INSTRUCT_GETKEY
EXTRA_SPID string The unique identifier assigned to a ServiceProvider by RivetzNet.
EXTRA_KEYNAME string An arbitrary string assigned to a key created in the Rivet. If no value is provided a random name will be generated and returned.
EXTRA_CALLID int Optional reference field that is set by the caller and passed back with the result in order to match results.

Returns

EXTRA_CALLID int Optional reference field that is set by the caller and passed back with the result in order to match results.
EXTRA_PUBKEY string The public data stored with the key hex encoded
EXTRA_RESULTDATA bytearray The raw result data returned from Rivetz call. Includes a device signature if the device id key is available

ResultCode is returned in the intent callback.

Example

public void doGetKey(String mySPID, String keyName) {
    Intent intent = new Intent(Rivet.RIVET_INTENT)
        .putExtra(Rivet.EXTRA_INSTRUCT, Rivet.INSTRUCT_GETKEY)
        .putExtra(Rivet.EXTRA_SPID, mySPID)
        .putExtra(Rivet.EXTRA_KEYNAME,keyName);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent,Rivet.INSTRUCT_GETKEY);
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if (requestCode == Rivet.INSTRUCT_GETKEY && resultCode == RESULT_OK) {
        String publicKey = data.getStringExtra(Rivet.EXTRA_PUBKEY);
        String privateKey = data.getStringExtra(Rivet.EXTRA_PRVKEY);
        /* do stuff */
    }
}

INSTRUCT_HASH

Compute a hash on the given payload data using the indicated hash alogorithm

Intent Extras

EXTRA_INSTRUCT int Rivet.INSTRUCT_HASH
EXTRA_SPID string The unique identifier assigned to a ServiceProvider by RivetzNet.
EXTRA_HASH_ALGO string Indicates the algorithm to apply when computing a hash
EXTRA_PAYLOAD bytearray A byte array of arbitrary data
EXTRA_CALLID int Optional reference field that is set by the caller and passed back with the result in order to match results.

Returns

EXTRA_CALLID int Optional reference field that is set by the caller and passed back with the result in order to match results.
EXTRA_HASH string The computed hash
EXTRA_RESULTDATA bytearray The raw result data returned from Rivetz call. Includes a device signature if the device id key is available

ResultCode is provided via onActivityResult

Example



INSTRUCT_PAIRDEVICE

Pairing is a key exchange ceremony brokered by Rivetz.net. In this process the device is given the endorsed public key of the Service Provider (given during registration) and the Service Provider is given access to the device.

If a Service Provider ID is not paired with a device, Rivetz will reject incoming requests.

Pairing may trigger the initial provisioning of the TA if this is the first service. The provisioning process takes less than a minute and equips the device with the Rivetz Trusted App

Intent Extras

EXTRA_INSTRUCT int Rivet.INSTRUCT_PAIRDEVICE
EXTRA_SPID String The unique identifier assigned to a ServiceProvider by RivetzNet.
EXTRA_SILENT Boolean If silent is set to true then Rivetz will not display a popup if the pairing status is already complete
EXTRA_CALLID String Reference field that will be passed back with the result in order match requests to results

Returns

EXTRA_CALLID String Optional reference field set by the caller when the Intent was created
EXTRA_RESULTCODE int Contains the result status of the request

Example

private void pairDevice() {
        Intent intent = new Intent("com.rivetz.adapter.PAIR");
        intent.putExtra(Rivet.EXTRA_SPID, MYSPID);
        if (intent.resolveActivity(getPackageManager()) != null) {
            startActivityForResult(intent,Rivet.INSTRUCT_PAIRDEVICE);
        }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        if (requestCode == Rivet.INSTRUCT_PAIRDEVICE) {
            if (resultCode == RESULT_OK) {
                Toast.makeText(this, "PairDevice Success", Toast.LENGTH_LONG).show();
            }
        }
}

INSTRUCT_SIGN

Sign the given data with the named key. The algorithm to be used is established when the key is created.

The instruction takes an arbitrary object as input. This is generally a byte array pass through EXTRA_PAYLOAD, but could also be a simple string using EXTRA_MESSAGE or a hex encoded string using EXTRA_HEXSTRING.

This can be either a string, EXTRA_MESSAGE, or a byte array, EXTRA_PAYLOAD. The signature data is returned in EXTRA_SIGNATURE. The signature can be later verified with INSTRUCT_VERIFY.

Intent Extras

EXTRA_INSTRUCT int Rivet.INSTRUCT_SIGN
EXTRA_SPID string The unique identifier assigned to a ServiceProvider by RivetzNet.
EXTRA_KEYNAME string An arbitrary string assigned to a key created in the Rivet. If no value is provided a random name will be generated and returned.
EXTRA_PAYLOAD bytearray A byte array of arbitrary data
EXTRA_MESSAGE string A simple text string provided for encryption or signature
EXTRA_HEXSTRING string A byte array that has been encoded as a string by rendering each byte in 2 character hex notation.
EXTRA_CALLID int Optional reference field that is set by the caller and passed back with the result in order to match results.

Returns

EXTRA_CALLID int Optional reference field that is set by the caller and passed back with the result in order to match results.
EXTRA_SIGNATURE bytearray A byte array of signature data
EXTRA_RESULTDATA bytearray The raw result data returned from Rivetz call. Includes a device signature if the device id key is available

ResultCode is provided via onActivityResult

Example

public void doSign(String mySPID, String keyName, byte[] thingToSign) {
    Intent intent = new Intent(Rivet.RIVET_INTENT)
        .putExtra(Rivet.EXTRA_INSTRUCT, Rivet.INSTRUCT_SIGN)
        .putExtra(Rivet.EXTRA_SPID, mySPID)
        .putExtra(Rivet.EXTRA_MESSAGE, "My Message to be Signed")
        .putExtra(Rivet.EXTRA_KEYNAME,keyName);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent,Rivet.INSTRUCT_SIGN);
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if (requestCode == Rivet.INSTRUCT_SIGN && resultCode == RESULT_OK) {
        String signature = data.getStringExtra(Rivet.EXTRA_SIGNATURE);
        /* do stuff */
    }
}

INSTRUCT_SIGNTXN

Sign a coin transaction with the named coin (wallet) key

Intent Extras

EXTRA_INSTRUCT int INSTRUCT_SIGNTXN
EXTRA_SPID string The unique identifier assigned to a ServiceProvider by RivetzNet.
EXTRA_KEYNAME string An arbitrary string assigned to a key created in the Rivet. If no value is provided a random name will be generated and returned.
EXTRA_COIN string Indicates the signing algorithm and block chain infrastructure of the coin transaction. If unspecified BTC is the default.
EXTRA_TOPUB String Virtual coin public address to send coins to
EXTRA_AMT string Floating point value given as a string indicating the amount of coin to tender in a transaction
EXTRA_FEE string The miner fee that is declared for a coin transaction
EXTRA_TRANS String JSON String of input transactions to redeem with this transaction
EXTRA_CALLID int Optional reference field that is set by the caller and passed back with the result in order to match results.

Returns

EXTRA_CALLID int Optional reference field that is set by the caller and passed back with the result in order to match results.
EXTRA_SIGNED String Hex string of signed transaction
EXTRA_SIGNDONE Boolean Future use: Multi-sig will return false if more signing is required
EXTRA_RESULTDATA bytearray The raw result data returned from Rivetz call. Includes a device signature if the device id key is available

ResultCode is provided via onActivityResult

Example

public void doSignTX(String mySPID, String keyName, String ToAddress, String SpendAmount, String Inputs) {
    Intent intent = new Intent(Rivet.RIVET_INTENT)
        .putExtra(Rivet.EXTRA_INSTRUCT, Rivet.INSTRUCT_SIGNTXN)
        .putExtra(Rivet.EXTRA_SPID, mySPID)
        .putExtra(Rivet.EXTRA_KEYNAME, keyName)
        .putExtra(Rivet.EXTRA_VC, "BTC")
        .putExtra(Rivet.EXTRA_TOPUB, ToAddress)
        .putExtra(Rivet.EXTRA_AMT, SpendAmount)
        .putExtra(Rivet.EXTRA_FEE, Fee)
        .putExtra(Rivet.EXTRA_TRANS, Inputs);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent,Rivet.INSTRUCT_SIGNTXN);
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if (requestCode == Rivet.INSTRUCT_SIGNTXN && resultCode == RESULT_OK) {
        String signedTrans = data.getStringExtra(Rivet.EXTRA_SIGNED);
        /* Sign Transaction Successful - Send to virtual coin network */
    }
}

INSTRUCT_VERIFY

Verify a signature for the give payload of data. Result code: Result of the verification is provide in EXTRA_VERIFIED.

Note, you must provide a key that is of a type capable of signing.

Intent Extras

EXTRA_INSTRUCT int Rivet.INSTRUCT_VERIFY
EXTRA_SPID string The unique identifier assigned to a ServiceProvider by RivetzNet.
EXTRA_KEYNAME string An arbitrary string assigned to a key created in the Rivet. If no value is provided a random name will be generated and returned.
EXTRA_SIGNATURE bytearray A byte array of signature data
EXTRA_PAYLOAD bytearray A byte array of arbitrary data
EXTRA_CALLID int Optional reference field that is set by the caller and passed back with the result in order to match results.

Returns

EXTRA_CALLID int Optional reference field that is set by the caller and passed back with the result in order to match results.
EXTRA_VERIFIED boolean Indicates the result of a signature verification test
EXTRA_RESULTDATA bytearray The raw result data returned from Rivetz call. Includes a device signature if the device id key is available

ResultCode is provided via onActivityResult

Developer Guide