OpenTTD's Survey website

This is the website to show the results of the survey analysis and the information and privacy statement of the participation.

This is a Jekyll website, and is served by nginx as a static site.

Development

Survey results

To summarize survey results, the Python application analysis processes a bundle of JSONs and outputs another JSON with the summary.

To run it:

• git clone https://github.com/OpenTTD/BaNaNaS to get the BaNaNaS dataset (needed to resolve NewGRFs).
• Create a Python virtual env run pip install -r requirements.txt.
• python3 -m analysis <tar-xz bundle files> to run the analysis.

Running a local server

If you do not want to run a server, but just build the current site, replace serve with build in the examples below.

Under _site Jekyll will put the compiled result in both serve and build.

• Follow jekyll installation
• Run bundle install
• Run JEKYLL_ENV=production jekyll serve

Workers

The survey makes use of a Cloudflare worker to process the survey results and to hand out new survey-keys.

• Install wrangler
• Navigate into workers folder
• Run npm install
• Run npx wrangler dev --local src/index.js

Survey keys

Security in Open Source is difficult, as all code is open for everyone to read, and everyone can compile their own binary. This is especially an issue if the backend wants to trust information received from a client.

There is no waterproof method, but the survey makes use of a key to somewhat know the survey result was generated by a trusted client. Make no mistake: it is trivial for anyone with ill intentions to retrieve the survey key from an official binary, and reuse it to submit fraudulent survey results. There are other mitigations in place to decrease the impact of this.

Mostly, the survey key is used to know when the survey result was created by, for example, a development build. These are very likely to have no key at all.

That all said, survey keys are simply JWTs, signed with HS256. This signature is used to validate that a survey result is, most likely, send by a trusted client.

Getting a survey key

When an official binary is built, the GitHub workflow requests a new survey key. This is done by sending the OpenTTD version together with a signature of that request (based on RSA private/public key).

The public key of this RSA is under workers/src/public_keys/. The private key is, of course, a secret within the GitHub workflow of the project itself.

Based on this, the worker can validate that the request is valid, and create a survey key based on the request. This is then used by the GitHub workflow to embed in the binaries.

Patch-pack support

The survey fully supports patch-packs, including the ability for them to get a survey key.

First, an RSA private/public key is needed. This can be generated in various of ways, but for example via openssl:

• Private key: openssl genrsa -out privatekey.pem 2048
• Public key (based on the private key above): openssl rsa -in privatekey.pem -outform PEM -pubout -out publickey.pem

Now the public key (without the lines starting with ----) needs to be added under workers/src/public_keys/ and workers/src/public_keys/index.js needs to be adjusted to import the new key. The name of the file under public_keys/ is important, as this is part of the URL to retrieve a new survey key. Requests to this URL have to be signed with the private key of which the public key is in this repository.

Make a Pull Request out of this change, and point to where your patch-pack can be found etc.

Next, the contents of the private key file (privatekey.pem) needs to be added as the SURVEY_SIGNING_KEY secret to the GitHub Actions of your repository. Now for the last part, add the SURVEY_TYPE variable to the GitHub Actions of your repository matching the name of the file above. The patch-pack can now safely create new survey keys. See OpenTTD's workflow (release-source.yml) for more details exactly how.