Remote Signaling API

Remote Signaling API

Android applications which have exchanged keys with CommCare can signal for CommCare to perform certain actions using BroadcastIntents.

Prerequisites

In order to use this API, you'll need

• An application installed in CommCare
• An encryption key and a key id that you got from the Key Exchange API

Workflow

Calling applications can trigger remote behaviors by creating intents with the appropriate action and passing arguments as an encrypted payload which will be unmarshalled into a Bundle.

Android's security implementation doesn't provide chaining ciphers for RSA encryption. As such, calling applications will encrypt the passed bundle with an AES key, and pass that key (encrypted with their public key) with the signal.

Currently CommCare doesn't provide the ability to receive a response from the action.

Calling Intent Structure

**Action: ** org.commcare.dalvik.api.action.ExternalAction

**Extras (Details on encryption formats are available at the end of the document): **

• commcare_sharing_key_id[string] - Your app's sharing api ID
• commcare_sharing_key_symetric[byte[]] - The AES symetric key used to encrypt the callout as encrypted by your public key
• commcare_sharing_key_callout[byte[]] - The encrypted callout bundle itself.

Available Callouts

The action you are signalling comes as packed in the Bundle you pass with the callout. The available callouts that you can perform are as follows, with parameters to the bundle outlined

• Log In (commcareaction->login)
  • username
  • password

Note that this login will only work locally. That is to say: The user needs to have logged into CommCare before through the application and have all credentials, etc already synced to your device

• Sync (commcareaction->sync)

Sample Code

An example of this implementation is maintained in the code here

Encryption Details

To send your bundle to CommCare the process is

• Create a bundle with your callout arguments
• Marshall that object into a byte[] with a parcel at data position 0
• Create a new, random AES key and encode it into a byte[]
• Encrypt the encoded AES key with the public key provided to you by CommCare
• Encrypt your marshalled callout using the AES key that you have generated
• Pass those three arguments through the intent as outlined above