Add documentation on Red October internals.

docs/README.rst

@@ -0,0 +1,18 @@
+How Red October works
+=====================
+
+This is a roadmap to the docs here that cover Red October's design and
+how it works internally.
+
+Start with ``model.rst`` for an overview of the Red October model.
+
+The ``delegation.rst`` [1]_ file discusses delegations, which is the
+mechanism by which Red October does decryption.
+
+The ``passvault.rst`` file discusses the user vault and user records.
+
+The mechanics of encryption and decryption are covered in the
+``cryptor.rst`` file.
+
+
+.. [1] TODO.

docs/cryptor.rst

@@ -0,0 +1,47 @@
+The Cryptor package
+===================
+
+or, How RO actually encrypts and decrypts
+-----------------------------------------
+
+The Cryptor uses the ``EncryptedData`` structure for ciphertexts, the
+``passvault`` for user records. The ``keycache`` package provides a
+cache for actively-delegated keys.
+
+See also: passvault.txt
+
+Encryption:
+
+	1. Create a new EncryptedData structure.
+	   - The version is set to the default version compiled into
+             Red October.
+	   - The vault ID recorded in the EncryptedData is checked
+             against the vault's ID. This is a sanity check to help
+             catch the case where data was encrypted to a different
+             vault. This is not a security mechanism, it's to help
+	     users in multi-redoctober instances.
+	   - Generate a random AES CBC IV.
+	   - Generate a random AES key.
+	2. The AES encryption key is wrapped to the appropriate users
+           based on the access structure provided. This results in a
+	   number of keys wrapped to users.
+	3. The plaintext is encrypted with AES-CBC (no HMAC is applied
+           yet).
+	4. Any labels provided are added to the structure.
+	5. An HMAC-SHA1 is computed over the following:
+	   1. The string version of the vault version,
+	   2. the string version of the vault ID,
+	   3. the sorted wrapped keys (writing the user name and key),
+	   4. the IV,
+	   5. the encrypted data, and
+	   6. the sorted labels.
+	6. This HMAC is stored in the ``Signature`` field of the
+           ``EncryptedData`` structure.
+	7. The structure is "locked" with the HMAC key:
+	   1. The structure is serialised to JSON.
+	   2. An HMAC is computed over the serialised JSON.
+	   3. The structure is replaced with another ``EncryptedData`` structure:
+	      + Version ← -1
+	      + Data ← serialised JSON
+	      + Signature ← the HMAC
+

docs/model.rst

@@ -0,0 +1,39 @@
+The Red October encryption model
+==========================
+
+Red October is a system for encrypting and decrypting data using the
+two-person rule [1]_. It is intended for securing data where the
+requirement that multiple individuals agree to decrypt the data.
+
+Users have a public keypair generated for them (either RSA or elliptic
+curve); users never have access to this key directly. Instead, their
+key is protected using a passphrase supplied to scrypt.
+
+The server encrypts data by using these public keys and an access
+policy: the server generates a random symmetric key, and uses the
+access control policy (either two-person or MSP [2_]) to encrypt the
+key appropriately. The encryptor can add additional information,
+called labels, that must also be supplied for the decryption to
+succeed.
+
+A user is said to "delegate" [3]_ their key to the server in order to
+decrypt data, in which case they supply their password to the
+server. The server then decrypts their private key; when a decryption
+is requested later, if this decrypted key is still valid (delegations
+can expire or otherwise be invalidated based on certain constraints),
+the server can use this to perform a decryption.
+
+
+Notes:
+-----
+
+.. [1] https://en.wikipedia.org/wiki/Two-man_rule
+
+.. [2] MSP is a monotone span program; they are introduced in the paper
+       http://www.math.ias.edu/~avi/PUBLICATIONS/MYPAPERS/KW93/proc.pdf.
+       The high-level overview is that it permits more complex access
+       policies such as Alice and (Bob or Carol): Alice is always needed
+       for decryption, and one of Bob or Carol is needed to decrypt.
+
+.. [3] Delegations are covered more in-depth in the "delegation.txt"
+       file.

docs/passvault.rst

@@ -0,0 +1,30 @@
+The Red October PassVault
+=========================
+
+Package: passvault
+
+See also: model.txt
+
+The PassVault structure stores the user records [1]_ for the vault, as
+well as the version of vault structure, the vault's ID [2]_, and an
+HMAC key.
+
+User records store the user's encryption key, the Scrypt hash and salt
+for the user's password, and some metadata about the user. The
+metadata is currently only used to store the user's HipChat name; in
+the future, it could be used to support multiple notification
+backends. They also provide support for returning the user's
+encryption key and password validation.
+
+The vault structure is responsible for the management of user records,
+such as changing passwords and adding records.
+
+.. [1] In the ``passvault`` package, these records are called
+       `PasswordRecords <https://godoc.org/github.com/cloudflare/redoctober/passvault#PasswordRecord>`_.
+
+.. [2] The vault ID is a randomly (using the OS cryptographic RNG)
+       generated 32-bit signed integer that is used to identify the
+       vault. This is used when decrypting as a sanity check to make
+       sure that the ciphertext was encrypted using this vault.
+
+