Release procedure: Add information about key handling

Before, during and after a release, we need to manage signing keys:
- We might need to take care of keeping the gpg signing key still
  valid (not expired) for some time after the release.
- We also may need to migrate from one set of keys generated during
  the build process to a new one.

Signed-off-by: Denis 'GNUtoo' Carikli <GNUtoo@cyberdimension.org>

2 files changed, 81 insertions, 1 deletions

diff --git a/README.txt b/README.txt
index 09f61bb..9964b46 100644
--- a/README.txt
+++ b/README.txt
@@ -2,6 +2,77 @@
 + Release process +
 +-----------------+
 
+Key management and associated commits:
+--------------------------------------
+Replicant releases use several different set of keys:
+- The images being built are at the end signed with a gpg key. That gpg
+  key needs to be defined in the RELEASE_KEY variable in the releasevars.sh
+  file. Users are expected to manually verify at least the recovery with the
+  associated public key as part of the installation instructions.
+- In addition, during the build process, additional keys and certificates are
+  generated. These are for instance used to sign the Android applications that
+  are built as part of the Replicant images. They are also used by the recovery
+  to check if the zip being installed is built with the same keys. If not it
+  will simply refuse to install it. As the users already verified the gpg
+  signature of the recovery, this can also be used to simplify the installation
+  instructions by making users check the signature only for the recovery.
+
+When the developer doing the release changes, none of these keys are passed
+around to the new developer:
+- Having the developer's personal GPG keys enable people to more easily verify
+  the developer's key as people can check that directly instead of checking
+  the keys of the people who signed a Replicant release key. In addition, there
+  is more security as the key don't need to be transferred from person to person.
+- As for the keys and certificates generated build process, they don't need to
+  be passed around either.
+
+So when a developer is doing a release, that developer gpg public key is
+published automatically as part of the release process, and the installation
+instructions already contain instructions on how to download and use that public
+key, so no extra steps are needed during the release.
+
+However the key (or subkey) signing the release needs to be kept valid (not
+expired) for as long as it is relevant for less technical users to install
+any of the releases signed by that key.
+
+As for the keys generated during the build, the release instructions already
+take care of making users install the recovery associated with a given release,
+so that part is being taken care of.
+
+However if the keys signing system application changed between one release
+and another, users won't be able to upgrade to the new release without wiping
+their data. As this would be extremely inconvenient for users (which potentially
+includes yourself as well), we can generate a shell script that will take care of
+the migration from the old set of keys to the new one during the first run of the
+new Replicant image.
+
+In vendor/replicant-scripts/images/gen_key_migration_script, there is a python
+script (gen_key_migration_script.py) that can generate that shell script.
+
+Once generated, that shell script needs to be copied in
+vendor/replicant/prebuilt/common/bin/key-migration.sh and a commit needs to be
+made in vendor/replicant to add it to the Replicant source code.
+
+Once the commit is made, it doesn't necessarily need to be pushed to a branch:
+if it is in the Replicant source code that will be tagged on later, it will then
+be pushed to the tag. The next sections have more more details on that.
+
+Alternatively, as the generated keys are in vendor/replicant-security/, it is
+also possible to keep the same keys from one release to the next.
+
+The downside of keeping the same keys is that it slightly increase the security
+risk as these keys are also used by the recovery to check the zip. Still, since
+Replicant 6.0 0004, the release version is now part of the image and can be found
+in Settings->About phone to mitigate the fact that the same set of keys could
+also end up signing images that are not part of a release.
+
+In another hand, changing the keys at each release would increase the number of
+public keys, which will make the migration script slower and slower over time.
+As at the time of writing, it check if keys need to be changed at each boot, and
+that already takes a significant amount of time (about 5 seconds) so if we were
+to change the generated keys at each release, we would also need to redesign part
+of that script.
+
 Adding the last commits before the release:
 --------------------------------------------
 Before a release, we need to make some additional changes in several
diff --git a/releasevars.sh b/releasevars.sh
index 896d4f8..d3c7f59 100755
--- a/releasevars.sh
+++ b/releasevars.sh
@@ -67,7 +67,16 @@ RELEASE_DEVICES="\
 	n5110 \
 "
 
-RELEASE_KEY="FB31DBA3AB8DB76A4157329F7651568F80374459"
+RELEASE_KEY=""
+if [ -z "${RELEASE_KEY}" ] ; then
+    echo "You need to define the RELEASE_KEY variable in the releasevars.sh script."
+    echo "This variable contains the gpg key that will sign the images you are releasing."
+    echo
+    echo "For example:"
+    echo "    RELEASE_KEY=\"FB31DBA3AB8DB76A4157329F7651568F80374459\""
+    exit 1
+fi
+
 REPO="repo"
 COLOR=1