diff --git a/docs/README.rst b/docs/README.rst new file mode 100644 index 0000000..17460fa --- /dev/null +++ b/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. diff --git a/docs/cryptor.rst b/docs/cryptor.rst new file mode 100644 index 0000000..a809690 --- /dev/null +++ b/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 + diff --git a/docs/model.rst b/docs/model.rst new file mode 100644 index 0000000..6e4542a --- /dev/null +++ b/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. diff --git a/docs/passvault.rst b/docs/passvault.rst new file mode 100644 index 0000000..78c5e50 --- /dev/null +++ b/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 `_. + +.. [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. + +