Authentication via Key Exchange

Key Exchange API

In order to use some API's, CommCare requires you to perform an authenticated exchange to hand off keys to secure potentially sensitive information

Prerequisites

In order to use this API, you'll need

• An application installed in CommCare

Workflow

Calling applications will request an intent for a response. CommCare will inform the user that your application has requested the ability to communicate securely and prompt the user to accept. If the user accepts, the calling application will receive a success response with a payload containing a private key. You can use this key with the Remote Signaling API to send CommCare information securely.

Calling Intent Details

**Action: ** org.commcare.dalvik.action.CommCareKeyAccessRequest

**Extras: ** [Optional] commcare_sharing_caller_key, An RSA Public Key (described below) from your app if you want to be able to receive information from CommCare

Response Intent Details

Extras:

• commcare_sharing_key_id[string] - An id that you should send with signalling requests to identify that data was encrypted with your key
• commcare_sharing_key_payload[byte[]] - An RSA public key that you can use to encrypt data that you submit to CommCare in the future

Example Code

• Callout to CommCare to get the public key -

Intent intent = new Intent("org.commcare.dalvik.action.CommCareKeyAccessRequest");
startActivityForResult(intent, KEY_INTENT_REQUEST_CODE); 

• Get the key from callout response -

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if (requestCode == KEY_INTENT_REQUEST_CODE) {
        if (resultCode == Activity.RESULT_OK) {
            String ccKey = data.getExtras().getString("commcare_sharing_key_id");
            // store the key for future usage in CC callouts
        } else {
            // User didn't grant access, show a relevant message to the user
        }
    }
}

Data Format Details

RSA public keys are exchanged as X.509 encoded bytes.