How does closecontact work?

Closecontact (capitalised as “closecontact”) enables potential guests to create a pass, which consists of a QR code with their personal information. Guests can check into a club using this pass, at which point their personal details will be recorded in the club’s check-in log.

Closecontact is built with a focus on privacy: personal information is only visible to the club administrator when they download the check-in log (for it to be passed on to the Gesundheitsamt).

Roles

Closecontact distinguishes the following roles:

  • A guest visits a club.
  • A door operator of a club scans guest passes for their club.
  • A club administrator can download the check-in log for their club. They are also responsible for activating their club on closecontact.
  • A closecontact administrator manages accounts of door operators, club administrators and closecontact administrators, creates clubs in closecontact, and assigns accounts to clubs. Closecontact administrators cannot access check-in logs.

Data models

  • A pass contains a guest’s personal information.
  • An account allows door operators, club administrators and closecontact administrators to sign in to the closecontact back office. An account has a name and an email address, as well as a role (either “admin” for closecontact admins, or “regular” otherwise.)
  • A club is a record representing a club. It has just a name.
  • A club assignment represents the relationship between an account and a club. It has a role (either “admin” for club administrators, or “door operator” for door operators).
  • A check-in record is created when a door operator scans a pass. It contains the secured personal information, as well as a reference to the club, and the time of check-in.
  • A check-in log is the list of all check-in records for a club.

Data security

This section gives an overview of how cryptography is used to secure personal information. For more detail, refer to the Scenarios section in this document.

  • The closecontact encryption keypair is a keypair used for asymmetric encryption. It is used to encrypt passes.
  • The closecontact signing keypair is a keypair used for generating digital signatures. It is used to sign the encrypted passes. This way, the authenticity of the pass, meaning that the pass was generated by closecontact, can be verified at check-in.
  • A pass consists of personal information encrypted with the closecontact public key, and a signature, generated with the closecontact signing key, of this encrypted data.
  • Each club has a club keypair, consisting of a private club key and a public club key for asymmetric encryption. It is used for encrypting check-in records (see below). The private club key is encrypted with the club token (see below).
  • Each club has a club token that is known to the club administrator(s) and is necessary to decrypt the private club key. This club token is generated by closecontact and communicated to club administrators, but is not known to closecontact administrators, and cannot be recovered if lost.
  • Each club has a (club) token key which is used to encrypt the private club key. This token key is derived from the club token. Because the club token is not available to closecontact administrators, they cannot decrypt the private club key, and therefore cannot decrypt the check-in record.
  • A check-in record is encrypted using the closecontact key, and then encrypted with the club key. This way, only club administrators can see check-in records, and they can only see check-in records for their own club.

Architecture

The closecontact architecture consists of the following systems:

  • The guest registration frontend is used by potential guests. They enter their personal data here, after which it is sent to the guest registration backend (see below), which replies with the encrypted and signed personal details. The guest registration frontend then constructs a QR code containing this encrypted and signed data. The guest registration frontend runs on potential guests’ browsers.
  • The guest registration backend is indirectly used by potential guests. It receives personal details from the guest registration frontend, and encrypts and signs the data. The guest registration backend runs on closecontact infrastructure. It does not store any personal data, and has no connection to a database.
  • The closecontact back office is used by door operators to check in guests, club administrators to activate clubs and download the check-in log, and closecontact administrators to manage clubs and accounts. The back office consists of a back-end, which runs on closecontact infrastructure, and a front-end, which runs in the browser.
  • The database stores accounts, clubs, club assignments, and check-in records. Only the backend of the closecontact back office can access the database.

Scenarios

Closecontact has the following scenarios:

  • Pass generation
  • Club activation
  • Guest check-in
  • Guest check-in log download

Diagram conventions

The diagrams in this section use the following conventions:

  • Shapes: circles represent actions, and rectangles represent data
  • Colors: blue represents input, purple represents data transformation, and pink represents output.
  • Arrows indicate how data is used as input and output of transformations.
  • Dashed lines indicate the boundary between systems (see the Architecture section above), and uppercase bold text indicates the names of the systems.
  • Colored text indicates the sensitivity of cryptographic keys. Blue is used for public information (the public part of keypairs used for asymmetric encryption, as well as verification keys). Orange is used for private information (private keys and keys for symmetric encryption).

Scenario: Pass generation

A pass is generated when a potential guest submits their personal data. The generation of a pass happens as follows:

  1. [user input] The guest enters their personal information in the guest registration frontend, and submits the data to the guest registration backend.
  2. [encrypt] The guest registration backend receives this data, and encrypts this data using the closecontact encryption key (CC key) known by the guest registration backend.
  3. [sign] The guest registration backend creates a digital signature for this encrypted data, using the closecontact signing key.
  4. [combine] The guest registration backend combines the signature and the encrypted data.
  5. [send via email] The guest registration backend generates a QR code from the combined data, and emails it to the specified email address.

When the request to the guest registration backend finishes, the input data (the unencrypted personal information) is discarded.

Scenario: Club activation, part 1: club key generation

Before a club can start checking in guests, the club needs to be activated. This involves generating the club keypair, as well as a token (not known to closecontact) to encrypt the private club key with.

This activation process can only be completed once. If a club is already activated, and therefore already has a club keypair and a club token, then re-running the activation flow would replace this club keypair and club token, making it impossible to decrypt past check-in records.

This scenario assumes that the club admin is signed in to the closecontact back office.

The generation of a club keypair and a club token happens as follows:

  1. [generate] At the request of a club administrator, the closecontact back office generates a club keypair and a club token.
  2. [derive key] The closecontact back office derives the token key (a symmetric encryption key) from the club token.
  3. [send] The closecontact back office delivers the club token out-of-band to the club administrator.
  4. [encrypt] The closecontact back office encrypts the private club key using the token key.
  5. [store in database] The closecontact back office stores the encrypted private club key and the (unencrypted) public club key in the database.

When the request to the closecontact back office finishes, the private club key, the club token, and the club token key are discarded.

Scenario: Club activation, part 2: finalization

The purpose of this step is to verify that the club administrator has the club token. This happens as follows:

  1. [user input] The club administrator enters the club token, which they have received out of band.
  2. [derive key] The closecontact back office derives the token key (a symmetric encryption key) from the club token.
  3. [load from database] The closecontact back office loads the encrypted club key for this club from the database.
  4. [decrypt] The closecontact back office decrypts the encrypted private club key using the token key. This decryption will fail if the token key is not correct, i.e. when the club token is not correct.

As a last step, assuming the decryption succeeded, the club is marked as activated, which enables them to start checking in guests. This way, a club can only start checking in once they have confirmed that they have their club token.

When the request to the closecontact back office finishes, the club token, the club token key, and the (decrypted) private club key are discarded.

Scenario: Guest check-in, part 1: verification

In this scenario, a guest presents their pass to the door operator, who scans the pass, which is then cryptographically verified before moving on to the second step, storage (see below).

The door operator is assumed to be signed in to the closecontact back office. The operations in this step take place in the door operator’s browser.

This happens as follows:

  1. [user input] The door operator scans the pass (QR code).
  2. [verify signature] The signature part of the pass is verified using the closecontact verification key, which is loaded from the configuration.
  3. [abort if invalid] If the signature verification fails, the scenario is aborted. Step 2 (storage), does not take place.

After this scenario, step 2 (storage) is executed immediately.

Scenario: Guest check-in, part 2: storage

In this scenario, the already-encrypted personal details in the pass are encrypted once more, so that the data stored in the closecontact back office cannot be accessed by closecontact administrators.

This happens as follows:

  1. [encrypt] The already-encrypted data in the pass is encrypted again, this time using the public club key, which is loaded from the database.
  2. [send to back office] The double-encrypted data is sent to the closecontact back office.
  3. [store] The closecontact back office stores the received double-encrypted data, and stores it in the database as a check-in record for the current time and the relevant club.

Scenario: Guest check-in log download

This final scenario describes how a club administrator can download the check-in log.

The club administrator is assumed to be signed in to the closecontact back office.

The steps in this scenario are as follows:

  1. [user input] On the check-in log download page, the club administrator enters the club token.
  2. [derive key] The closecontact back office derives the token key (a symmetric encryption key) from the club token.
  3. [decrypt] The closecontact back office decrypts the encrypted private club key, which is loaded from the database, using the token key. This decryption will fail if the token key is not correct, i.e. when the club token is not correct.
  4. [decrypt] Each fully-encrypted check-in record for this club (loaded from the database) is decrypted using the (decrypted) private club key, yielding a half-decrypted check-in record. This half-decrypted check-in record is kept in memory (not stored in the database) for the duration of the request, after which it is discarded.
  5. [decrypt] Each half-decrypted check-in record for this club (obtained in the previous step) is decrypted using the closecontact private key, yielding a fully-decrypted check-in record. This fully-decrypted check-in record is kept in memory (not stored in the database) for the duration of the request, after which it is discarded.
  6. [send to browser] The list of fully-decrypted check-in records is sent to the browser.

In addition, an audit log entry is written to confirm that this club administrator downloaded the check-in log at this time.

When the request to the closecontact back office finishes, the club token, the club token key, the (decrypted) private club key, the half-decrypted check-in records, and the fully-decrypted check-in records are all discarded.

Privacy and security considerations

This section describes some of the considerations behind decisions made with relation to privacy and security.

Club token security

The club token is secret, but the club token by itself is not useful. It cannot be used to sign in, and it cannot be used to download the check-in log. The club token is only useful to club administrators who are signed in to the closecontact back office.

For this reason, we believe that having the club token written down is fine from a security and privacy point of view, and we even recommend printing out the club token and storing it in a secure location.

Data retention

Check-in records are kept for 30 days in the database. Each day, all records older than 30 days are removed from the database.

Database backups are kept for 7 days. A club’s check-in log functionality will contain check-in records at most 30 days old, even if the database contains older records. This way, restoring the database from backups won’t make it possible to download older records.

Ephemeral data handling

All systems running on our infrastructure (the guest registration frontend and the closecontact back office) only handle personal data when absolutely required, and discard this data after it is used:

  • After the guest registration backend generates the pass, all personal information (name, telephone number, and email address) is discarded. Additionally, the guest registration backend intentionally does not have a connection to a database.
  • After the check-in log is downloaded, the half-decrypted check-in records, the fully-decrypted check-in records, the club token, and the (unencrypted) private club key are discarded immediately as the request ends.

Additionally, when generating a keypair and a club token, the club token and the (unencrypted) private club key are discarded as soon as the private club key is encrypted and stored in the database, and the club token is sent out of band.

Data boundaries between systems

The closecontact architecture prevents data from being inside a system if it is not processed within that system. This has the following effects:

  • The data that is stored in the closecontact back office cannot be read by closecontact administrators. This data is encrypted with the club key, and cannot be decrypted without the private club key. This private club key, in turn, is encrypted and cannot be decrypted without the club token, which is unknown to closecontact administrators.
  • The data in a pass is not sent as-is to the back-end of the closecontact back office. Before it is sent, it is encrypted with the club key inside the browser, so that the closecontact back office backend (which runs on our infrastructure rather than the browser) cannot decrypt this data.
  • The door operator cannot extract personal information from the QR code, as it is encrypted with the closecontact key, and the decryption key is not available to the door operator.