1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
# Push notifications as a Nextcloud client device
## Checking the capabilities of the Nextcloud server
In order to find out if notifications support push on the server you can run a request against the capabilities endpoint: `/ocs/v2.php/cloud/capabilities`
```
{
"ocs": {
...
"data": {
...
"capabilities": {
...
"notifications": {
"push": [
...
"devices"
]
}
}
}
}
}
```
## Subscribing at the Nextcloud server
1. **Only on first registration on the server** The device generates a `rsa2048` key pair (`devicePrivateKey` and `devicePublicKey`).
2. The device generates the `PushToken` for *Apple Push Notification Service* (iOS) or *Firebase Cloud Messaging* (Android)
3. The device generates a `sha512` hash of the `PushToken` (`PushTokenHash`)
4. The device then sends the `devicePublicKey`, `PushTokenHash` and `proxyServerUrl` to the Nextcloud server:
```
POST /ocs/v2.php/apps/notifications/api/v3/push
{
"pushTokenHash": "{{PushTokenHash}}",
"devicePublicKey": "{{devicePublicKey}}",
"proxyServer": "{{proxyServerUrl}}"
}
```
### Response
The server replies with the following status codes:
| Status code | Meaning |
| ----------- | ---------------------------------------- |
| 200 | No further action by the device required |
| 201 | Push token was created/updated and **needs to be sent to the `Proxy`** |
| 400 | Invalid device public key; device does not use a token to authenticate; the push token hash is invalid formatted; the proxy server URL is invalid; |
| 401 | Device is not logged in |
#### Body in case of success
In case of `200` and `201` the reply has more information in the body:
| Key | Type | |
| ---------------- | ------------ | ---------------------------------------- |
| publicKey | string (512) | rsa2048 public key of the user account on the instance |
| deviceIdentifier | string (128) | unique identifier encrypted with the users private key |
| signature | string (512) | base64 encoded signature of the deviceIdentifier |
#### Body in case of an error
In case of `400` the following `message` can appear in the body:
| Error | Description |
| ------------------------ | ---------------------------------------- |
| `INVALID_PUSHTOKEN_HASH` | The hash of the push token was not a valid `sha512` hash. |
| `INVALID_SESSION_TOKEN` | The authentication token of the request could not be identified. Check whether a password was used to login. |
| `INVALID_DEVICE_KEY` | The device key does not match the one registered to the provided session token. |
| `INVALID_PROXY_SERVER` | The proxy server was not a valid https URL. |
## Unsubcribing at the Nextcloud server
When an account is removed from a device, the device should unregister on the server. Otherwise the server sends unnecessary push notifications and might be blocked because of spam.
The device should then send a `DELETE` request to the Nextcloud server:
```
DELETE /ocs/v2.php/apps/notifications/api/v3/push
```
### Response
The server replies with the following status codes:
| Status code | Meaning |
| ----------- | ---------------------------------------- |
| 200 | Push token was not registered on the server |
| 202 | Push token was deleted and **needs to be deleted from the `Proxy`** |
| 400 | Device does not use a token to authenticate |
| 401 | Device is not logged in |
#### Body in case of an error
In case of `400` the following `message` can appear in the body:
| Error | Description |
| ----------------------- | ---------------------------------------- |
| `INVALID_SESSION_TOKEN` | The authentication token of the request could not be identified. |
## Subscribing at the Push Proxy
The device sends the`PushToken` as well as the `deviceIdentifier`, `signature` and the user´s `publicKey` (from the server´s response) to the Push Proxy:
```
POST /devices
{
"pushToken": "{{PushToken}}",
"deviceIdentifier": "{{deviceIdentifier}}",
"deviceIdentifierSignature": "{{signature}}",
"userPublicKey": "{{userPublicKey}}"
}
```
### Response
The server replies with the following status codes:
| Status code | Meaning |
| ----------- | ---------------------------------------- |
| 200 | Push token was written to the databse |
| 400 | Push token, public key or device identifier is malformed, the signature does not match |
| 403 | Device is not allowed to write the push token of the device identifier |
| 409 | In case of a conflict the device can retry with the additional field `cloudId` with the value `{{userid}}@{{serverurl}}` which allows the proxy to verify the public key and device identifier belongs to the given user on the instance |
## Unsubscribing at the Push Proxy
The device sends the `deviceIdentifier`, `deviceIdentifierSignature` and the user´s `publicKey` (from the server´s response) to the Push Proxy:
```
DELETE /devices
{
"deviceIdentifier": "{{deviceIdentifier}}",
"deviceIdentifierSignature": "{{signature}}",
"userPublicKey": "{{userPublicKey}}"
}
```
### Response
The server replies with the following status codes:
| Status code | Meaning |
| ----------- | ---------------------------------------- |
| 200 | Push token was deleted from the database |
| 400 | Public key or device identifier is malformed |
| 403 | Device identifier and device public key didn't match or could not be found |
## Pushed notifications
The pushed notifications is defined by the [Firebase Cloud Messaging HTTP Protocol](https://firebase.google.com/docs/cloud-messaging/http-server-ref#send-downstream). The sample content of a Nextcloud push notification looks like the following:
```json
{
"to" : "APA91bHun4MxP5egoKMwt2KZFBaFUH-1RYqx...",
"notification" : {
"body" : "NEW_NOTIFICATION",
"body_loc_key" : "NEW_NOTIFICATION",
"title" : "NEW_NOTIFICATION",
"title_loc_key" : "NEW_NOTIFICATION"
},
"data" : {
"subject" : "*Encrypted subject*",
"signature" : "*Signature*"
}
}
```
| Attribute | Meaning |
| ----------- | ---------------------------------------- |
| `subject` | The subject is encrypted with the device´s *public key*. |
| `signature` | The signature is a sha512 signature over the encrypted subject using the user´s private key. |
### Verification
So a device should verify the signature using the user´s public key.
If the signature is okay, the subject can be decrypted using the device´s private key.
|
