Basic encrypted backup/restore test

This sets up a whole lot of infrastructure, too.

1 files changed, 84 insertions, 0 deletions

diff --git a/yarns/0060-encryption.yarn b/yarns/0060-encryption.yarn
new file mode 100644
index 00000000..6903de8f
--- /dev/null
+++ b/yarns/0060-encryption.yarn
@@ -0,0 +1,84 @@
+Encrypted repositories
+======================
+
+Obnam repositories may be encrypted. The encryption is based on public
+keys, using GnuPG specifically. Internally, symmetric encryption is
+also used, but that is not visible, nor relevant, to the user. All
+encryption requires some level of key management, so the encryption
+plugin in Obnam provides a number of subcommands for that.
+
+We need to test, at minimum, that key management works. Ideally, we'd
+also test that encryption works, but that's trickier to achieve
+without making assumptions about the repository format.
+
+Test setup
+----------
+
+We need two PGP keys for these tests, and they need to be independent
+of each other so that tests can meaningfully use the different keys to
+pretend they're different users. We have, in the Obnam source tree,
+two GnuPG keyrings (`test-data/keyring-1` and `test-data/keyring-2`),
+which we use for this purpose. We use pre-generated keys instead of
+generating new ones for each test run, since key generation is a
+fairly heavy operation that easily depletes the host of entropy.
+
+However, to avoid inadvertent changes to the keys, keyrings, random
+data seeds, or other files, we make a copy of the data into `$DATADIR`
+for the duration of the test.
+
+The keys have usernames `Test Key One` and `Test Key Two` (no e-mail
+addresses). They have no passphrase. Otherwise, they are generated
+using GnuPG defaults (as of 1.4.12 in Debian wheezy).
+
+Encrypted backup and restore
+----------------------------
+
+We'll make a simple backup and restore using encryption. If this
+works, we can probably assume that any other normal repository
+operations (those not part of encryption management) also work, given
+that encryption is done at the I/O abstraction level.
+
+    SCENARIO basic encrypted backup and restore
+    GIVEN user U uses encryption key "Test Key One" from test-data/keyring-1
+    AND directory L with interesting filesystem objects
+    AND a manifest of directory L in M
+    WHEN user U backs up directory L to repository R
+    AND user U restores their latest generation in repository R into X
+    THEN L, restored to X, matches manifest M
+
+Adding and removing keys to clients
+-----------------------------------
+
+Each client specifies the key they want to use with the
+`--encrypt-with` setting. This is the primary key for the client. The
+client may additionally use other keys to encrypt to: this allows, for
+example, having a repository-wide encryption key that can run fsck or
+forget.
+
+We test these by having two keys: one for the primary one, and a
+second one, and verifying that we can, or can't, access the backup
+with the second key, depending on whether it has or hasn't been added
+to the client.
+
+#       obnam [options] client-keys
+#       obnam [options] add-key [CLIENT-NAME]...
+#       obnam [options] remove-key [CLIENT-NAME]...
+
+Key queries
+-----------
+
+Obnam has a couple of commands to list the keys in the repository and
+what they have access to.
+
+#       obnam [options] list-keys
+#       obnam [options] list-toplevels
+
+Removing a client
+-----------------
+
+Obnam currently has a `obnam remove-client` command which only works
+when encryption is used. This is a wart, a bug, and a disgrace.
+However, it will be fixed some day, and until then the command is
+tested in this chapter.
+
+#       obnam [options] remove-client [CLIENT-NAME]...