Chat Client Implementation Notes

Overview

This page contains implementation notes for iOS and Android chat applications wishing to add ChatSecure-Push push messaging.

Our intention is that adding ChatSecure-Push's capabilities to your application should have no visible impact to your users until a push message arrives.

Accounts

You should create a single ChatSecure-Push account for every application install. APNS and GCM issue one push token per application install so your app will use a single ChatSecure-Push account even if it allows the user to be present as multiple chat (XMPP etc.) accounts.

Devices

You should request an APNS or GCM push token on each application launch and notify ChatSecure-Push by creating or updating a Device entity.

Whitelist Tokens

You should request batches of Whitelist tokens from the server and distribute them to users you trust to send you push messages. A good time to do this might be during the initialization of a "conversation" view with a peer. Whitelist tokens should be sent and received automatically without any user interaction.

They should be exchanged via an end-to-end secure channel, such as a specially defined OTR TLV when you enter an OTR session. The token exchange process should also include information about the REST API endpoint, so the receiver knows where the POST your token.

These tokens can also be used in conjunction with the XEP-0357 push notifications XMPP extension, but we will focus on that in a future document.

OTR TLV

We have chosen the following OTR TLVs for exchange of Whitelist token data:

0x01A4 = Whitelist token exchange

JSON Whitelist Token Exchange

{
	"endpoint": "https://push.chatsecure.org/api/v1/message",
	"tokens": ["1daf13e01982d3029cf09ae3d027a62923f0f2b6"],
	"date_expires": ["yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z"],
	"extra_data": "anything goes!"
}

Whitelist Token Exchange Flow

Sender:

1. Request batch of tokens from server.
2. Establish OTR session with a friend.
3. Create JSON containing one or more whitelist tokens.
4. Send the JSON data blob inside an OTR TLV (type=0x01A4)

Receiver:

1. Establish OTR session with friend.
2. Receive JSON blob within OTR TLV (type=0x01A4)
3. Extract whitelist tokens and endpoint from JSON blob, save them locally, associated with your friend.
4. When desired, send a push to your friend by POSTing a token to the designated endpoint.

Push Messages

In its current form, ChatSecure-Push messages are best employed as a "knock" informing an offline user that someone would like to chat with them. As such you'd ideally present UI for "Knocking" an offline user from your app's "conversation" view.