Merge remote-tracking branch 'qeng/feature/permissioning-1.8.18-suborgs' into feature/permissioning-1.8.18-suborgs

docs/Permissioning/Contract Design.md

@@ -10,4 +10,4 @@ The permissions smart contract design follows the Proxy-Implementation-Storage p
 * `AccountManager.sol`: This contract receives requests from valid implementation contract as defined in `PermissionsUpgrdable.sol`. This contracts stores the data of all accounts, their linkage to organization and various roles. This contracts also stores the status of an account. The account can be in any of the following states - `PendingApproval`, `Active`, `Suspended`, `Blacklisted`, `Revoked`
 * `NodeManager.sol`: This contract receives requests from valid implementation contract as defined in `PermissionsUpgrdable.sol`. This contracts stores the data of a node, its linkage to a organization or sub organization and status of the node. The node status can be any one of the following states - `PendingApproval`, `Active`, `Deactivated`, `Blacklisted`
 * `RoleManager.sol`: This contract receives requests from valid implementation contract as defined in `PermissionsUpgrdable.sol`. This contract stores data for various roles and the organization to which it is linked. At access at role level can be any one of the following: `Readonly` which allows only read operations, `Transact` which allows value transfer but no contract deployment access, `ContractDeploy` which allows both value transfer and contract deployment access and `FullAccess` which allows additional network level accesses in addition to value transfer and contract deployment. If a role is revoked all accounts which are linked to the role lose all access rights.
-* `VoterManager.sol`: This contract receives requests from valid implementation contract as defined in `PermissionsUpgrdable.sol`. This contract stores the data of valid voters at network level which can approve identified activities e.g. adding a new organization to the network. Any account which is linked to a predefined network admin role will be marked as a voter. Whenever a network level activity which requires voting is performed, a voting item is added to this contract and each voter account can vote for the activity. The activity is marked as `Approved` upon majority voting.
+* `VoterManager.sol`: This contract receives requests from valid implementation contract as defined in `PermissionsUpgrdable.sol`. This contract stores the data of valid voters at network level which can approve identified activities e.g. adding a new organization to the network. Any account which is linked to a predefined network admin role will be marked as a voter. Whenever a network level activity which requires voting is performed, a voting item is added to this contract and each voter account can vote for the activity. The activity is marked as `Approved` upon majority voting.

docs/Permissioning/Old Permissioning.md

@@ -22,21 +22,3 @@ Sample file: (node id truncated for clarity)
 
 !!! Note
     In the current implementation, every node has its own copy of the `permissioned-nodes.json` file. In this case, if different nodes have a different list of remote keys then each node may have a different list of permissioned nodes - which may have an adverse effect. In a future release, the permissioned nodes list will be moved from the `permissioned-nodes.json` file to a Smart Contract, thereby ensuring that all nodes will use one global on-chain list to verify network connections. 
-
-## Enclave Encryption Technique
-The Enclave encrypts payloads sent to it by the Transaction Manager using xsalsa20poly1305 (payload container) and curve25519xsalsa20poly1305 (recipient box). Each payload encryption produces a payload container,  as well as N recipient boxes, where N is the number of recipients specified in the `privateFor` param of the Transaction. 
-
- * A payload container contains the payload encrypted with a symmetric key and a random nonce
- * A recipient box is the Master Key for the payload container encrypted for the public key of a recipient using a random nonce. (Note that this is basically how PGP works, but using the [NaCl](https://nacl.cr.yp.to/) cryptographic primitives.)
-
-We currently manually define all public key whitelists, and don’t do automatic rotation of keys, however the system was built to support rotation trivially, by allowing counterparties to advertise multiple keys at once. The tooling to make it seamless and automatic is on the our Roadmap.
-We also do not currently have a PKI system, but simply randomly generate keys that are manually added to whitelists (e.g. a registry of authorized counterparties on the blockchain.) The process is currently for operators to generate a keypair and then add the public keys to the whitelists manually.
-
-## Private Key Storage Algorithm
-The following steps detail the technique used to manage the private keys:
-
- 1. Given a password P
- 2. Generate random Argon2i  nonce
- 3. Generate random NaCl secretbox  nonce
- 4. Stretch P using Argon2i (and the Argon2i nonce) into a 32-byte master key (MK)
- 5. Encrypt Private key in secretbox using secretbox nonce and Argon2i-stretched MK

docs/Permissioning/Overview.md

@@ -1,5 +1,5 @@
 # Introduction
-The current permission model with in Quorum is limited to node level permissions only and allows a set of nodes which are part of `permissioned-nodes.json` to join the network. The model has been enhanced to cater for enterprise level needs to have **smart contract based permissions model** which allows flexibility to manage nodes, accounts and account level access controls. The overview of the model is as depicted below:
+The [current permission model](../Old%20Permissioning.md) with in Quorum is limited to node level permissions only and allows a set of nodes which are part of `permissioned-nodes.json` to join the network. The model has been enhanced to cater for enterprise level needs to have **smart contract based permissions model** which allows flexibility to manage nodes, accounts and account level access controls. The overview of the model is as depicted below:
 ![permissions mode](images/PermissionsModel.png)  
 ### Key Definitions
 * Network - A set of interconnected nodes representing an enterprise blockchain which contains organizations

docs/Privacy/Tessera/Tessera Services/Enclave.md

@@ -12,6 +12,13 @@ This enables all sensitive operations to be handled in a single place, without a
 
 The Transaction Manager, which handles peer management and database access, as well as Quorum communication does not perform **any** encryption/decryption, greatly reducing the impact an attack can have.
 
+### Enclave Encryption Technique
+
+The Enclave encrypts payloads sent to it by the Transaction Manager using xsalsa20poly1305 (payload container) and curve25519xsalsa20poly1305 (recipient box). Each payload encryption produces a payload container,  as well as N recipient boxes, where N is the number of recipients specified in the `privateFor` param of the Transaction. 
+
+ * A payload container contains the payload encrypted with a symmetric key and a random nonce
+ * A recipient box is the Master Key for the payload container encrypted for the public key of a recipient using a random nonce. (Note that this is basically how PGP works, but using the [NaCl](https://nacl.cr.yp.to/) cryptographic primitives.)
+
 ### What exactly does the enclave handle?
 
 The Tessera enclave **handles** the following data:
@@ -30,6 +37,15 @@ The enclaves **performs** the following actions on request:
 - decrypting transactions for a given recipient (or sender)
 - adding new recipients for existing payloads
 
+### Private Key Generation Algorithm
+The following steps detail the technique used to manage the private keys:
+
+ 1. Given a password P
+ 2. Generate random Argon2id  nonce
+ 3. Generate random NaCl secretbox  nonce
+ 4. Stretch P using Argon2id (and the Argon2id nonce) into a 32-byte master key (MK)
+ 5. Encrypt Private key in secretbox using secretbox nonce and Argon2i-stretched MK
+
 ### Where does the Enclave sit in the private transaction flow?
 
 The Enclave is the innermost actor of the sequence of events. The below diagram demonstrates where the enclave sits:

docs/README.md

@@ -1,4 +1,4 @@
 
 # Quorum documentation
 
-New Quorum documentation is now published on https://goquorum.readthedocs.io/
+New Quorum documentation is now published on http://docs.goquorum.com

mkdocs.yml

@@ -23,8 +23,11 @@ nav:
         - Raft: Consensus/raft.md
         - Istanbul: Consensus/istanbul-rpc-api.md
     - Transaction Processing: Transaction Processing/Transaction Processing.md
-    - Security:
-        - Security & Permissioning: Security/Security & Permissioning.md
+    - Permissioning:
+        - Overview: Permissioning/Overview.md
+        - Design: Permissioning/Contract Design.md
+        - Setup: Permissioning/setup.md
+        - API: Permissioning/Permissioning apis.md       
     - Privacy:
         - Tessera:
             - What is Tessera: Privacy/Tessera/Tessera.md