Configuring Validator and Transactor Permissions
Note
These instructions have been tested on Ubuntu 18.04 (Bionic) only.
This section describes the validator and transactor permissions in Hyperledger Sawtooth.
- Transactor key permissioningcontrols who (which users and clients) can submit transactions and batches to a validator. Sawtooth provides both on-chain (network-wide) and off-chain (local) settings for transactor key permissioning.
- Validator key permissioning controls which nodes can connect to the Sawtooth network. These settings are configured with on-chain settings.
The Identity and Settings transaction processors (or equivalent) are required to process the on-chain settings. Note that Settings includes several settings to control who can change on-chain settings and how many votes are required for a settings change.
Note
Sawtooth also includes another type of transaction control that limits which transaction processors can submit transactions. For more information, see Setting the Allowed Transaction Types (Optional)”.
Transactor Key Permissioning
A running protected network needs a mechanism for limiting which transactors are allowed to submit batches and transactions to the validators. There are two different methods for defining the transactors that a validator will accept.
The first method is configuring a validator to only accept batches and transactions from predefined transactors that are loaded from a local validator config file. Once the validator is configured, the list of allowed transactors is immutable while the validator is running. This set of permissions are only enforced when receiving a batch from a connected client, but not when receiving a batch from a peer on the network.
The second method uses the Identity namespace which handles network-wide updates and agreement on allowed transactors. The allowed transactors are checked when a batch is received from a client, received from a peer, and when a block is validated.
When using both on-chain and off-chain configuration, the validator only accepts transactions and batches from a client if both configurations agree it should be accepted. If a batch is received from a peer, only on-chain configuration is checked.
It is possible that in the time that the batch has been in the pending queue, the transactor permissions have been updated to no longer allow a batch signer or a transaction signer that is being included in a block. For this reason, the allowed transactor roles must also be checked on block validation.
Off-chain Transactor Permissioning
Validators can be locally configured by creating a validation
configuration file, validator.toml
, and placing it in the config
directory. Add the configuration for transactor permissioning to this
file using the following format:
[permissions]
ROLE = POLICY_NAME
ROLE
is a role for transactor permissioning (see Transactor
Roles). POLICY_NAME
is the name of policy file in the policy_dir (/etc/sawtooth/policy
by
default). Multiple roles may be defined in the same format within the
validator configuration file.
The policies are stored in the policy_dir defined by the path config (see Configuraing Sawtooth.
Each policy consists of permit and deny rules, similar to policies
defined in the Identity namespace. Each line contains either a
PERMIT_KEY
or DENY_KEY
followed with either a public key for an
allowed transactor or the *
character to specify all possible
transactors. The rules are evaluated in order.
A policy file has the following format:
PERMIT_KEY {key}
DENY_KEY {key}
Specify one key per line. To define multiple permitted or denied keys,
use additional PERMIT_KEY
or DENY_KEY
lines.
Note
A policy file implicitly ends with the rule
DENY_KEY *
, which denies all transactors or validators that are not explicitly specified in aPERMIT_KEY
rule. For example, if a transactor policy file contains a single rule that permits one transactor, it is implicitly denying all other transactors.
On-chain Transactor Permissioning
The Identity namespace stores roles as key-value pairs, where the key is a role name and the value is a policy. All roles that limit who is allowed to sign transactions and batches should start with transactor as a prefix.
transactor.SUB_ROLE = POLICY_NAME
SUB_ROLEs are more specific signing roles, for example who is allowed to sign transactions. Each role equals a policy name that corresponds to a policy stored in state. The policy contains a list of public keys that correspond to the identity signing key of the transactors.
Before you can configure on-chain roles, your public key must be set in
the sawtooth.identity.allowed_keys
setting. Only those transactors
whose public keys are in that setting are allowed to update roles and
policies.
-
Make sure that the Identity and Settings transaction processors and the REST API are running, as described in Running Sawtooth as a Service.
-
Add your public key to the list of those allowed to change settings.
In the following command, change
{user}
to specify your own public key file.$ sudo sawset proposal create --key /etc/sawtooth/keys/validator.priv \ sawtooth.identity.allowed_keys=$(cat ~/.sawtooth/keys/{user}.pub)
Important
You must run this command on the same node that created the genesis block. Otherwise, an additional
sawset proposal create
command would be required on the "genesis node" to add a second node'svalidator.priv
key to thesawtooth.identity.allowed_keys
setting. This guide does not show that step. -
Once your public key is stored in the setting, use the command
sawtooth identity policy create
to set and update roles and policies.For example, running the following command will create a policy that permits all and is named
policy_1
:$ sawtooth identity policy create policy_1 "PERMIT_KEY *"
You can enter multiple permit or deny rules in the same command; separate each rule with a space.
Important
Be careful not to remove your permission to change Identity settings. Sawtooth will not prevent you from entering a rule to deny all transactors (including yourself).
-
To see the policy in state, run the following command:
$ sawtooth identity policy list policy_1: Entries: PERMIT_KEY *
-
Use the command
sawtooth identity role create
to create a role for this policy. The following example sets the role fortransactor
to the policy that permits all:$ sawtooth identity role create transactor policy_1
-
To see the role in state, run the following command:
$ sawtooth identity role list transactor: policy_1
Transactor Roles
The following identity roles are used to control which transactors are allowed to sign transactions and batches on the system.
-
default
: -
When evaluating role permissions, if the role has not been set, the default policy is used. The policy can be changed to meet the network's requirements after initial start-up by submitting a new policy with the name default. If the default policy has not been explicitly set, the default is
PERMIT_KEY *
(permit all). -
transactor
: -
The top level role for controlling who can sign transactions and batches on the system. This role is used when the allowed transactors for transactions and batches are the same. Any transactor whose public key is in the policy is allowed to sign transactions and batches, unless a more specific sub-role disallows their public key.
-
transactor.transaction_signer
: -
If a transaction is received that is signed by a transactor who is not permitted by the policy, the batch containing the transaction will be dropped.
-
transactor.transaction_signer.{tp_name}
: -
If a transaction is received for a specific transaction family that is signed by a transactor who is not permitted by the policy, the batch containing the transaction will be dropped. Replace {tp_name} with a transaction family name (see Transaction Family Specifications).
-
transactor.batch_signer
: -
If a batch is received that is signed by a transactor who is not permitted by the policy, that batch will be dropped.
Validator Key Permissioning
Sawtooth allows the network to limit the nodes that are able to connect to it. The permissioning rules determine the roles a connection is able to play on the network. These roles control the types of messages that can be sent and received over a given connection. In this section, the entities acting in the different roles are referred to as "requesters".
Validators are able to determine whether messages delivered to them should be handled or dropped based on a set of role and identities stored within the Identity namespace. Each requester is identified by the public key derived from its identity signing key. Permission verifiers examine incoming messages against the policy and the current configuration and either permit, drop, or respond with an error. In certain cases, the connection will be forcibly closed -- such as if a node is not allowed to connect to the network.
This on-chain approach allows the whole network to change its policies at the same time while the network is live, instead of relying on a startup configuration.
Configuring Authorization
The Identity namespace stores roles as key-value pairs, where the key is a role name and the value is a policy. Sawtooth network permissioning roles use the following pattern:
network[.SUB_ROLE] = POLICY_NAME
where network
is the name of the role to be used for network-wide
validator permissioning. POLICY_NAME refers to the name of a policy that
is set in the Identity namespace. The policy defines the public keys
that are allowed to participate in that role. The policy is made up of
PERMIT_KEY and DENY_KEY rules and is evaluated in order. If the public
key is denied, the connection will be rejected. For more information,
please look at the Identity Transaction Family.
-
As in the previous procedure (see On-chain Transactor Permissioning, make sure that the Identity and Settings transaction processors and the REST API are running.
-
This procedure assumes that you already added your public key to the
sawtooth.identity.allowed_keys
setting. If not, add the your public key now, using thesudo sawset proposal create
command in On-chain Transactor Permissioning. -
Create a new policy for the network role, as described in On-chain Transactor Permissioning. The remaining steps assume that the policy is named
policy_2
. -
Run the following command to set the role for network to permit all:
$ sawtooth identity role create network policy_2
-
To see the role in state, run the following command:
$ sawtooth identity role list network: policy_2
Network Roles
The following is the suggested high-level role for on-chain network permissioning.
-
default
: -
When evaluating role permissions, if the role has not been set, the default policy is used. The policy can be changed to meet the network's requirements after initial start-up by submitting a new policy with the name default. If the default policy has not been explicitly set, the default is
PERMIT_KEY *
(permit all). -
network
: -
If a validator receives a peer request from a node whose validator public key is not permitted by the policy, the message will be dropped, an
AuthorizationViolation
will be returned, and the connection will be closed.This role is checked by the permission verifier when the following messages are received:
GossipMessage
GetPeersRequest
PeerRegisterRequest
PeerUnregisterRequest
GossipBlockRequest
GossipBlockResponse
GossipBatchByBatchIdRequest
GossipBatchByTransactionIdRequest
GossipBatchResponse
GossipPeersRequest
GossipPeersResponse
-
network.consensus
: -
If a validator receives a
GossipMessage
that contains a new block published by a node whose validator public key is not permitted by the policy, the message will be dropped, anAuthorizationViolation
will be returned, and the connection will be closed.