documentation and license

LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2021 Peter Körner <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -0,0 +1,77 @@
+Python Implementation of the CoronaWarnApp (CWA) Event Registration
+===================================================================
+
+This is an Implementation of the Protocol used to generate Event-Location QR-Codes for the CoronaWarnApp (CWA) as described in [
+Corona-Warn-App: Documentation – Event Registration - Summary](https://github.com/corona-warn-app/cwa-documentation/blob/c0e2829/event_registration.md).
+
+**This is not an official implementation – use it at your own risk** (as far as that's possible, these days…).
+
+State
+-----
+The Interface described in the Document is implemented, the undocumented Pieces (Public Key Value, Seed Length, Versions etc.) have been taken from the Open Source iOS Client Application. As Far as I know the Interface has been fully implemented, but without an actual positive Corona Test there is no way to do an End-to-End verification.
+
+Usage
+-----
+The Library is not yet packaged as pip and so the `.py` files should be copied over to your project manually.
+
+Useas follows:
+```py
+#!/usr/bin/env python3
+
+import io
+from datetime import datetime, timedelta, timezone
+
+import cwa
+import qrcode.image.svg
+
+eventDescription = cwa.CwaEventDescription()
+eventDescription.locationDescription = 'Zuhause'
+eventDescription.locationAddress = 'Gau-Odernheim'
+eventDescription.startDateTime = datetime.now(timezone.utc)
+eventDescription.endDateTime = datetime.now(timezone.utc) + timedelta(days=2)
+eventDescription.locationType = cwa.lowlevel.LOCATION_TYPE_PERMANENT_WORKPLACE
+eventDescription.defaultCheckInLengthInMinutes = 4 * 60
+qr = cwa.generateQrCode(eventDescription)
+
+# Render QR-Code to PNG-File
+img = qr.make_image(fill_color="black", back_color="white")
+img.save('example.png')
+print("generated example.png")
+
+# Render QR-Code to PNG BytesIO-Object for further usage
+img_bytes = io.BytesIO()
+img.save(img_bytes)
+print(len(img_bytes.getvalue()), " bytes of png")
+
+
+# Render QR-Code to SVG-File
+svg = qr.make_image(image_factory=qrcode.image.svg.SvgPathFillImage)
+svg.save('example.svg')
+
+# Render QR-Code to SVG BytesIO-Object for further usage
+svg_bytes = io.BytesIO()
+svg.save(svg_bytes)
+print(len(svg_bytes.getvalue()), " bytes of svg")
+```
+
+CwaEventDescription
+-------------------
+- `locationDescription`: Description of the Location, Optional, String, max 100 Characters
+- `locationAddress`: Address of the Location, Optional, String, max 100 Characters
+- `startDateTime`: Start of the Event, Optional, datetime in UTC
+- `endDateTime`: End of the Event, Optional, datetime in UTC
+- `locationType`: Type of the Location, Optional, one of
+	- `cwa.lowlevel.LOCATION_TYPE_UNSPECIFIED` = 0
+	- `cwa.lowlevel.LOCATION_TYPE_PERMANENT_OTHER` = 1
+	- `cwa.lowlevel.LOCATION_TYPE_TEMPORARY_OTHER` = 2
+	- `cwa.lowlevel.LOCATION_TYPE_PERMANENT_RETAIL` = 3
+	- `cwa.lowlevel.LOCATION_TYPE_PERMANENT_FOOD_SERVICE` = 4
+	- `cwa.lowlevel.LOCATION_TYPE_PERMANENT_CRAFT` = 5
+	- `cwa.lowlevel.LOCATION_TYPE_PERMANENT_WORKPLACE` = 6
+	- `cwa.lowlevel.LOCATION_TYPE_PERMANENT_EDUCATIONAL_INSTITUTION` = 7
+	- `cwa.lowlevel.LOCATION_TYPE_PERMANENT_PUBLIC_BUILDING` = 8
+	- `cwa.lowlevel.LOCATION_TYPE_TEMPORARY_CULTURAL_EVENT` = 9
+	- `cwa.lowlevel.LOCATION_TYPE_TEMPORARY_CLUB_ACTIVITY `= 10
+	- `cwa.lowlevel.LOCATION_TYPE_TEMPORARY_PRIVATE_EVENT `= 11
+	- `cwa.lowlevel.LOCATION_TYPE_TEMPORARY_WORSHIP_SERVICE `= 12
+- `defaultCheckInLengthInMinutes`: Default Checkout-Time im Minutes, Optional

cwa.py

@@ -9,14 +9,42 @@
 
 class CwaEventDescription(object):
 	def __init__(self):
-		self.locationDescription = None;
-		self.locationAddress = None;
-		self.startDateTime = None;
-		self.endDateTime = None;
-		self.locationType = None
-		self.defaultCheckInLengthInMinutes = None
-
-def generatePayload(eventDescription):
+		"""Description of the Location, Optional, String, max 100 Characters"""
+		self.locationDescription: str = None;
+
+		"""Address of the Location, Optional, String, max 100 Characters"""
+		self.locationAddress: str = None;
+
+		"""Start of the Event, Optional, datetime in UTC"""
+		self.startDateTime: datetime = None;
+
+		"""End of the Event, Optional, datetime in UTC"""
+		self.endDateTime: datetime = None;
+
+		"""Type of the Location, Optional
+
+		one of
+		- cwa.lowlevel.LOCATION_TYPE_UNSPECIFIED = 0
+		- cwa.lowlevel.LOCATION_TYPE_PERMANENT_OTHER = 1
+		- cwa.lowlevel.LOCATION_TYPE_TEMPORARY_OTHER = 2
+		- cwa.lowlevel.LOCATION_TYPE_PERMANENT_RETAIL = 3
+		- cwa.lowlevel.LOCATION_TYPE_PERMANENT_FOOD_SERVICE = 4
+		- cwa.lowlevel.LOCATION_TYPE_PERMANENT_CRAFT = 5
+		- cwa.lowlevel.LOCATION_TYPE_PERMANENT_WORKPLACE = 6
+		- cwa.lowlevel.LOCATION_TYPE_PERMANENT_EDUCATIONAL_INSTITUTION = 7
+		- cwa.lowlevel.LOCATION_TYPE_PERMANENT_PUBLIC_BUILDING = 8
+		- cwa.lowlevel.LOCATION_TYPE_TEMPORARY_CULTURAL_EVENT = 9
+		- cwa.lowlevel.LOCATION_TYPE_TEMPORARY_CLUB_ACTIVITY = 10
+		- cwa.lowlevel.LOCATION_TYPE_TEMPORARY_PRIVATE_EVENT = 11
+		- cwa.lowlevel.LOCATION_TYPE_TEMPORARY_WORSHIP_SERVICE = 12
+		"""
+		self.locationType: int = None
+
+		"""Default Checkout-Time im Minutes, Optional"""
+		self.defaultCheckInLengthInMinutes: int = None
+
+
+def generatePayload(eventDescription: CwaEventDescription):
 	payload = lowlevel.QRCodePayload()
 	payload.version = 1
 
@@ -38,15 +66,15 @@ def generatePayload(eventDescription):
 	payload.countryData = cwaLocationData.SerializeToString()
 	return payload
 
-def generateUrl(eventDescription):
+def generateUrl(eventDescription: CwaEventDescription):
 	payload = generatePayload(eventDescription)
 	serialized = payload.SerializeToString()
 	encoded = base64.urlsafe_b64encode(serialized)
 	url = 'https://e.coronawarn.app?v=1#' + encoded.decode('ascii')
 
 	return url
 
-def generateQrCode(eventDescription):
+def generateQrCode(eventDescription: CwaEventDescription):
 	qr = qrcode.QRCode()
 	qr.add_data(generateUrl(eventDescription))
 	qr.make(fit=True)