Permissioning Design

Sawtooth includes the ability to control validator and transactor permissions. This chapter describes permissioning in Hyperledger Sawtooth by providing a detailed list of the requirements, capabilities, and user stories that help to understand permissioning design.

Sawtooth divides permissioning into two general groups:

  • Transactor key permissioning controls who can submit transactions and batches, based on signing keys.
  • Validator key permissioning controls which nodes are allowed to establish connections to the Sawtooth network.

This chapter summarizes the types of Sawtooth networks, then lists the capability requirements for these permissioning groups. Each requirement has 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 of Sawtooth permissioning includes both local validator configuration and network-wide on-chain permissioning.

  • Local configuration allows a validator to 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 Sawtooth node and wishes to allow only members of that company to submit transactions.
  • On-chain configuration allows a Sawtooth network to 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 list contains architecture-level definitions for Sawtooth concepts. For general definitions, see the glossary

Authorization procedure

“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.

Batch

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

Client

Program that connects to a validator and is able to query the state of the blockchain and submit batches.

Policy

Set of DENY and PERMIT rules that can be used to permission the access to the Sawtooth network and which transactors can participate on the network.

Transaction

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.

Transaction Family

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.

Actor Definitions

The following terms are used for the actors within a Sawtooth network:

Transactor

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

Transactor that 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

Transactor that 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

One or more people who collectively manage the Sawtooth network. The network operator determines and coordinates the overall network characteristics, such as determining which transaction processors are being run, setting the consensus mechanism, modifying on-chain settings, and modifying on-chain roles.

Sysadmin

System administrator; a person who installs and configures a Sawtooth node using config files. The role of sysadmin does not include activities that modify on-chain settings.

Sawtooth Network Scenarios

Sawtooth is designed to support public, consortium, and private networks. The following network scenarios are used in the discussion of capability requirements to illustrate when each requirement would be useful.

  • Public network: In a public network, all connections are allowed and all transactors are allowed to sign batches and transactions.
  • Consortium network: In a consortium network, only specific nodes are allowed to join the Sawtooth network and participate in consensus. However, the network allows any client, transaction processor, or event subscriber to connect to a validator and accept batches and transactions signed by all transactors.
  • Private Network: In a private network, only specific nodes are allowed to join the Sawtooth network and participate in consensus. The validators in the network accept only connections from specific clients. The validators also control whether the client is allowed to submit batches and query specific address prefixes in state. Only specific transaction processors and event subscribers are allowed to connect to the local validator. Batches and transactions that are received by the validator can only be signed by permitted transactors. Transactors can also be restricted to only sending transactions for certain transaction families.

The following table summaries the capability requirements for each network scenario.

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 Sawtooth network
Consortium Network - Allow all batch signers to submit batches
  - Allow all transaction signers to submit transactions
  - Allow only specific nodes to join the Sawtooth 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 Sawtooth 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

Transactor key permissioning is performed on the basis of a transactor’s public signing key. This includes both batch signers and transaction signers.

When the validator receives a batch from a client, it checks both the local configuration and network configuration. Only the batch signers that are permitted in the intersection of the two configurations will be allowed.

When the validator receives a batch from a peer validator, only the network configuration is checked. This behavior is required to prevent network forks.

The following tables describe the design of each capability for transactor key permissioning.

Allow all batch signers to submit batches  
Network Scenario - Public - YES
  - Consortium - YES
  - Private - NO
Description The validator can 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 ejected if
  they fail signature verification.
User Stories - A sysadmin can configure a local validator to
  accept batches signed by any batch signer.
  - A network operator can configure the Sawtooth 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 can 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 is dropped. Batches are also checked
  before block validation. If the Sawtooth network
  permits a given batch signer, the validator
  accepts batches signed by that batch signer from
  peers, regardless of its local configuration.
User Stories - A sysadmin can configure a local validator to
  accept batches signed only by predefined
  batch signers.
  - A network operator can configure the whole
  Sawtooth 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 can 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 can configure a local validator to
  accept transactions signed by any transaction
  signer.
  - A network operator can configure the whole
  Sawtooth 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 can 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 Sawtooth network permits a
  given transaction signer, the validator will
  accept transactions signed by that transaction
  signer from peers, regardless of its local
  configuration.
User Stories - A sysadmin can configure a local validator to
  accept transactions signed only by predefined
  transaction signers.
  - A network operator can configure the whole
  Sawtooth 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 can restrict the transaction
  signers that are allowed to sign transactions for
  a specific transaction family. This permissioning
  is separate from any public key permissioning
  enforced by the transaction family logic.
User Stories - A network operator can configure the whole
  Sawtooth 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 can enforce transactor permissions
  based on defined policies.
User Stories - A sysadmin can configure a local validator to
  accept only transactions and batches that are
  signed by transactors that are allowed by
  predefined locally stored policies.
  - A network operator can configure the whole
  Sawtooth network to accept only transactions
  and batches that are signed by transactor
  that are allowed by defined policies.

Validator Key Permissioning

Validator key permissioning is performed on the basis of a validator’s public signing key.

The following tables describe the design of each capability for validator key permissioning.

Allow all nodes to join the Sawtooth network  
Network Scenario - Public - YES
  - Consortium - NO
  - Private - NO
Description The Sawtooth network can be configured to allow
  all nodes to join the network. This means that
  every validator on the network should accept the
  node as a peer, regardless of its public key. The
  nodes are also able to participate in consensus
  and communicate over the gossip protocol. The
  node must still 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 can configure the Sawtooth
  network to accept all nodes that wish to
  connect, regardless of the node’s public key.
Allow only specific nodes to join the Sawtooth network  
Network Scenario - Public - NO
  - Consortium - YES
  - Private - YES
Description The Sawtooth network can 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 is rejected.
User Stories - A network operator can configure the Sawtooth
  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 Sawtooth network can 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 can configure the Sawtooth
  network to only allow certain nodes to
  participate in consensus.