From 620d5733821464664892f86ca024cef224c6a3da Mon Sep 17 00:00:00 2001 From: Joas Schilling Date: Thu, 26 Jan 2017 17:46:59 +0100 Subject: [PATCH] Add documentation for devices Signed-off-by: Joas Schilling --- docs/push-v3.md | 186 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 docs/push-v3.md diff --git a/docs/push-v3.md b/docs/push-v3.md new file mode 100644 index 000000000..0aff0587f --- /dev/null +++ b/docs/push-v3.md @@ -0,0 +1,186 @@ +# 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` + +```json +{ + "ocs": { + ... + "data": { + ... + "capabilities": { + ... + "notifications": { + "ocs-endpoints": [ + ... + "push" + ] + } + } + } + } +} +``` + + + +## 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` and `PushTokenHash` to the Nextcloud server: + + ```json + POST /ocs/v2.php/apps/notifications/api/v3/push + + { + "pushTokenHash": "{{PushTokenHash}}", + "devicePublicKey": "{{devicePublicKey}}" + } + ``` + + ​ + +### 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 public key, device does not use a token to authenticate or the push token hash is invalid formatted | +| 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. | + + + +## 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 the `devicePublicKey` and `PushTokenHash` to the Nextcloud server: + +```json +DELETE /ocs/v2.php/apps/notifications/api/v3/push + +{ + "devicePublicKey": "{{devicePublicKey}}" +} +``` + + + +### Response + +The server replies with the following status codes: + +| Status code | Meaning | +| ----------- | ---------------------------------------- | +| 202 | Push token was deleted and **needs to be deleted from the `Proxy`** | +| 400 | Invalid public key or 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. | +| `INVALID_DEVICE_KEY` | The device key does not match the one registered to the provided session token. | + + + +## 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: + +```json +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` and the user´s `publicKey` (from the server´s response) to the Push Proxy: + +```json +DELETE /devices + +{ + "deviceIdentifier": "{{deviceIdentifier}}", + "userPublicKey": "{{userPublicKey}}" +} +``` + + + +### Response + +The server replies with the following status codes: + +| Status code | Meaning | +| ----------- | ---------------------------------------- | +| 200 | Push token was deleted from the databse | +| 400 | Public key or device identifier is malformed | +| 403 | Device identifier and device public key didn't match or could not be found | + + +