Merge pull request #2833 from derekpierre/tmckf-diagram-updates

TreasureMapConKFrags docs updates (diagram and notes)

docs/source/architecture/character.rst

@@ -40,9 +40,17 @@ When Alice wants to share this information with Bob, she can create a
 policy in the NuCypher Network to grant access to him. To grant access to Bob, Alice must:
 
 #. Create a re-encryption key based on the asymmetric private key and Bob's public key
-#. Configure the conditions of the policy e.g. *expiration time, m-of-n threshold values*
+#. Determine `n` Ursulas from the NuCypher Network to use in the policy
-#. Deploy the policy including associated fees to the blockchain
+#. Configure the conditions of the policy, e.g. *expiration time, m-of-n threshold values*
-#. Deploy `n` policy arrangements, each containing a re-encryption key fragment, `kFrag`, to `n` nodes on the NuCypher Network
+#. Deploy the policy to the blockchain and escrow associated policy fees
+#. Create a `treasure map`, encrypted for Bob that contains the list of `n` Ursulas in the policy,
+   and the `n` re-encryption key fragments (`kFrags`), each encrypted for a different Ursula in
+   the policy.
+
+   .. note::
+
+      Bob can decrypt the encrypted treasure map, but since each re-encryption fragment is encrypted
+      for a specific Ursula, Bob never has access to any re-encryption fragment in plaintext form.
 
 
 Enrico::Encrypt
@@ -70,20 +78,22 @@ Bob::Retrieve
 When Bob wants to access the data, he must first obtain the encrypted data and `capsule` from encrypted storage.
 However, this data is currently encrypted and inaccessible to Bob.
 
-In order to gain access, Bob must request re-encryption of the `capsule` by the `n` Ursulas that Alice previously
+To gain access, Bob must request re-encryption of the `capsule` by the `n` Ursulas that participated in the policy.
-distributed `kFrags` to. Remember that when Alice granted access to Bob, she distributed `n`
+Remember that when Alice granted access to Bob, she created a `treasure map` that contained
-`kFrags` of a re-encryption key for Bob to `n` Ursulas on the network. Therefore, Bob sends his `capsule` to `n`
+this list of `n` Ursulas in the policy, and the associated encrypted re-encryption key fragments (`kFrags`) for Bob to
-Ursulas in the NuCypher Network that have a corresponding `kFrag` for that policy. Those Ursulas
+give to the Ursulas for the re-encryption operation. Therefore, Bob sends his `capsule` and the relevant encrypted
-will use their `kFrag` to perform a partial re-encryption operation on the `capsule` and produce a corresponding
+`kFrag` to the various Ursulas in the NuCypher Network associated with the policy. Those Ursulas
-ciphertext fragment, `cFrag`. In the same way a `kFrag` is a fragment of a key, a `cFrag` is a fragment of ciphertext.
+will decrypt the encrypted `kFrag` and use it to perform a partial re-encryption operation on the `capsule` to
-The `cFrag` is returned to Bob, who collects `cFrags` until he obtains a threshold, `m`, number of `cFrags`.
+produce a corresponding ciphertext fragment, `cFrag`. In the same way a `kFrag` is a fragment of a key, a `cFrag`
-Bob attaches `m` received `cFrags` to the original `capsule` to obtain the fully re-encrypted `capsule` that is now
+is a fragment of ciphertext. The `cFrag` is returned to Bob, who collects `cFrags` until he obtains a threshold, `m`,
-encrypted under his public key. Note that the generation of a complete re-encrypted `capsule` is possible from a
+number of `cFrags`. Bob attaches `m` received `cFrags` to the original `capsule` to obtain the fully re-encrypted
-smaller number of `cFrags` than the number of `kFrags` originally sent out to Ursulas (m-of-n threshold scheme). Bob
+`capsule` that is now encrypted under his public key. Note that the generation of a complete re-encrypted `capsule`
-can now decrypt the `capsule` to obtain the symmetric key originally used to encrypt the bulk data.
+is possible from a smaller number of `cFrags` than the number of `kFrags` included in the `treasure map`
+(m-of-n threshold scheme). Bob can now decrypt the `capsule` to obtain the symmetric key originally used to
+encrypt the bulk data.
 
 Once Bob has the symmetric key, he can use it to decrypt the bulk data. This process can be repeated as more data is
-shared with Bob that is associated with `label` for the policy.
+shared with Bob that is associated with the `label` for the policy.
 
 Ultimately, because of the KEM/DEM approach, only the `capsule` needs to be re-encrypted for Bob.
 Subsequently, the size of the actual bulk data is irrelevant - whether 1KB or 1GB the re-encryption operation only
@@ -96,7 +106,7 @@ Ursula::Reencrypt
 .. image:: ../.static/img/ursula_reencrypt.svg
     :target: ../.static/img/ursula_reencrypt.svg
 
-Having previously received a `kFrag` from Alice when the policy arrangement was issued, Ursula can now partially
+Having received an encrypted `kFrag` and a `capsule` from Bob as part of the re-encryption request,
-re-encrypt data for Bob. Ursulas use their `kFrag` on the `capsule` provided by Bob and return a
+Ursula can now partially re-encrypt data for Bob. Ursulas decrypt the encrypted `kFrag` using their private key, and
-corresponding `cFrag`. Bob will require `m` of these interactions with `m` different Ursulas to obtain a fully
+use it to perform a re-encryption operation on the `capsule` to return a corresponding `cFrag`. Bob will
-re-encrypted `capsule`.
+require `m` of these interactions with `m` different Ursulas to obtain a fully re-encrypted `capsule`.

docs/source/glossary.rst

@@ -76,7 +76,7 @@ Glossary
       The public key for a :term:`Character`'s signing key pair.
 
     Treasure Map
-      The locations of :term:`Ursulas<Ursula>` that have the relevant :term:`kFrags<kFrag>` for a policy. :term:`Bob` will use the treasure map to determine which :term:`Ursulas<Ursula>` to contact to re-encrypt the data :term:`Alice` has shared with him.
+      The locations of :term:`Ursulas<Ursula>` and associated encrypted :term:`kFrags<kFrag>` for a policy. :term:`Bob` will use the treasure map to determine which :term:`Ursulas<Ursula>` to contact to re-encrypt the data :term:`Alice` has shared with him.
 
     Umbral
       NuCypher's threshold proxy re-encryption scheme - it takes standard :term:`PRE` and increases security and performance. See Umbral_.

docs/source/index.rst

@@ -21,11 +21,12 @@ How does NuCypher work?
 anyone she wants by creating a policy and uploading it to
 the NuCypher network.
 
-2. A group of Ursulas, which are nodes on the NuCypher network,
+2. Alice gets information about the group of ``n`` Ursulas associated
-receive information about the policy, called a ``PolicyArrangement`` that include
+with the policy, which are nodes on the NuCypher network. Each Ursula provides their encrypting key, and Alice creates
-a re-encryption key share. The Ursulas stand ready to re-encrypt data in exchange for payment
+``n`` re-encryption key shares (:term:`kFrag`), each of which is encrypted with a different Ursula's encrypting key.
-in fees and token rewards. Thanks to the use of proxy re-encryption,
+The Ursulas in the group stand ready to re-encrypt data in exchange for payment in fees and token rewards.
-Ursulas and the storage layer never have access to Alice's plaintext data.
+The list of Ursulas and their associated encrypted re-encryption key shares are stored in a treasure map. Alice
+subsequently encrypts the treasure map for Bob. The treasure map provides Bob the requisite information and cryptographic material to successfully request the NuCypher network to re-encrypt the data shared by Alice – such that he can decrypt it with his private key. 
 
 3. Each policy created by Alice has an associated encryption key, which can be used
 by any entity (Enrico) to encrypt data on Alice's behalf.
@@ -35,15 +36,17 @@ data that belongs to her – for example, a lab analyzing medical tests.
 The resulting encrypted data can be uploaded to IPFS, Swarm, S3,
 or any other storage layer.
 
-4. Bob, a data recipient, obtains the encrypted data from the storage layer and sends an access request
+4. Bob, a data recipient, uses the treasure map to determine the list of Ursulas to contact and the associated
-to the NuCypher network. If the policy is satisfied, the data is re-encrypted to his public key
+re-encryption key share to send to Ursula for the re-encryption operation. Bob obtains the encrypted data from the
-and he can decrypt it with his private key.
+storage layer and sends a re-encryption request to the relevant Ursulas on the NuCypher network. If the policy is
+satisfied, Ursula decrypts the provided re-encryption key share and re-encrypts the data to Bob's public key. Bob
+can subsequently decrypt the data with his private key.
 
-5. Ursulas earn fees and token rewards for performing
+5. Ursulas earn fees and token rewards for being available to perform re-encryption operations.
-re-encryption operations.
 
 More detailed information:
 
+- :ref:`character-concepts`
 - GitHub https://www.github.com/nucypher/nucypher
 - Website https://www.nucypher.com/
 

newsfragments/2833.doc.rst

@@ -0,0 +1 @@
+Update documentation to reflect new TreasureMap con KFrags design.