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 validator network.

This chapter summarizes the types of validator 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 validator 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 validator 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 Structure.

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 the validator software and configures the validator software using config files. The role of sysadmin does not include activities that modify on-chain settings.

Validator 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 validators are allowed to join the validator 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 validators are allowed to join the validator 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 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

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 rejected 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 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 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 validator 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 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 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 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 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 validator 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 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 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 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 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 validator 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 node’s public signing key.

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

Allow all nodes to join the validator network

Network Scenario

  • Public - YES

  • Consortium - NO

  • Private - NO

Description

The validator network can 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 its public key. The validator 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 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 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 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 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 validator network to only allow certain nodes to participate in consensus.