mirror of https://github.com/hyperledger/besu
An enterprise-grade Java-based, Apache 2.0 licensed Ethereum client https://wiki.hyperledger.org/display/besu
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
154 lines
8.9 KiB
154 lines
8.9 KiB
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 configuration file](#permissions-configuration-file) file.
|
|
When node whitelisting is enabled, communication is restricted to only nodes in the whitelist.
|
|
|
|
!!! example "Nodes Whitelist in Permissions Configuration File"
|
|
`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 configuration file](#permissions-configuration-file)
|
|
file in the [data directory](../Reference/Pantheon-CLI-Syntax.md#data-path) for the node.
|
|
|
|
To 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)
|
|
|
|
Alternatively, update the [`permissions_config.toml`](#permissions-configuration-file) file directly and use the
|
|
[`perm_reloadPermissionsFromFile`](../Reference/JSON-RPC-API-Methods.md#perm_reloadpermissionsfromfile) method
|
|
to update the whitelists.
|
|
|
|
Updates to the permissions configuration file persist across node restarts.
|
|
|
|
To view the nodes whitelist, use the [perm_getNodesWhitelist](../Reference/JSON-RPC-API-Methods.md#perm_getNodesWhiteList) method.
|
|
|
|
!!! note
|
|
Each node has a [permissions configuration file](#permissions-configuration-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 specified bootnodes and have node permissions enabled:
|
|
|
|
```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 the [permissions configuration file](#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 configuration file](#permissions-configuration-file).
|
|
A node with account permissions accepts transactions only from accounts in the accounts whitelist.
|
|
|
|
!!! example "Accounts Whitelist in Permissions Configuration File"
|
|
`accounts-whitelist=["0x0000000000000000000000000000000000000009"]`
|
|
|
|
Account whitelisting is at the node level. That is, each node in the network has a [permisssions configuration file](#permissions-configuration-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 configuration file](#permissions-configuration-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 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)
|
|
|
|
Alternatively, update the [`permissions_config.toml`](#permissions-configuration-file) file directly and use the
|
|
[`perm_reloadPermissionsFromFile`](../Reference/JSON-RPC-API-Methods.md#perm_reloadpermissionsfromfile) method
|
|
to update the whitelists.
|
|
|
|
Updates to the permissions configuration file persist across node restarts.
|
|
|
|
To view the accounts whitelist, use the [`perm_getAccountsWhitelist`](../Reference/JSON-RPC-API-Methods.md#perm_getAccountsWhitelist) method.
|
|
|
|
### 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 configuration file contains the nodes and accounts whitelists. If the [`--permissions-config-file`](../Reference/Pantheon-CLI-Syntax.md#permissions-config-file)
|
|
option is not specified, the permissions configuration file must be called `permissions_config.toml` and
|
|
must be in the [data directory](../Reference/Pantheon-CLI-Syntax.md#data-path) for the node.
|
|
|
|
Use the [`--permissions-config-file`](../Reference/Pantheon-CLI-Syntax.md#permissions-config-file) option to specify a permissions configuration file
|
|
in any location.
|
|
|
|
!!! example "Example Permissions Configuration File"
|
|
```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"]
|
|
```
|
|
|
|
|
|
|