Class Gateway

void onPause()

Pause the monitor thread. Block the monitor thread if it was unblocked and running. The thread will remain blocked until onResume() is called.

void onResume()

Run/resume the monitor thread. This method starts/unblocks the monitor thread if it was blocked or not running. If the thread does not exist upon calling onResume(), onResume() will call onStart() to create the thread. The thread will remain running until onPause() is called.

void onStart()

Create the monitor thread if it did not exist. Note that this does not start the thread. Use onResume() to do that

void onStop()

Stop and destroy the monitor thread if it exists. If the thread is running upon entry in this method, this method will (safely) cause the thread to stop execution before destroying it.

void updateBlokchainState()

Update the local blockchain state. Fetches the relevant blockchain state from the network and updates the local cache for certificates and UTXOs.

void seed()

Seeds the private key pool and generates a mnemonic recovery string. Should be run once a Gateway is created before other operations.

Persona createPersona(String name, String subName, SecurityLevel securityLevel)

Creates a new persona in the Gateway with the given identity information and security level. This persona will be returned immediately, regardless of its status on the blockchain. It can only be set as the active persona once its status is CONFIRMED.

Parameters:

name - the persona name, an arbitrary user set value

subName - the persona sub-name, an arbitrary user set value

securityLevel - the cipher strength to use for the persona

Returns:

The newly created persona

void setActivePersona(Persona persona)

Sets the active persona in the Gateway. Most operations in Gateway require an active persona. Gateway keeps track of the active persona internally as state, rather than passing the target persona in to various methods. Therefore it is necessary to change the active persona before any encrypt, sign, verify, decrypt, or contact-related methods.

Parameters:

persona - the persona to set active. The full list of personas the Gateway is aware of is available through getPersonas().

void Persona getActivePersona()

Returns the current active persona in the Gateway, if one has been set. When the Gateway is created, if there is at least one mature persona in it, then one of them will be activated even if setActivePersona has not been invoked yet. Users are encouraged to not rely on this mechanic however as the chosen persona is not deterministic from the user point of view.

Returns:

The current active persona

Raises:

NoActivePersona - if there is no active persona yet

boolean maturePersonaExists()

Checks to see if the Gateway has a mature persona within it. If any of the personas are mature, it will return true.

Returns:

true if there is at least 1 mature persona in the Gateway

ArrayList<Persona> getPersonas()

Returns all personas in the Gateway

Returns:

an ArrayList of Personas regardless of confirmation state

void replaceCertificate()

Revoke and replace existing current certificate for given persona on the blockchain. This method creates a new set of public/private key pairs that will, over time, be used for encryption/decryption and signing/verifying.

It is good practice to replace certificates periodically in order to provide forward security for subsequently encrypted/signed data. Note that the certificate replacement happens asyncronous to this call, however when it happens, it will be reflected locally atomically. That is, suppose you call this method while encrypting a stream of data. Then at some point in the future, the new certificate will be confirmed on the blockchain, and with respect to the data stream encryption, there will be a point at which the old certificate will stop being used and the new will begin to be used. This happens transparently to the developer’s code in the sense that there is otherwise no programmatic differentiation that the developer make in order to start using the new certificate; it happens automatically subject to confirmation on the blockchain.

Note: this method blocks on network operations, so should not be called on the main/UI thread. Call this method in, for example, an AsyncTask.

Contact createContact(String name, String subName, Uri uri)

Creates a new contact for the current active persona with the given identity information. The contact Uri must be reachable on the blockchain.

Parameters:

name - the contact name, an arbitrary user set value

subName - the contact sub-name, an arbitrary user set value

uri - the contact Uri, a digital identification that in v2.4 is a reference to multiple blockchain transactions holding the contact public key information.

Returns:

The created contact

ArrayList<Contact> getContacts()

Returns all contacts for the current active persona.

Returns:

an ArrayList of Contact for the active persona

deletePersona(Persona persona)

Deletes a Persona from the Gateway. It must not be the active one.

Parameters:

persona - the persona to remove.

deleteContact(Contact contact)

Deletes a Contact from the Gateway.

Parameters:

contact - the contact to remove.

renamePersona(Persona persona, String name, String subName)

Renames the Persona name and sub name

Parameters:

persona - the Persona to rename

name - the new name

subName - the new sub name

renameContact(Contact contact, String name, String subName)

Renames the Contact name and sub name

Parameters:

contact - the Contact to rename

name - the new name

subName - the new sub name

byte[] sign(byte[] data, CharEncoding encoding, boolean isApproval)

Signs the clear text data

Parameters:

data - a byte array holding the data to sign, in any format

encoding - the character encoding of the data

isApproval - true if this signature is an approval type

Returns:

A signed message

byte[] addSignature(byte[] data, boolean isApproval)

Adds the current persona’s signature to an existing signed data. Unlike sign() the encoding information is not passed in to the method, since the message itself is not touched. Only a new signature is appended.

Parameters:

data - a byte array holding a signed message

isApproval - true if this signature is an approval type

Returns:

An updated signed message

String encrypt(ArrayList<Contact> contacts, byte[] clearText)

Encrypts the cleartext for the provided contacts, returning an XML string representation.

Parameters:

contacts - the list of contacts for whom to encrypt the text

clearText - the text to encrypt

Returns:

A String representation of the encrypted text. This is an XML serialization format used by Keychain.

String signThenEncrypt(ArrayList<Contact> contacts, byte[] clearText)

Signs the clear text and then encrypts it for the provided contacts

Parameters:

contacts - the list of contacts for whom to encrypt the text

clearText - the text to sign and encrypt

Returns:

A String representation of the signed and encrypted text. This is an XML serialization format used by Keychain.

byte[] decrypt(String cipherText)

Decrypts the cipher text into a byte[].

Parameters:

cipherText - the encrypted text

Returns:

The plaintext as a byte[]

byte[] decryptThenVerify(String cipherText)

Decrypts the cipher text into a byte[] that represents the original data passed in to encrypt(). This method will fail and return an empty byte[] if any of the signatures fail to verify, or if the current persona was not either the creator or a target contact for the message.

Parameters:

cipherText - the encrypted text

Returns:

A byte[] representing the cleartext

String decryptThenVerifyString(String cipherText)

This method does exactly what decryptThenVerify() does, but then converts the byte[] result to a UTF-8 string and returns it.

Parameters:

cipherText - the encrypted text

Returns:

The decrypted text as a UTF-8 String

VerificationResult verify(byte[] signedData)

Verifies the signed data and returns a VerificationResult with detailed information on all signatures

Parameters:

signedData - the signed data

Returns:

A VerificationResult holding signature verification details

void setRefreshable(Refreshable refresher)

Sets the Refreshable associated with the internal monitor thread

Parameters:

refresher - the new Refreshable

Context initializeDb(String configPath, String dbPath, String dropSqlPath, String createSqlPath)

Creates a Keychain Context and validates the license. The Context is required for Gateway construction, meaning this method must be called before any other operations. Valid paths to config (keychain.cfg) and the Keychain DB must be passed.

Parameters:

configPath - the path to the Keychain configuration file (e.g. keychain.cfg)

dbPath - the path to the Keychain DB

dropSqlPath - the path to an SQL file that drops all Keychain tables in an existing DB

createSqlPath - the path to an SQL file that recreates Keychain tables

Returns:

A Context object holding the configuration and values passed in