Contributing to SoloKeys

Thank you for your interest in contributing to SoloKeys!

Background

SoloKeys, Inc. is a commercial entity that develops open source software (GPL-3.0-or-later) and hardware (CC-BY-SA-4.0), in order to produce and sell both locked and unlocked security tokens.

We are strong believers that security must be transparent, in fact, this is the reason we created SoloKeys! So why do we also (and perhaps mainly) sell locked keys? The keys we sell to non-hacker customers are locked in multiple ways:

  • debugging is permanently disabled
  • readout protection level 2 is activated
  • the USB firmware interface accepts only signed updates

The reason is that this helps prevent “evil maid attacks”, meaning that nobody should be able to easily modify the firmware running on the key to steal the secret key material or inject malware (“BadUSB”).

Additionally, the embedded (secret!) attestation key allows to easily confirm that a Solo is genuine and has not been tampered with, from when we originally program it, throughout the entire supply chain, until it reaches the end user.

If we were not the owners of the original intellectual property that we release under these open source licences, we would not be allowed to sell these locked keys. In order to stay in the business of selling keys (which in turn enables us to continue improving and extending the software and hardware) we need to stay legal!

For these reasons, we require contributors to the SoloKeys project to assign us more permissive licenses, so-called “contributor license agreements”. While certain projects ask for a CAA (copyright assignment agreements), expressed in non-legal terms we simply ask you to allow us to use your code in our project as we see fit.

We note that the firmware running on the locked keys (which unfortunately cannot to our knowledge be verified, but please let us know if you find a way with proof-of-secure-erasure or zk-SNARKs or other constructions!) is exactly the same as the code running on the unlocked keys (which can be easily verified by falling back to the STM32 bootloader). The only difference is that the locked key contains our attestation key as additional data - this allows easy verification that the key is genuine. On the other hand, future (signed) firmware updates for the locked keys will be verifiable via our Docker build environment (in fact, you can use your own build, and our signature).

Procedure

There are two CLAs that we use, depending on whether the copyright owner is an individual or an entity:

They are lightly modified HARMONY agreements, please read them carefully if you intend to contribute to SoloKeys. These are the same as the ones the Ubuntu Linux project uses.

If and when you add a pull request to any repository in the GitHub SoloKeys organization, a bot will check if your GitHub user handle is associated with a signed CLA, and if not, send you to this page for further information.

There is a lightweight and a heavyweight way to sign these agreements. For substantial pull requests, touching the guts of the project (exposing us to higher legal risk), we will reach out to you to exchange the heavyweight CLA, which asks for more details such as your address, and an actual signature. For smaller pull requests, the process is easy:

  • fork our https://github.com/solokeys/contributors repository
  • if you are submitting your contribution as an individual
    • copy INDIVIDUAL-CLA.md to individual/<your GitHub handle>.md
    • add your details
  • if you are submitting your contribution as an entity
    • copy ENTITY-CLA.md to entity/<your GitHub handle>.md
    • add your details
  • send us a pull request

We will then review and merge your agreement, and add you to the CONTRIBUTORS.md file

Our CLA bot will then label your original pull request as cla-signed, and we can merge it unless we deem that it falls in the heavyweight category.

Feedback

If you have any questions about this procedure, or suggestions how to improve it while allowing us to continue to produce keys, please reach out to us via [email protected]

If you would like to contribute to SoloKeys, but are absolutely unwilling to sign a CLA, please also talk to us, and we will see if we can find an alternative solution that enables us to both merge your contribution and continue the SoloKeys project!