Permissioning Requirements

The following is a detailed list of permissioning requirements, capabilities, and user stories that aid in the explanation and discussion of the permissioning design for Hyperledger Sawtooth.

The following permission groups are presented in this document:

  • Transactor key permissioning, which controls acceptance of transactions and batches based on signing keys.
  • Validator key permissioning, which controls which nodes are allowed to establish connections to the validator network.

The permissioning types are further broken down into capability requirements. Each requirement is made up of a short description, the network scenario the requirement supports, and associated user stories. User stories are short statements about a requirement or capability that an actor desires. These short descriptions illustrate the need for specific permission requirements.

The design requirements for permissioning include both local validator configuration and network-wide on-chain permissioning. Local configuration is needed so that a validator can limit who is allowed to submit batches and transactions directly to that validator. This is useful, for example, if a company is running its own validator and wishes to only allow members of that company to submit transactions. On-chain configuration is required so that the whole of the network can enforce consistent permissioning rules. For example, in validator key permissioning, all the validators on the network will reject the same node from peering, ensuring that only known nodes can join the network.

Definitions

General Definitions

The following define general components and concepts related to Sawtooth:

Batch
A batch is a protobuf object containing a list of transactions, a header, and a signature. The signature is generated by the batch signer by signing the batch header with the batch signer’s private key. For more information on the structure of a batch, see Batch Data Structure.
Transaction
A transaction is a protobuf object containing a payload, header, and signature. The signature is generated by the transaction signer by signing the transaction header with the transaction signer’s private key. For more information on the structure of a transaction, see Transaction Data Structure.
Consensus
Consensus is the process of building agreement among a group of mutually distrusting participants. In this case, the mutually distrusting participants are the other nodes on the validator network.
Transaction Family
A transaction family is a set containing: a transaction payload format, a model for storing information in global state, and a procedure for validating a transaction and updating state based on the transaction payload. For information on specific transaction families, see Transaction Family Specifications.
Transaction Processor
A transaction processor validates transactions and updates state based on the rules defined by a given transaction family.
Validator
A validator is the component ultimately responsible for validating batches of transactions, combining them into blocks, maintaining consensus with the network, and coordinating communication between clients, other validators, and transaction processors. Much of the actual validation is delegated to other components, such as transaction processors and the active consensus module.
Node
A node is a validator that is trying to connect to the network.
Client
A client is a program that connects to a validator and is able to query the state of the blockchain and submit batches.
State Delta Subscriber
A state delta subscriber is a client framework that subscribes to a validator for state deltas on a specific subset of namespaces, for the purpose of off-chain storage or action.
Radix Merkle Tree
A Radix Merkle tree is the representation of state used by Sawtooth. The tree is a Merkle tree because it is a copy-on-write data structure which stores successive node hashes from leaf-to-root upon any changes to the tree. The tree is also an addressable Radix tree because addresses uniquely identify the paths to leaf nodes in the tree where information is stored.
Validator Network
A validator network is peer to peer network of validators that are working on the same block chain.
Authorization Procedure
An authorization procedure is a “handshake” that a connection must go through to be allowed to connect to a validator. If the connection does not follow the authorization procedure correctly, the connection will be rejected and closed.
Policy
A policy is a set of DENY and PERMIT rules that can be used to permission the access to the validator network and which transactors can participate on the network.

Actor Definitions

The following define the actors within a Sawtooth network:

Transactor
A transactor is the person or program which signs batches or transactions. When signing a batch, the transactor is also a batch signer. When signing a transaction, a transactor is also a transaction signer.
Batch Signer
A batch signer is a transactor which signs a batch header using the batch signer’s private key. The resulting signature is included as part of the batch. The batch signer’s public key is also stored in the batch header.
Transaction Signer
A transaction signer is a transactor which signs a transaction header using the transaction signer’s private key. The resulting signature is included as part of the transaction. The transaction signer’s public key is also stored in the transaction header.
Network Operator
A network operator is one or more people who collectively manage the sawtooth network. The network operator determines and coordinates the overall network characteristics such as which transaction processors are being run, the consensus mechanism, modifying on-chain settings, modifying on-chain roles etc.
Sysadmin
A sysadmin is a person who installs and configures the validator software and configures the validator software using config files. The role of sysadmin does not include activities which modify on-chain settings.

Validator Network Scenarios

The following example network scenarios are used to illustrate when each capability requirement would be useful.

Public Network

In a public network, all connections will be allowed and all transactors are allowed to sign batches and transactions.

In order for a public Sawtooth network to function correctly, an incentive system would also need to be designed and implemented. Such a system is beyond the scope of this design and so it is omitted.

Consortium Network

In a consortium network, only specific validators will be allowed to join the validator network and participate in consensus. The network will still allow any client, transaction processor, or state delta subscriber to connect to a validator and accept batches and transactions signed by all transactors.

Private Network

In a private network, only specific validators will be allowed to join the validator network and participate in consensus. The validators in the network will only accept connections from specific clients and will control if the client is allowed to submit batches and query specific address prefixes in state. Only specific transaction processors and state delta subscribers will be allowed to connect to the local validator. Batches and transactions received by the validator can only be signed by permitted transactors. Transactors may also be restricted to only sending transactions for certain transaction families.

Network Scenario Capabilities
Public Network
  • Allow all batch signers to submit batches
  • Allow all transaction signers to submit transactions
  • Allow all nodes to join the validator network
Consortium Network
  • Allow all batch signers to submit batches
  • Allow all transaction signers to submit transactions
  • Allow only specific nodes to join the validator network
  • Allow only specific nodes to participate in consensus
  • Support policy-based transactor permissioning
Private Network
  • Allow only specific batch signers to submit batches
  • Allow only specific transaction signers to submit transactions
  • Allow only specific nodes to join the validator network
  • Allow only specific nodes to participate in consensus
  • Restrict the type of transactions transactors can sign
  • Restrict address space access to a limited set of transactors
  • Support policy-based transactor permissioning

Transactor Key Permissioning

The following stories are related to permissioning performed on the basis of a transactor’s public signing key. This includes both batch signers and transaction signers. The validator will check local configuration and network configuration when receiving a batch from a client and only batch signers permitted in the intersection of the two configurations will be allowed. When the validator receives a batch from a peer, only the network configuration will be checked. This is required to prevent network forks.

Allow all batch signers to submit batches

Network Scenario
  • Public - YES
  • Consortium - YES
  • Private - NO
Description The validator must be able to be configured to allow all batches to be submitted, regardless of who the batch signer is. In other words, if a client is connected to the validator and that client is allowed to submit batches, the batches will not be rejected due to the public key that was used to sign the batch. These batches will still be rejected if they fail signature verification.
User Stories
  • A sysadmin must be able to configure a local validator to accept batches signed by any batch signer.
  • A network operator must be able to configure the validator network to accept batches signed by any batch signer.

Allow only specific batch signers to submit batches

Network Scenario
  • Public - NO
  • Consortium - NO
  • Private - YES
Description The validator must be able to be configured to only allow certain batch signers to submit batches. If the validator receives a batch that was signed by a batch signer whose public key is not allowed, that batch should be dropped. Batches should also be checked before block validation. If the validator network permits a given batch signer, the validator must accept batches signed by that batch signer from peers, regardless of its local configuration.
User Stories
  • A sysadmin must be able to configure a local validator to accept batches signed only by predefined batch signers.
  • A network operator must be able to configure the whole validator network to only accept batches from specific batch signers.

Allow all transaction signers to submit transactions

Network Scenario
  • Public - YES
  • Consortium - YES
  • Private - NO
Description The validator must be able to be configured to allow all transactions to be submitted, regardless of who the transaction signer is. In other words, if a client is connected to the validator and the client is allowed to submit transactions, the transactions will not be rejected due to the public key that was used to sign the transactions. These transactions will still be rejected if they fail signature verification.
User Stories
  • A sysadmin must be able to configure a local validator to accept transactions signed by any transaction signer.
  • A network operator must be able to configure the whole validator network to accept transactions signed by any batch signer.

Allow only specific transaction signers to submit transactions

Network Scenario
  • Public - NO
  • Consortium - NO
  • Private - YES
Description The validator must be able to be configured to only allow certain transaction signers to submit transactions. In other words, if the validator receives a transaction that was signed by a transaction signer whose public key is not allowed, that transaction should be dropped. Transactions should also be checked during block validation. If the validator network permits a given transaction signer, the validator must accept transaction signed by that transaction signer from peers, regardless of its local configuration.
User Stories
  • A sysadmin must be able to configure a local validator to accept transactions signed only by predefined transaction signers.
  • A network operator must be able to configure the whole validator network to accept batches only from specific transaction signers.

Restrict the type of transactions transactors can sign

Network Scenario
  • Public - NO
  • Consortium - NO
  • Private - YES
Description The validator must be able to restrict the transaction signers that are allowed to sign transactions for a specific transaction family. This permissioning would be separate from any public key permissioning enforced by the transaction family logic.
User Stories
  • A network operator must be able to configure the whole validator network to only accept transactions that were signed by allowed transaction signers for a specific transaction family.

Support policy-based transactor permissioning

Network Scenario
  • Public - NO
  • Consortium - YES
  • Private - YES
Description The validator must be able to enforce transactor permissions based on defined policies.
User Stories
  • A sysadmin must be able to configure a local validator to only accept transactions and batches that are signed by transactors that are allowed by predefined locally stored policies.
  • A network operator must be able to configure the whole validator network to only accept transactions and batches that are signed by transactor that are allowed by defined policies.

Validator Key Permissioning

The following stories are related to permissioning performed on the basis of a node’s public signing key.

Allow all nodes to join the validator network

Network Scenario
  • Public - YES
  • Consortium - NO
  • Private - NO
Description The validator network must be able to be configured to allow all validator nodes to join the network. This means that every validator on the network should accept the node as a peer regardless of what its public key is. The validator nodes will also be able to participate in consensus and communicate over the gossip protocol. The node will still need to go through the authorization procedure defined by the validator the node is trying to connect to. If, for any reason, the node fails the authorization procedure, it will be rejected.
User Stories
  • A network operator must be able to configure the validator network to accept all nodes that wish to connect, regardless of the node’s public key.

Allow only specific nodes to join the validator network

Network Scenario
  • Public - NO
  • Consortium - YES
  • Private - YES
Description The validator network must be able to be configured to only allow nodes to join the network if the node’s public key is permitted. In other words, if a validator receives a connection request from a node, and the validator does not recognize the node’s public key, the connection should be rejected.
User Stories
  • A network operator must be able to configure the validator network to only accept connections from nodes with specific public keys.

Allow only specific nodes to participate in consensus

Network Scenario
  • Public - NO
  • Consortium - YES
  • Private - YES
Description The validator network must be able to be configured to only allow specific nodes to participate in consensus. This is separate from any restrictions enforced by the consensus algorithm. The nodes that are not allowed to participate in consensus can still validate blocks but are not allowed to publish blocks.
User Stories
  • A network operator must be able to configure the validator network to only allow certain nodes to participate in consensus.