README.md 10.7 KB
Newer Older
Lily Tsai's avatar
Lily Tsai committed
1
# Table of contents
2
3
* [Javadocs](/docs)
* [The exampleapp module](https://gitlab.rts.mpi-sws.org/encounters/ebc/tree/master/exampleapp) demonstrates the below configuration, initialization, and usage instructions
Lily Tsai's avatar
README    
Lily Tsai committed
4
* [Motivation: What is Encounter-based Communication?](#encounter-based-communication)
Lily Tsai's avatar
Lily Tsai committed
5
6
7
* [Necessary Setup](#necessary-setup)
    * [Initializing the EbC Agent ](#initializing-the-ebc-agent)
    * [EbC User Accounts](#ebc-user-accounts)
Lily Tsai's avatar
Lily Tsai committed
8
9
10
11
* [Usage](#usage)
    * [Encounter Formation and Confirmation](#encounter-formation-and-confirmation)
    * [Direct Communication over Encounters](#direct-communication-over-encounters)

Lily Tsai's avatar
Lily Tsai committed
12
******
Lily Tsai's avatar
Lily Tsai committed
13

Lily Tsai's avatar
nit    
Lily Tsai committed
14
# Encounter-Based Communication
Lily Tsai's avatar
Lily Tsai committed
15
16
<h4 align="center">Add secure, encounter-based communication to your Android applications.</h4>

Lily Tsai's avatar
Lily Tsai committed
17
18
19
This Android library implements _Encounter-based Communication_, a communication paradigm that is based on the notion of an _encounter_, or a period of co-location. EbC enables users to follow up after a meeting; share commentary, advice, or content about an attended event or a
visited place; identify people with shared interests at a large
event; confirm that they have met at a given place and time;
Lily Tsai's avatar
Lily Tsai committed
20
and use local services or control their present physical environment. EbC enables this type of communication securely,
Lily Tsai's avatar
Lily Tsai committed
21
22
without requiring participants to exchange contact details or reveal personal information.
More formally, EbC provides the following 4 properties:
Lily Tsai's avatar
Lily Tsai committed
23

Lily Tsai's avatar
readme    
Lily Tsai committed
24
25
26
27
1. Implicit naming: Communication is possible without the need to pair devices a priori or manually exchange contact details, identifiers, or keys.
2. Persistent addressing: Communication is possible both during and after a period of co-location.
3. Privacy: Parties may de-anonymize, re-identify, or track users/devices only if explicitly permitted.
4. Security: Users can authenticate communication partners as people or resources they have encountered at a specific time and place; message exchanges should be confidential, with message integrity protected.
Lily Tsai's avatar
Lily Tsai committed
28

Lily Tsai's avatar
Lily Tsai committed
29
The EbCLibrary module exposes an interface to control encounter discovery and send/receive direct messages to/from these encounters. Message recipients are selected by a number of _constraints_, including time, place, and length of the encounter.
Lily Tsai's avatar
Lily Tsai committed
30

Lily Tsai's avatar
Lily Tsai committed
31
32
## Necessary Setup

Lily Tsai's avatar
hm    
Lily Tsai committed
33
34
### Integration

Lily Tsai's avatar
Lily Tsai committed
35
36
In Android Studio, add the following in `build.gradle`
```
Lily Tsai's avatar
Lily Tsai committed
37
38
39
40
repositories {
    maven { url "https://dl.bintray.com/tslilyai/EncounterBasedCommunication" }
}
dependencies {
Lily Tsai's avatar
Lily Tsai committed
41
    compile 'org.mpisws:ebclibrary:0.1.0.2'
Lily Tsai's avatar
Lily Tsai committed
42
}
Lily Tsai's avatar
Lily Tsai committed
43
44
45
46
```

Alternatively, the source code can be downloaded and included as a separate module in an Android project.

Lily Tsai's avatar
Lily Tsai committed
47
EbC requires that the device have BLE capabilities and Bluetooth enabled. Furthermore, the user must allow access to location services. This requires the application to request Bluetooth and location access upon start (see `MainActivity.java` in the `testapp` module for an example). In your `AndroidManifest`, you must also include the following permissions:
Lily Tsai's avatar
Lily Tsai committed
48
49
50
51
```
    <uses-permission android:name="android.permission.BLUETOOTH" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
Lily Tsai's avatar
Lily Tsai committed
52
    <uses-permission android:name="android.permission.INTERNET" />
Lily Tsai's avatar
Lily Tsai committed
53
54
55
    <uses-feature android:name="android.hardware.bluetooth_le" />
```

Lily Tsai's avatar
hm    
Lily Tsai committed
56
57
### Initializing the EbC Agent

Lily Tsai's avatar
Lily Tsai committed
58
The EncounterBasedCommunication agent is initialized with the application context and a special config file (placed in `res/raw`). Please email `ebc@mpi-sws.org` to receive this file, which contains a key necessary to authenticate the application as an EbC application with the backend service. Initialization looks as follows:
Lily Tsai's avatar
Lily Tsai committed
59

Lily Tsai's avatar
docs    
Lily Tsai committed
60
```java
Lily Tsai's avatar
Lily Tsai committed
61
EncounterBasedCommunication ebc = EncounterBasedCommunication.getInstance();
Lily Tsai's avatar
Lily Tsai committed
62
ebc.initialize(getApplicationContext(), R.raw.ebc_config);
Lily Tsai's avatar
Lily Tsai committed
63
64
```

65
66
### EbC User Accounts 
In order to use any EbC functionality, the application must have the user sign into their EbC account. Each EbC account is tied to a Google account: the application must acquire a Google OAuth token for the user, which is passed as an argument to the EbC call `loginAccountWithGoogle(googletoken)`. A typical example of this workflow looks as follows:
Lily Tsai's avatar
Lily Tsai committed
67

Lily Tsai's avatar
docs    
Lily Tsai committed
68
69
```java
/* 
70
 * Log in the user; this procedure will also create an account for the user if her account does not yet exist.
Lily Tsai's avatar
docs    
Lily Tsai committed
71
 */
Lily Tsai's avatar
Lily Tsai committed
72
73
74
75
76
77
78
public void loginUser() {
    String googletoken = GoogleToken.getToken(); // application must implement Google token acquisition
    if (googletoken != null) {
        ebc.getUserAccountClient().loginAccountWithGoogle(googletoken);
    }
}

Lily Tsai's avatar
docs    
Lily Tsai committed
79
/* 
80
 * Log out of an EbC account and prevent access to any ebc functionality.
Lily Tsai's avatar
docs    
Lily Tsai committed
81
82
 * The user must then provide another googletoken the next time she wishes to log in.
 */
Lily Tsai's avatar
Lily Tsai committed
83
84
ebc.getUserAccountClient().signOut();

Lily Tsai's avatar
docs    
Lily Tsai committed
85
86
87
88
/* 
 * Delete an EbC account 
 * Note that this does *not* delete the encounter database stored on the device (as the database is device, and not user, specific).
 */ 
Lily Tsai's avatar
Lily Tsai committed
89
90
91
ebc.getUserAccountClient().deleteAccount();
```

92
93
Per-user EbC account credentials are used to encrypt the encounter database on the phone and hold the user accountable for any messages sent to encounters using the EbC library. Due to the per-device nature of the encounter database, it is expected that only one account use the application for every device.

94
_Note: a `Security Exception` will be thrown if any EbC actions are attempted when the user is not logged in or the EbC instance is not initialized._
Lily Tsai's avatar
readme    
Lily Tsai committed
95
96

## Usage
Lily Tsai's avatar
Lily Tsai committed
97
98
99
_After initializing an EbC agent and logging into a user account_, the application can access its various components to control encounter formation (`IEncounterFormationClient`) and handle direct messaging (`ICommunicationClient`).

These two clients are accessed via calls to
Lily Tsai's avatar
docs    
Lily Tsai committed
100
```java
Lily Tsai's avatar
Lily Tsai committed
101
102
103
ebc.getSDDRClient();
ebc.getCommunicationClient();
```
Lily Tsai's avatar
readme    
Lily Tsai committed
104

Lily Tsai's avatar
Lily Tsai committed
105
### Encounter Formation and Confirmation
Lily Tsai's avatar
Lily Tsai committed
106
107
Once a user is logged in, she can begin to form and confirm encounters (allowing her to later communicate over these encounters). A typical workflow is as follows:

Lily Tsai's avatar
docs    
Lily Tsai committed
108
```java
Lily Tsai's avatar
Lily Tsai committed
109
110
111
112
113
// start the encounter formation service running in the background
ebc.getSDDRClient().startFormingEncounters();

if (device_has_network) {
    // confirm all unconfirmed encounters (opening communication channels for these encounters)
Lily Tsai's avatar
Lily Tsai committed
114
    // over the network. This requires WiFi or data to succeed.
Lily Tsai's avatar
Lily Tsai committed
115
116
117
118
    ebc.getSDDRClient().confirmAndCommunicateUsingNetwork();
} else if (want_to_communicate_over_bluetooth) {
    // confirm all unconfirmed encounters (opening communication channels for these encounters)
    // over a Bluetooth connection. This requires the other end of the encounter to be within range
Lily Tsai's avatar
Lily Tsai committed
119
    // and be available to connect over Bluetooth.
Lily Tsai's avatar
Lily Tsai committed
120
121
122
123
124
125
126
127
128
129
    ebc.getSDDRClient().confirmAndCommunicateUsingBLE();
} else {
    // all encounters will remain unconfirmed (and un-communicable) in 
    // the device's database. Encounter confirmation over the network 
    // should be initialiated when network access becomes available to
    // enable communication with prior encounters.
}

....

Lily Tsai's avatar
docs    
Lily Tsai committed
130
131
132
133
// if application wishes to stop encounter confirmation 
// (over either the network or BLE)
ebc.getSDDRClient().disableConfirmation();

Lily Tsai's avatar
Lily Tsai committed
134
135
136
// when application wishes to stop encounter formation
ebc.getSDDRClient().stopFormingEncounters();
```
Lily Tsai's avatar
Lily Tsai committed
137
138

### Direct Communication over Encounters
Lily Tsai's avatar
Lily Tsai committed
139
Logged-in users can communicate over all confirmed encounters in the device's encounter database.
Lily Tsai's avatar
docs    
Lily Tsai committed
140
141
142
A typical communication workflow to send messages is as follows:

```java
Lily Tsai's avatar
docs    
Lily Tsai committed
143
/* The EbC CommunicationClient allows you to send messages to your encounters, specified by time/place or path 
Lily Tsai's avatar
docs    
Lily Tsai committed
144
145
146
147
148
149
150
 */ 

/* EXAMPLE: SENDING TO ENCOUNTERS WITHIN A SPECIFIED SPACE-TIME REGION */
EncounterQueryConstraint encounterConstraintSpaceTime = new SpaceTimeIntersectConstraint(
    CURRENT_TIME_MS() - MIN_TO_MS(100) /*starttime*/, 
    CURRENT_TIME_MS() /*endtime*/, 
    MIN_TO_MS(5) /*overlap duration*/, 
151
    new SpaceRegion(12003 /*latitude*/, 4000 /*longitude*/, 100 /*radius in meters*/),
Lily Tsai's avatar
docs    
Lily Tsai committed
152
153
154
155
    null /*non-null values constrains to encounters overlapping with the specified time value*/);

/* EXAMPLE: SENDING TO ENCOUNTERS THAT OCCURRED ON YOUR PATH (TRAJECTORY) */
EncounterQueryConstraint encounterConstraintTrajectory = new TrajectoryConstraint(
Lily Tsai's avatar
Lily Tsai committed
156
157
158
159
                        System.currentTimeMillis()-DAYS2MS(1), System.currentTimeMillis(),
                        MIN2MS(10), 
                        null // don't factor in causality,
                        false);
Lily Tsai's avatar
docs    
Lily Tsai committed
160

Lily Tsai's avatar
Lily Tsai committed
161
162
163
164
// Note that this will require the network to be available, as messages through encounters 
// are sent via a secure cloud service
getEbC(this).getCommunicationClient().sendDirectMessageToEncounters("msg_text", encounterConstraintTrajectory, true);
getEbC(this).getCommunicationClient().sendMultiHopMessageToEncounters("msg_text", encounterConstraintSpaceTime, null, false);
Lily Tsai's avatar
docs    
Lily Tsai committed
165
166
```

Lily Tsai's avatar
Lily Tsai committed
167
168
169
170
171
You can also get all your unread messages from various encounters (processed asynchronously). Note that
there are two types of messages, ones sent via encounters, and others sent via 
private channels you have opened up with other users. These private channels are created when you
respond to a message received over an encounter. Other types of messages are used as metadata only,
and should be ignored:
Lily Tsai's avatar
docs    
Lily Tsai committed
172
```java
Lily Tsai's avatar
Lily Tsai committed
173
174
175
176
177
178
179
180
181
182
183
184
Client.GetReceivedMessagesCallback callback = new ESClient.GetReceivedMessagesCallback() {
	@Override
	public void processReceivedMessages(List<ReceivedMessageWrapper> unreadMsgs) {
		for (ReceivedMessageWrapper msg : unreadMsgs) {
			String msgText;
			switch (msg.getMsgType()) {
				case ENCOUNTER_FORWARDING_MESSAGE:
					EncounterForwardingMessage encounterForwardingMessage = msg.getEncounterForwardingMessage();
					// you can read the message
					msgText = encounterForwardingMessage.getMsgText();
					break;
				case PRIVATE_MESSAGE:
Lily Tsai's avatar
Lily Tsai committed
185
186
					PrivateMessage privateMessage = msg.getPrivateMessage();
					msgText = privateMessage.getMsgText();
Lily Tsai's avatar
Lily Tsai committed
187
188
189
190
191
192
193
194
195
196
197
198
199
					break;
				default: // skip non-messaging type messages used as metadata 
					msgText = "";
					break;
			}
			// you can get the topic text, i.e. the EncounterID to which this message corresponds
			String whichEncounter = msg.getEncounterID();
			// you can also report offensive text
			if (isOffensive(msgText)) {
				getEbC(getApplicationContext()).getCommunicationClient().reportMsg(msg.getCursor(), Reason.OFFENSIVECONTENT);
			}
		}
	}
200
};
Lily Tsai's avatar
Lily Tsai committed
201
getEbC(this).getCommunicationClient().getUnreadMsgs(callback);
Lily Tsai's avatar
docs    
Lily Tsai committed
202
203
204
```

```java
Lily Tsai's avatar
docs    
Lily Tsai committed
205
/* You can also block certain encounters from messaging you by specifying a constraint on which encounters to block 
Lily Tsai's avatar
docs    
Lily Tsai committed
206
207
208
209
210
211
212
 */
ebc.getCommunicationClient().blockEncounters(encounterConstraintSpaceTime);

/* 
 * And report received messages as spam or unwanted
 */
List<EbCMsgContents> unreadMsgs = ebc.getCommunicationClient().getAllUnreadMsgs();
213
214
215
for (EbCMsgContents esMessage : unreadMsgs) {
    if (is_offensive(esMessage.getMsgText())) {
        ebc.getCommunicationClient().reportMsg(esMessage, Reason.OFFENSIVECONTENT);
Lily Tsai's avatar
docs    
Lily Tsai committed
216
217
218
    }
}
```