Skip to content

Commit 8819faf

Browse files
mfiebigmfiebig
authored
Add dedicated endpoint for encrypted push notifications and batching (#41)
Changelog: added
1 parent 4d1122e commit 8819faf

22 files changed

+574
-137
lines changed

‎docs/concept.adoc‎

Lines changed: 17 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -131,7 +131,7 @@ Möchte der Versicherte Push Notifications von mehreren Fachdiensten erhalten, w
131131
"app_id": "com.example.app.ios",
132132
"pushkey": "<APNS/GCM TOKEN>",
133133
"data": {
134-
"url": "https://push-gateway.location.here/_matrix/push/v1/notify"
134+
"url": "https://push-gateway.location.here/_matrix/push/v1/"
135135
},
136136
"encryption": {
137137
"method": "aes-hmac-sha256",
@@ -165,7 +165,7 @@ image::diagrams/send_push.svg[width=100%]
165165
2. Für jeden registrierten Pusher `p`, der für das Ereignis abonniert ist, wird eine Push-Benachrichtigung `Notification_p` mit mindestens folgenden Inhalten erzeugt (Die möglichen Felder und deren Beschreibungen sind auf der OpenAPI-Seite zu finden):
166166
a. `ciphertext` = Nachrichteninhalt aus 1a, `Base64(IV || Chiffrat || Authentication Tag)` verschlüsselt mit dem aktuell gültigen Schlüssel.
167167
b. `time_message_encrypted` = Zeitpunkt der Verschlüsselung des Nachrichteinhaltes.
168-
c. `devices` = (mindestens: app_id, push_token)
168+
c. `device` = (mindestens: app_id, push_token) - Einzelnes Gerät für verschlüsselte Nachrichten
169169
3. Für jeden Pusher p wird die Push-Benachrichtigung `Notification_p` an das Push Gateways des Pushers `p` übermittelt.
170170
4. Das Push Gateway übermittelt die Push-Benachrichtigung `Notification_p` an den Push Provider.
171171
5. Der Push-Provider sendet die Notification an die zur `push_token` gehörende FdV-Instanz.
@@ -293,7 +293,7 @@ Durch die extra Schritte ist es später möglich, einen eventuell neu vergebenen
293293
"app_id": "com.example.app.ios",
294294
"pushkey": "<APNS/GCM TOKEN>",
295295
"data": {
296-
"url": "https://push-gateway.location.here/_matrix/push/v1/notify"
296+
"url": "https://push-gateway.location.here/_matrix/push/v1"
297297
},
298298
"encryption": {
299299
"method": "aes-hmac-sha256",
@@ -316,7 +316,7 @@ Durch die extra Schritte ist es später möglich, einen eventuell neu vergebenen
316316
"app_id": "com.example.app",
317317
"pushkey": "<APNS/GCM TOKEN>",
318318
"data": {
319-
"url": "https://push-gateway.location.here/_matrix/push/v1/notify",
319+
"url": "https://push-gateway.location.here/_matrix/push/v1",
320320
"platform": "ios"
321321
},
322322
"encryption": {
@@ -340,7 +340,7 @@ Durch die extra Schritte ist es später möglich, einen eventuell neu vergebenen
340340
"app_id": "com.example.app",
341341
"pushkey": "<APNS/GCM TOKEN>",
342342
"data": {
343-
"url": "https://push-gateway.location.here/ios/_matrix/push/v1/notify"
343+
"url": "https://push-gateway.location.here/ios/_matrix/push/v1"
344344
},
345345
"encryption": {
346346
"method": "aes-hmac-sha256",
@@ -388,13 +388,13 @@ function createNotification(trigger, device) {
388388
time_message_encrypted: time_message_encrypted,
389389
ciphertext: ciphertext,
390390
key_identifier: encryptionKey.identifier
391-
devices: [
391+
device: {
392392
app_id: device.app_id,
393393
pushkey: device.pushkey,
394394
pushkey_ts: device.pushkey_ts,
395395
data: device.data,
396396
tweaks: {}
397-
]
397+
}
398398
}
399399
}
400400
----
@@ -415,7 +415,7 @@ pushContent:
415415

416416
=== Push Gateway
417417

418-
Endpoint: http://localhost:8080/push/v1/notify
418+
Endpoint: http://localhost:8080/push/v1/notifyEncrypted/batch
419419

420420
==== IN
421421

@@ -428,18 +428,16 @@ Endpoint: http://localhost:8080/push/v1/notify
428428
"key_identifier": "123e4567-e89b-12d3-a456-426614174000",
429429
"prio": "high",
430430
"counts": {},
431-
"devices": [
432-
{
433-
"app_id": "de.gematikkk.app.ios",
434-
"pushkey": "abcd-efghi-jklm-nopq",
435-
"pushkey_ts": 0,
436-
"data": {
437-
"format": "string"
438-
},
439-
"tweaks": {
440-
}
431+
"device": {
432+
"app_id": "de.gematikkk.app.ios",
433+
"pushkey": "abcd-efghi-jklm-nopq",
434+
"pushkey_ts": 0,
435+
"data": {
436+
"format": "string"
437+
},
438+
"tweaks": {
441439
}
442-
]
440+
}
443441
}
444442
----
445443

‎docs/optional-features.adoc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,15 @@ Ein Fachdienst sendet eine Push Nachricht mit zusätzlichem `identifier`.
113113
"key_identifier": "123123",
114114
"time_message_encrypted": "2024-01",
115115
"identifier": "123-4567-890",
116+
"device": {
117+
"app_id": "de.gematik.app.ios",
118+
"pushkey": "example-pushkey-123",
119+
"pushkey_ts": 1634025600,
120+
"data": {
121+
"format": "string"
122+
},
123+
"tweaks": {}
124+
},
116125
"data": {
117126
"service": "epa15"
118127
}

‎docs_sources/concept-source.adoc‎

Lines changed: 16 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@ image::diagrams/send_push.svg[width=100%]
132132
2. Für jeden registrierten Pusher `p`, der für das Ereignis abonniert ist, wird eine Push-Benachrichtigung `Notification_p` mit mindestens folgenden Inhalten erzeugt (Die möglichen Felder und deren Beschreibungen sind auf der OpenAPI-Seite zu finden):
133133
a. `ciphertext` = Nachrichteninhalt aus 1a, `Base64(IV || Chiffrat || Authentication Tag)` verschlüsselt mit dem aktuell gültigen Schlüssel.
134134
b. `time_message_encrypted` = Zeitpunkt der Verschlüsselung des Nachrichteinhaltes.
135-
c. `devices` = (mindestens: app_id, push_token)
135+
c. `device` = (mindestens: app_id, push_token) - Einzelnes Gerät für verschlüsselte Nachrichten
136136
3. Für jeden Pusher p wird die Push-Benachrichtigung `Notification_p` an das Push Gateways des Pushers `p` übermittelt.
137137
4. Das Push Gateway übermittelt die Push-Benachrichtigung `Notification_p` an den Push Provider.
138138
5. Der Push-Provider sendet die Notification an die zur `push_token` gehörende FdV-Instanz.
@@ -260,7 +260,7 @@ Durch die extra Schritte ist es später möglich, einen eventuell neu vergebenen
260260
"app_id": "com.example.app.ios",
261261
"pushkey": "<APNS/GCM TOKEN>",
262262
"data": {
263-
"url": "https://push-gateway.location.here/_matrix/push/v1/notify"
263+
"url": "https://push-gateway.location.here/_matrix/push/v1"
264264
},
265265
"encryption": {
266266
"method": "aes-hmac-sha256",
@@ -283,7 +283,7 @@ Durch die extra Schritte ist es später möglich, einen eventuell neu vergebenen
283283
"app_id": "com.example.app",
284284
"pushkey": "<APNS/GCM TOKEN>",
285285
"data": {
286-
"url": "https://push-gateway.location.here/_matrix/push/v1/notify",
286+
"url": "https://push-gateway.location.here/_matrix/push/v1",
287287
"platform": "ios"
288288
},
289289
"encryption": {
@@ -307,7 +307,7 @@ Durch die extra Schritte ist es später möglich, einen eventuell neu vergebenen
307307
"app_id": "com.example.app",
308308
"pushkey": "<APNS/GCM TOKEN>",
309309
"data": {
310-
"url": "https://push-gateway.location.here/ios/_matrix/push/v1/notify"
310+
"url": "https://push-gateway.location.here/ios/_matrix/push/v1"
311311
},
312312
"encryption": {
313313
"method": "aes-hmac-sha256",
@@ -355,13 +355,13 @@ function createNotification(trigger, device) {
355355
time_message_encrypted: time_message_encrypted,
356356
ciphertext: ciphertext,
357357
key_identifier: encryptionKey.identifier
358-
devices: [
358+
device: {
359359
app_id: device.app_id,
360360
pushkey: device.pushkey,
361361
pushkey_ts: device.pushkey_ts,
362362
data: device.data,
363363
tweaks: {}
364-
]
364+
}
365365
}
366366
}
367367
----
@@ -382,7 +382,7 @@ pushContent:
382382

383383
=== Push Gateway
384384

385-
Endpoint: http://localhost:8080/push/v1/notify
385+
Endpoint: http://localhost:8080/push/v1/notifyEncrypted/batch
386386

387387
==== IN
388388

@@ -395,18 +395,16 @@ Endpoint: http://localhost:8080/push/v1/notify
395395
"key_identifier": "123e4567-e89b-12d3-a456-426614174000",
396396
"prio": "high",
397397
"counts": {},
398-
"devices": [
399-
{
400-
"app_id": "de.gematikkk.app.ios",
401-
"pushkey": "abcd-efghi-jklm-nopq",
402-
"pushkey_ts": 0,
403-
"data": {
404-
"format": "string"
405-
},
406-
"tweaks": {
407-
}
398+
"device": {
399+
"app_id": "de.gematikkk.app.ios",
400+
"pushkey": "abcd-efghi-jklm-nopq",
401+
"pushkey_ts": 0,
402+
"data": {
403+
"format": "string"
404+
},
405+
"tweaks": {
408406
}
409-
]
407+
}
410408
}
411409
----
412410

‎docs_sources/definitions/pusher_get.yaml‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ examples:
1111
"profile_tag": "xyz",
1212
"lang": "en-US",
1313
"data": {
14-
"url": "https://example.com/_matrix/push/v1/notify"
14+
"url": "https://example.com/_matrix/push/v1/"
1515
}
1616
}
1717
]
@@ -70,7 +70,7 @@ schema:
7070
to use for sending notifications. Clients MAY use this object
7171
to pass custom data to their push gateway. Servers MUST forward
7272
the entire content including `format` and any custom keys but excluding `url`
73-
when calling [`/push/v1/notify`](/push-gateway-api/#postpushv1notify).
73+
when calling [`/push/v1/notify*`](/push-gateway-api/#postpushv1notify).
7474
title: PusherData
7575
properties:
7676
url:
@@ -79,8 +79,10 @@ schema:
7979
description: |-
8080
Required if `kind` is `http`. The URL to use for sending
8181
notifications. MUST be an HTTPS URL with a path of
82-
`/push/v1/notify`.
83-
example: https://push-gateway.location.here/push/v1/notify
82+
`/push/v1/` that can be extended by `notify`, `notify/batch`
83+
or `notifyEncrypted/batch`, so that the FD can pick the method, if not
84+
specified otherwise by the FD specification.
85+
example: https://push-gateway.location.here/push/v1/
8486
format:
8587
type: string
8688
description: |-

‎docs_sources/definitions/pusher_post_put_delete.yaml‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ examples:
1010
"app_id": "com.example.app.ios",
1111
"pushkey": "<APNS/GCM TOKEN>",
1212
"data": {
13-
"url": "https://push-gateway.location.here/_matrix/push/v1/notify"
13+
"url": "https://push-gateway.location.here/_matrix/push/v1/"
1414
},
1515
"encryption": {
1616
"method": "aes-hmac-sha256",
@@ -89,7 +89,8 @@ schema:
8989
to use for sending notifications. Clients MAY use this object
9090
to pass custom data to their push gateway. Servers MUST forward
9191
the entire content including `format` and any custom keys but excluding `url`
92-
when calling [`/notify`](./push_gateway_openapi.html#tag/Push-Gateway/operation/push_v1_notify).
92+
when calling [`/notify`](./push_gateway_openapi.html#tag/Push-Gateway/operation/push_v1_notify_plain)
93+
or [`/notifyEncrypted`](./push_gateway_openapi.html#tag/Push-Gateway/operation/push_v1_notify_batch_encrypted).
9394
title: PusherData
9495
properties:
9596
url:
@@ -98,8 +99,8 @@ schema:
9899
description: |-
99100
Required if `kind` is `http`. The URL to use for sending
100101
notifications. MUST be an HTTPS URL with a path of
101-
`/_matrix/push/v1/notify`.
102-
example: https://push-gateway.location.here/_matrix/push/v1/notify
102+
`/_matrix/push/v1/`.
103+
example: https://push-gateway.location.here/_matrix/push/v1/
103104
format:
104105
type: string
105106
description: |-

‎docs_sources/optional-features-source.adoc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,15 @@ Ein Fachdienst sendet eine Push Nachricht mit zusätzlichem `identifier`.
9797
"key_identifier": "123123",
9898
"time_message_encrypted": "2024-01",
9999
"identifier": "123-4567-890",
100+
"device": {
101+
"app_id": "de.gematik.app.ios",
102+
"pushkey": "example-pushkey-123",
103+
"pushkey_ts": 1634025600,
104+
"data": {
105+
"format": "string"
106+
},
107+
"tweaks": {}
108+
},
100109
"data": {
101110
"service": "epa15"
102111
}

0 commit comments

Comments
 (0)