covid19/cwa-documentation
covid19/cwa-documentation
1
0
Fork 0
mirror of https://github.com/corona-warn-app/cwa-documentation synced 2024-12-29 16:12:13 +01:00
Code Releases Activity

docs(evreg): update qr code data structures

Browse Source
This commit is contained in:
Maximilian Lenkeit 2021-04-01 09:10:30 +02:00
parent 81bb4a44cf
commit 48e0ec97af
1 changed files with 40 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
event_registration.md
View File

@ -56,23 +56,34 @@ However, we acknowledge that this does not prevent to execute this attack for a
The QR code of a venue contains all required attributes for Presence Tracing, so that no server communication is necessary when an attendee checks in to a venue
The data structure is described by the following Protocol Buffer message `TraceLocation`:
The data structure is described by the Protocol Buffer message `QRCodePayload`:
```protobuf
message QRCodePayload {
uint32 version = 1;
TraceLocation locationData = 2;
CrowdNotifierData crowdNotifierData = 3;
// byte sequence of CWALocationData
bytes vendorData = 4;
}
message TraceLocation {
// uuid
string guid = 1;
uint32 version = 2;
TraceLocationType type = 3;
// max. 150 characters
string description = 4;
// max. 150 characters
string address = 5;
uint32 version = 1;
// max. 100 characters
string description = 2;
// max. 100 characters
string address = 3;
// UNIX timestamp (in seconds)
uint64 startTimestamp = 6;
uint64 startTimestamp = 5;
// UNIX timestamp (in seconds)
uint64 endTimestamp = 7;
uint32 defaultCheckInLengthInMinutes = 8;
uint64 endTimestamp = 6;
}
message CrowdNotifierData {
uint32 version = 1;
bytes publicKey = 2;
bytes cryptographicSeed = 3;
}
enum TraceLocationType {
@ -91,26 +102,22 @@ enum TraceLocationType {
LOCATION_TYPE_TEMPORARY_CLUB_ACTIVITY = 10;
LOCATION_TYPE_TEMPORARY_PRIVATE_EVENT = 11;
LOCATION_TYPE_TEMPORARY_WORSHIP_SERVICE = 12;
}
message CWALocationData {
uint32 version = 1;
TraceLocationType type = 2;
uint32 defaultCheckInLengthInMinutes = 3;
}
```
The `guid` attribute is generated by the CWA Server to ensure uniqueness across all CWA QR codes. The data structure is signed by the CWA Server with its private key to prevent tampering of the QR code or identity theft of the GUID of a venue.
The ID of a venue is derived as the SHA-256 hash of the concatenated byte representation of the string `CWA-GUID` and the byte representation of the Protocol Buffer message `QRCodePayload`. The `cryptographicSeed` adds sufficient entropy so that any modifications to the QR result in a unique ID.
The combination of signature and TraceLocation is represented in the following Protocol Buffer message `SignedTraceLocation`:
```protobuf
message SignedTraceLocation {
// byte representation of a TraceLocation
bytes location = 1;
// byte representation of the signature of the TraceLocation
bytes signature = 2;
}
```
A SignedTraceLocation is base32-encoded and included in a URL. The URL is the content of the QR code and structures as follows:
A `QRCodePayload` is base32-encoded and included in a URL. The URL is the content of the QR code and structures as follows:
```text
HTTPS://E.CORONAWARN.APP/C1/<SIGNED_TRACE_LOCATION_BASE32>
HTTPS://E.CORONAWARN.APP/C1/<ENCODED_PAYLOAD>
# example:
HTTPS://E.CORONAWARN.APP/C1/BIPEY33...
@ -118,20 +125,20 @@ HTTPS://E.CORONAWARN.APP/C1/BIPEY33...
The base32 encoding allows to leverage the input mode _alphanumeric_ when generating the QR code and produces a QR code with a lower density compared to base64 encoding.
### Interoperability with Other Contact Tracing Apps DRAFT
### QR Code Compatibility with Other Contract Tracing Apps in Germany DRAFT
Other contact tracing apps that leverage QR code for Presence Tracing can integrate with CWA by creating QR codes according to the following pattern:
Other contact tracing apps in Germany that leverage QR code for Presence Tracing can integrate with CWA by creating QR codes according to the following pattern:
```text
<URL>/<VENDOR_DATA>#[VENDOR_ADDITIONAL_DATA]/CWA1/<ENCODED_SIGNED_TRACE_LOCATION>
<URL>/<VENDOR_DATA>#[VENDOR_ADDITIONAL_DATA]/CWA1/<ENCODED_PAYLOAD>
```
| Parameter | Description |
|---|---|
| `<URL>` | The URL associated with the respective contact tracing apps, with or without a partial path. |
| `<VENDOR_DATA>` | Any vendor-specific data such as venue ids. This data may be passed to the vendor-specific app upon interaction by the user if a deeper integration is required. |
| `<VENDOR_DATA>` | Any vendor-specific data such as the venue id in the vendor's system. This data may be passed to the vendor-specific app upon interaction by the user if a deeper integration is required. |
| `[VENDOR_ADDITIONAL_DATA]` | Additional vendor-specific data (optional). |
| `<ENCODED_SIGNED_TRACE_LOCATION>` | A representation of the Protocol Buffer message SignedTraceLocation encoded in base64. Note that the signature must have been created by the CWA Server. |
| `<ENCODED_PAYLOAD>` | A representation of the Protocol Buffer message `QRCodePayload` encoded in base64. Note that the signature must have been created by the CWA Server. |
**Note:** Any contact tracing apps that integrate with CWA must ensure that they do not process any information from the CWA part of the QR code.
@ -143,12 +150,12 @@ https://presence-tracing.app/386d0384-8aaa-41b6-93c2-d3399894d0ee#/CWA1/CiRmY2E.
URL: https://presence-tracing.app
VENDOR_DATA: 386d0384-8aaa-41b6-93c2-d3399894d0ee
VENDOR_ADDITIONAL_DATA: ∅
ENCODED_SIGNED_TRACE_LOCATION: CiRmY2E...
ENCODED_PAYLOAD: CiRmY2E...
# with optional data
https://check-in.pt.app/386d0384-8aaa-41b6-93c2-d3399894d0ee#42/CWA1/CiRmY2E...
URL: https://check-in.pt.app
VENDOR_DATA: 386d0384-8aaa-41b6-93c2-d3399894d0ee
VENDOR_ADDITIONAL_DATA: 42
ENCODED_SIGNED_TRACE_LOCATION: CiRmY2E...
ENCODED_PAYLOAD: CiRmY2E...
```