Updated on June 29, 2020

# Local permissioning

Local permissioning supports node and account whitelisting.

## Node whitelisting

You can specify nodes in the nodes whitelist in the permissions configuration file file. With node whitelisting enabled, communication is only between nodes in the whitelist.

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 file in the data directory for the node.

To update the nodes whitelist when the node is running, use the JSON-RPC API methods:

You can also update the permissions_config.toml file directly and then update the whitelists using the perm_reloadPermissionsFromFile method.

Updates to the permissions configuration file persist across node restarts.

To view the nodes whitelist, use the perm_getNodesWhitelist method.

Note

Each node has a permissions configuration file, which means nodes can have different nodes whitelists. This means nodes might 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.

Onchain permissioning uses one onchain nodes whitelist.

An Example of 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 nodes whitelist must include the bootnodes or Hyperledger Besu does not start with node permissions enabled.

Example

If you start Besu with specified bootnodes and have node permissioning enabled:

--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 must contain the specified bootnodes.

### Enabling node whitelisting

To enable node whitelisting, specify the --permissions-nodes-config-file-enabled option when starting Besu.

The PERM API methods are not enabled by default. To enable the PERM API methods, use the --rpc-http-api or --rpc-ws-api options.

## Account whitelisting

You can specify accounts in the accounts whitelist in the permissions configuration file. A node with account permissioning accepts transactions only from accounts in the accounts whitelist.

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 in the data directory for the node.

Using account permissioning and privacy

Account permissioning is incompatible with random key signing for privacy marker transactions.

If using account permissioning and privacy, a signing key must be specified using the --privacy-marker-transaction-signing-key-file command line option and the signing key included in the accounts whitelist.

Transaction validation against the accounts whitelist occurs at the following points:

After adding transactions 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.

The following diagram illustrates applying local and onchain permissioning rules.

An Example of 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 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’s propagated if the account is not in the Node B whitelist. We recommend each node in the network has the same accounts whitelist.

To update the accounts whitelist when the node is running, use the JSON-RPC API methods:

You can also update the permissions_config.toml file directly and use the 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 method.

### Enabling account whitelisting

To enable account whitelisting, specify the --permissions-accounts-config-file-enabled option when starting Besu.

The PERM API methods are not enabled by default. To enable the PERM API methods, use the --rpc-http-api or --rpc-ws-api options.

## Permissions configuration file

The permissions configuration file contains the nodes and accounts whitelists. If the --permissions-accounts-config-file and permissions-nodes-config-file options are not specified, the name of the permissions configuration file must be permissions_config.toml and must be in the data directory for the node.

You can specify the accounts and nodes whitelists in the same file or in separate files for accounts and nodes.

To specify a permissions configuration file (or separate files for accounts and nodes) in any location, use the --permissions-accounts-config-file and permissions-nodes-config-file options.

Sample Permissions Configuration File

accounts-whitelist=["0xb9b81ee349c3807e46bc71aa2632203c5b462032", "0xb9b81ee349c3807e46bc71aa2632203c5b462034"]