README: Document the new key migration process

Applications need to be signed by a set of keys that are generated
during the build. When they change, if they is no key migration done,
they can prevent the device from booting.

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

1 files changed, 36 insertions, 13 deletions

diff --git a/README.txt b/README.txt
index 0f5f9bb..7320dc8 100644
--- a/README.txt
+++ b/README.txt
@@ -40,11 +40,11 @@ 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.
+and another, without any key migration procedure, 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.
@@ -57,8 +57,8 @@ 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.
+As the generated keys for a given release 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
@@ -66,12 +66,35 @@ Replicant 6.0 0004, the release version is now part of the image and can be foun
 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.
+Changing keys too often currently have huge downsides given how the migration
+script is designed:
+- If the script would check if it needs to run at each boot, then it would need
+  to handle cases like upgrade->downgrade->upgrade to not corrupt users data.
+- If the script replaces the old key (if found) with the new ones at each boot,
+  then it increases a lot the risk of data loss over time. In addition, at the
+  time of writing, running that script takes about 5 seconds, even if no keys
+  need to be changed. The more old keys we need to migrate from, the more time
+  it will take to run.
+
+So to keep the code simple and robust we want to make sure that the script is
+only run at the first boot after an installation, without using any complicated
+logic however:
+- /etc/init.d scripts cannot delete themselves. Allowing that triggers some
+  neverallow errors during the compilation of the selinux policies.
+- Importing other *.rc init files from /system (once it is mounted) results
+  in a phone that doesn't boot.
+
+So the solution that has been chosen is to do 2 releases at the same time:
+- The first release would migrate the keys automatically.
+- The second release will keep the script but not run it automatically
+  anymore.
+
+This way, once the migration is done, it doesn't increase the risk of data
+loss anymore. In that regard it is similar to the unofficial LineageOS data
+migration procedure (https://blunden.se/migration) that is done only once in
+the recovery, through an update zip. However here it also handles encrypted
+partitions as our script run in Replicant. In addition users can more easily
+generate scripts to downgrade/upgrade between different keys.
 
 Adding the last commits before the release:
 --------------------------------------------