Permissioning overview (#812)

Added permissions doc Signed-off-by: Adrian Sutton <adrian.sutton@consensys.net>
6 years ago · dfdf994e2d
parent 5a1389b970
commit dfdf994e2d
2 changed files with 134 additions and 0 deletions
--- a/docs/Permissions/Permissioning.md
+++ b/docs/Permissions/Permissioning.md
@ -0,0 +1,132 @@
+description: Pantheon Permissions feature
+<!--- END of page meta data -->
+
+# Permissions 
+
+A permissioned network is a network where only specified nodes and accounts (participants) can participate. 
+Nodes and accounts outside those specified are prevented from participating. Permissioned networks can have node permissions enabled, 
+account permissions enabled, or both. 
+
+## Node Whitelisting 
+
+Node whitelisting is specified by the nodes whitelist in the [`permissions_config.toml`](#permissions-configuration-file) file. 
+A node with node whitelisting enabled communicates only with nodes in the nodes whitelist. 
+
+!!! example "Nodes Whitelist in `permissons_config.toml`"
+    `nodes-whitelist=["enode://6f8a80d14311c39f35f516fa664deaaaa13e85b2f7493f37f6144d86991ec012937307647bd3b9a82abe2974e1407241d54947bbb39763a4cac9f77166ad92a0@192.168.0.9:4567","enode://6f8a80d14311c39f35f516fa664deaaaa13e85b2f7493f37f6144d86991ec012937307647bd3b9a82abe2974e1407241d54947bbb39763a4cac9f77166ad92a0@192.169.0.9:4568"]`
+
+Node whitelisting is at the node level. That is, each node in the network has a [`permissions_config.toml`](#permissions-configuration-file)
+file in the [data directory](../Reference/Pantheon-CLI-Syntax.md#data-path) for the node.  
+
+To view or update the nodes whitelist when the node is running, use the JSON-RPC API methods:
+ 
+* [perm_addNodesToWhitelist](../Reference/JSON-RPC-API-Methods.md#perm__addnodestowhitelist)
+* [perm_removeNodesFromWhitelist](../Reference/JSON-RPC-API-Methods.md#perm_removeNodesFromWhiteList)
+* [perm_getNodesWhitelist](../Reference/JSON-RPC-API-Methods.md#perm_getNodesWhiteList)
+
+!!! note
+    Each node has a `permissions_config.toml` file which means nodes can have different nodes whitelists. 
+    This means nodes may be participating in the network that are not on the whitelist of other nodes in the network. 
+    We recommend each node in the network has the same nodes whitelist. 
+    
+    On-chain permissioning is under development. On-chain permissioning will use one on-chain 
+    nodes whitelist. 
+    
+!!! example "Example Different Node Whitelists" 
+
+    Node 1 Whitelist = [Node 2, Node 3] 
+    
+    Node 2 Whitelist = [Node 3, Node 5] 
+    
+    Node 5 is participating in the same network as Node 1 even though Node 1 does not have Node 5 on their whitelist.
+
+### Bootnodes
+
+The bootnodes must be included in the nodes whitelist or Pantheon does not start when node permissions are enabled. 
+
+!!! example 
+    If you start Pantheon with:
+    
+     ```bash
+     --bootnodes="enode://7e4ef30e9ec683f26ad76ffca5b5148fa7a6575f4cfad4eb0f52f9c3d8335f4a9b6f9e66fcc73ef95ed7a2a52784d4f372e7750ac8ae0b544309a5b391a23dd7@127.0.0.1:30303","enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304","enode://7b61d5ee4b44335873e6912cb5dd3e3877c860ba21417c9b9ef1f7e500a82213737d4b269046d0669fb2299a234ca03443f25fe5f706b693b3669e5c92478ade@127.0.0.1:30305" 
+     ```
+    
+    The `nodes-whitelist` in [`permissions_config.toml`](#permissions-configuration-file) must contain the specified bootnodes. 
+
+### Enabling Node Whitelisting     
+
+To enable node whitelisting, specify the [`--permissions-nodes-enabled`](../Reference/Pantheon-CLI-Syntax.md#permissions-nodes-enabled) option 
+when starting Pantheon. 
+
+The `PERM` API methods are not enabled by default. Use the [`--rpc-http-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-api) 
+or [`--rpc-ws-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-api) options to enable the `PERM` API methods.
+
+## Account Whitelisting 
+
+Account whitelisting is specified by the accounts whitelist in the [`permissions_config.toml`](#permissions-configuration-file) file.
+A node with account permissions accepts transactions only from accounts in the accounts whitelist. 
+
+!!! example "Accounts Whitelist in `permissons_config.toml`"
+    `accounts-whitelist=["0x0000000000000000000000000000000000000009"]`
+    
+Account whitelisting is at the node level. That is, each node in the network has a [`permissions_config.toml`](#permissions-configuration-file)
+file in the [data directory](../Reference/Pantheon-CLI-Syntax.md#data-path) for the node.    
+    
+Transactions are validated against the accounts whitelist at the following points: 
+
+1. Submitted by JSON-RPC API method [`eth_sendRawTransaction`](../Reference/JSON-RPC-API-Methods.md#eth_sendrawtransaction) 
+1. Received via propagation from another node 
+1. Added to a block by a mining node 
+
+Once added to a block, the transactions are not validated against the whitelist when received by another node. That is, a node 
+can synchronise and add blocks containing transactions from accounts that are not on the accounts whitelist of that node.      
+    
+!!! example "Example Different Account Whitelists"
+    Node 1 Whitelist = [Account A, Account B]
+    
+    Node 2 Whitelist = [Account B, Account C]
+    
+    Mining Node Whitelist = [Account A, Account B]
+    
+    Account A submits a transaction on Node 1. Node 1 validates and propagates the transaction. The Mining Node receives the transaction, 
+    validates it is from an account in the Mining Node accounts whitelist, and includes the transaction in the block. Node 2 receives and 
+    adds the block created by the Mining Node.
+     
+    Node 2 now has a transaction in the blockchain from Account A which is not on the accounts whitelist for Node 2.   
+
+!!! note
+    Each node has a [`permissions_config.toml`](#permissions-configuration-file) file which means nodes in the network can have different accounts whitelists. 
+    This means a transaction can be successfully submitted by Node A from an account in the Node A whitelist but rejected by 
+    Node B to which it is propagated if the account is not in the Node B whitelist. 
+    We recommend each node in the network has the same accounts whitelist. 
+        
+    On-chain permissioning is under development. On-chain permissioning will use one on-chain 
+    nodes whitelist. 
+
+To view or update the accounts whitelist when the node is running, use the JSON-RPC API methods: 
+
+* [perm_addAccountsToWhitelist](../Reference/JSON-RPC-API-Methods.md#perm_addAccountsToWhitelist)
+* [perm_removeAccountsFromWhitelist](../Reference/JSON-RPC-API-Methods.md#perm_removeAccountsFromWhitelist)
+* [perm_getAccountsWhitelist](../Reference/JSON-RPC-API-Methods.md#perm_getAccountsWhitelist)
+
+### Enabling Account Whitelisting 
+
+To enable account whitelisting, specify the [`--permissions-accounts-enabled`](../Reference/Pantheon-CLI-Syntax.md#permissions-accounts-enabled) option 
+when starting Pantheon. 
+
+The `PERM` API methods are not enabled by default. Use the [`--rpc-http-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-api) 
+or [`--rpc-ws-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-api) options to enable the `PERM` API methods.
+
+## Permissions Configuration File 
+
+The `permissions_config.toml` file contains the nodes and accounts whitelists. The `permissions_config.toml` 
+must be in the [data directory](../Reference/Pantheon-CLI-Syntax.md#data-path) for the node.
+
+!!! example "Example permissions_config.toml"  
+    ```toml 
+    accounts-whitelist=["0xb9b81ee349c3807e46bc71aa2632203c5b462032", "0xb9b81ee349c3807e46bc71aa2632203c5b462034"]
+    
+    nodes-whitelist=["enode://7e4ef30e9ec683f26ad76ffca5b5148fa7a6575f4cfad4eb0f52f9c3d8335f4a9b6f9e66fcc73ef95ed7a2a52784d4f372e7750ac8ae0b544309a5b391a23dd7@127.0.0.1:30303","enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304","enode://7b61d5ee4b44335873e6912cb5dd3e3877c860ba21417c9b9ef1f7e500a82213737d4b269046d0669fb2299a234ca03443f25fe5f706b693b3669e5c92478ade@127.0.0.1:30305"]
+    ```
+
+
--- a/mkdocs.yml
+++ b/mkdocs.yml
@ -69,6 +69,8 @@ nav:
        - Logging: Configuring-Pantheon/Logging.md
        - Bootnodes: Configuring-Pantheon/Bootnodes.md
        - Passing JVM Options: Configuring-Pantheon/Passing-JVM-Options.md
+    - Permissions:
+        - Nodes and Accounts Whitelists: Permissions/Permissioning.md
    - Using Pantheon:
        - Events and Logs:
          - Overview: Using-Pantheon/Events-and-Logs.md