github.com/muhammedhassanm/blockchain@v0.0.0-20200120143007-697261defd4d/sawtooth-core-master/docs/source/architecture/permissioning_requirement.rst (about)

     1  **************************
     2  Permissioning Requirements
     3  **************************
     4  
     5  The following is a detailed list of permissioning requirements, capabilities,
     6  and user stories that aid in the explanation and discussion of the
     7  permissioning design for Hyperledger Sawtooth.
     8  
     9  The following permission groups are presented in this document:
    10  
    11    - Transactor key permissioning, which controls acceptance of transactions and
    12      batches based on signing keys.
    13    - Validator key permissioning, which controls which nodes are allowed to
    14      establish connections to the validator network.
    15  
    16  The permissioning types are further broken down into capability requirements.
    17  Each requirement is made up of a short description, the network scenario the
    18  requirement supports, and associated user stories. User stories are short
    19  statements about a requirement or capability that an actor desires. These short
    20  descriptions illustrate the need for specific permission requirements.
    21  
    22  The design requirements for permissioning include both local validator
    23  configuration and network-wide on-chain permissioning. Local configuration is
    24  needed so that a validator can limit who is allowed to submit batches and
    25  transactions directly to that validator. This is useful, for example, if a
    26  company is running its own validator and wishes to only allow members of that
    27  company to submit transactions. On-chain configuration is required so that the
    28  whole of the network can enforce consistent permissioning rules. For example,
    29  in validator key permissioning, all the validators on the network will reject
    30  the same node from peering, ensuring that only known nodes can join the network.
    31  
    32  Definitions
    33  ===========
    34  
    35  General Definitions
    36  -------------------
    37  The following list contains architecture-level definitions for Sawtooth
    38  concepts. For general definitions, see the :doc:`../glossary`.
    39  
    40  Authorization procedure
    41    “Handshake” that a connection must go through
    42    to be allowed to connect to a validator. If the connection does not follow
    43    the authorization procedure correctly, the connection will be rejected and
    44    closed.
    45  
    46  Batch
    47    Protobuf object containing a list of transactions, a header, and
    48    a signature. The signature is generated by the batch signer by signing the
    49    batch header with the batch signer's private key. For more information on the
    50    structure of a batch, see :doc:`Batch Data Structure
    51    <../architecture/transactions_and_batches>`.
    52  
    53  Client
    54    Program that connects to a validator and is able to query the
    55    state of the blockchain and submit batches.
    56  
    57  Policy
    58    Set of DENY and PERMIT rules that can be used to permission the
    59    access to the validator network and which transactors can participate on the
    60    network.
    61  
    62  Transaction
    63    Protobuf object containing a payload, header, and
    64    signature. The signature is generated by the transaction signer by signing the
    65    transaction header with the transaction signer's private key. For more
    66    information on the structure of a transaction, see :doc:`Transaction Data
    67    Structure <../architecture/transactions_and_batches>`.
    68  
    69  Transaction Family
    70    Set containing a transaction payload format, a model for storing information
    71    in global state, and a procedure for validating a transaction and updating
    72    state based on the transaction payload. For information on specific
    73    transaction families, see :doc:`Transaction Family
    74    Specifications <../transaction_family_specifications>`.
    75  
    76  Actor Definitions
    77  -----------------
    78  The following terms are used for the actors within a Sawtooth network:
    79  
    80  Transactor
    81    Person or program which signs batches or transactions.
    82    When signing a batch, the transactor is also a batch signer. When signing a
    83    transaction, a transactor is also a transaction signer.
    84  
    85  Batch signer
    86    Transactor that signs a batch header using the batch
    87    signer's private key. The resulting signature is included as part of the
    88    batch. The batch signer's public key is also stored in the batch header.
    89  
    90  Transaction Signer
    91    Transactor that signs a transaction header using
    92    the transaction signer's private key. The resulting signature is included as
    93    part of the transaction. The transaction signer's public key is also
    94    stored in the transaction header.
    95  
    96  Network Operator
    97    One or more people who collectively manage the Sawtooth
    98    network. The network operator determines and coordinates the overall network
    99    characteristics, such as determining which transaction processors are being
   100    run, setting the consensus mechanism, modifying on-chain settings, and
   101    modifying on-chain roles.
   102  
   103  Sysadmin
   104    System administrator; a person who installs and configures the validator
   105    software and configures the validator software using config files. The
   106    role of sysadmin does not include activities that modify on-chain settings.
   107  
   108  Validator Network Scenarios
   109  ===========================
   110  
   111  The following example network scenarios are used to illustrate when each
   112  capability requirement would be useful.
   113  
   114  Public Network
   115  --------------
   116  
   117  In a public network, all connections will be allowed and all transactors are
   118  allowed to sign batches and transactions.
   119  
   120  In order for a public Sawtooth network to function correctly, an incentive
   121  system would also need to be designed and implemented. Such a system is beyond
   122  the scope of this design and so it is omitted.
   123  
   124  Consortium Network
   125  ------------------
   126  
   127  In a consortium network, only specific validators will be allowed to join the
   128  validator network and participate in consensus. The network will still allow
   129  any client, transaction processor, or state delta subscriber to connect to a
   130  validator and accept batches and transactions signed by all transactors.
   131  
   132  Private Network
   133  ---------------
   134  
   135  In a private network, only specific validators will be allowed to join the
   136  validator network and participate in consensus. The validators in the network
   137  will only accept connections from specific clients and will control if the
   138  client is allowed to submit batches and query specific address prefixes in
   139  state. Only specific transaction processors and state delta subscribers will be
   140  allowed to connect to the local validator. Batches and transactions received by
   141  the validator can only be signed by permitted transactors. Transactors may also
   142  be restricted to only sending transactions for certain transaction families.
   143  
   144  +--------------------+--------------------------------------------------------+
   145  | Network Scenario   | Capabilities                                           |
   146  +--------------------+--------------------------------------------------------+
   147  | Public Network     | - Allow all batch signers to submit batches            |
   148  |                    | - Allow all transaction signers to submit transactions |
   149  |                    | - Allow all nodes to join the validator network        |
   150  +--------------------+--------------------------------------------------------+
   151  | Consortium Network | - Allow all batch signers to submit batches            |
   152  |                    | - Allow all transaction signers to submit transactions |
   153  |                    | - Allow only specific nodes to join the validator      |
   154  |                    |   network                                              |
   155  |                    | - Allow only specific nodes to participate in consensus|
   156  |                    | - Support policy-based transactor permissioning        |
   157  +--------------------+--------------------------------------------------------+
   158  | Private Network    | - Allow only specific batch signers to submit batches  |
   159  |                    | - Allow only specific transaction signers to submit    |
   160  |                    |   transactions                                         |
   161  |                    | - Allow only specific nodes to join the validator      |
   162  |                    |   network                                              |
   163  |                    | - Allow only specific nodes to participate in consensus|
   164  |                    | - Restrict the type of transactions transactors can    |
   165  |                    |   sign                                                 |
   166  |                    | - Restrict address space access to a limited set of    |
   167  |                    |   transactors                                          |
   168  |                    | - Support policy-based transactor permissioning        |
   169  +--------------------+--------------------------------------------------------+
   170  
   171  Transactor Key Permissioning
   172  ============================
   173  
   174  The following stories are related to permissioning performed on the basis of a
   175  transactor's public signing key. This includes both batch signers and
   176  transaction signers. The validator will check local configuration and network
   177  configuration when receiving a batch from a client and only batch signers
   178  permitted in the intersection of the two configurations will be allowed. When
   179  the validator receives a batch from a peer, only the network configuration will
   180  be checked. This is required to prevent network forks.
   181  
   182  
   183  Allow all batch signers to submit batches
   184  
   185  +--------------------+--------------------------------------------------------+
   186  | Network Scenario   | - Public - YES                                         |
   187  |                    | - Consortium - YES                                     |
   188  |                    | - Private - NO                                         |
   189  +--------------------+--------------------------------------------------------+
   190  | Description        | The validator must be able to be configured to allow   |
   191  |                    | all batches to be submitted, regardless of who the     |
   192  |                    | batch signer is. In other words, if a client is        |
   193  |                    | connected to the validator and that client is allowed  |
   194  |                    | to submit batches, the batches will not be rejected due|
   195  |                    | to the public key that was used to sign the batch.     |
   196  |                    | These batches will still be rejected if they fail      |
   197  |                    | signature verification.                                |
   198  +--------------------+--------------------------------------------------------+
   199  | User Stories       | - A sysadmin must be able to configure a local         |
   200  |                    |   validator to accept batches signed by any batch      |
   201  |                    |   signer.                                              |
   202  |                    | - A network operator must be able to configure the     |
   203  |                    |   validator network to accept batches signed by any    |
   204  |                    |   batch signer.                                        |
   205  +--------------------+--------------------------------------------------------+
   206  
   207  Allow only specific batch signers to submit batches
   208  
   209  +--------------------+--------------------------------------------------------+
   210  | Network Scenario   | - Public - NO                                          |
   211  |                    | - Consortium - NO                                      |
   212  |                    | - Private - YES                                        |
   213  +--------------------+--------------------------------------------------------+
   214  | Description        | The validator must be able to be configured to only    |
   215  |                    | allow certain batch signers to submit batches. If the  |
   216  |                    | validator receives a batch that was signed by a batch  |
   217  |                    | signer whose public key is not allowed, that batch     |
   218  |                    | should be dropped. Batches should also be checked      |
   219  |                    | before block validation. If the validator network      |
   220  |                    | permits a given batch signer, the validator must accept|
   221  |                    | batches signed by that batch signer from peers,        |
   222  |                    | regardless of its local configuration.                 |
   223  +--------------------+--------------------------------------------------------+
   224  | User Stories       | - A sysadmin must be able to configure a local         |
   225  |                    |   validator to accept batches signed only by predefined|
   226  |                    |   batch signers.                                       |
   227  |                    | - A network operator must be able to configure the     |
   228  |                    |   whole validator network to only accept batches from  |
   229  |                    |   specific batch signers.                              |
   230  +--------------------+--------------------------------------------------------+
   231  
   232  Allow all transaction signers to submit transactions
   233  
   234  +--------------------+--------------------------------------------------------+
   235  | Network Scenario   | - Public - YES                                         |
   236  |                    | - Consortium - YES                                     |
   237  |                    | - Private - NO                                         |
   238  +--------------------+--------------------------------------------------------+
   239  | Description        | The validator must be able to be configured to allow   |
   240  |                    | all transactions to be submitted, regardless of who the|
   241  |                    | transaction signer is. In other words, if a client is  |
   242  |                    | connected to the validator and the client is allowed to|
   243  |                    | submit transactions, the transactions will not be      |
   244  |                    | rejected due to the public key that was used to sign   |
   245  |                    | the transactions. These transactions will still be     |
   246  |                    | rejected if they fail signature verification.          |
   247  +--------------------+--------------------------------------------------------+
   248  | User Stories       | - A sysadmin must be able to configure a local         |
   249  |                    |   validator to accept transactions signed by any       |
   250  |                    |   transaction signer.                                  |
   251  |                    | - A network operator must be able to configure the     |
   252  |                    |   whole validator network to accept transactions signed|
   253  |                    |   by any batch signer.                                 |
   254  +--------------------+--------------------------------------------------------+
   255  
   256  Allow only specific transaction signers to submit transactions
   257  
   258  +--------------------+--------------------------------------------------------+
   259  | Network Scenario   | - Public - NO                                          |
   260  |                    | - Consortium - NO                                      |
   261  |                    | - Private - YES                                        |
   262  +--------------------+--------------------------------------------------------+
   263  | Description        | The validator must be able to be configured to only    |
   264  |                    | allow certain transaction signers to submit            |
   265  |                    | transactions. In other words, if the validator receives|
   266  |                    | a transaction that was signed by a transaction signer  |
   267  |                    | whose public key is not allowed, that transaction      |
   268  |                    | should be dropped. Transactions should also be checked |
   269  |                    | during block validation. If the validator network      |
   270  |                    | permits a given transaction signer, the validator must |
   271  |                    | accept transaction signed by that transaction signer   |
   272  |                    | from peers, regardless of its local configuration.     |
   273  +--------------------+--------------------------------------------------------+
   274  | User Stories       | - A sysadmin must be able to configure a local         |
   275  |                    |   validator to accept transactions signed only by      |
   276  |                    |   predefined transaction signers.                      |
   277  |                    | - A network operator must be able to configure the     |
   278  |                    |   whole validator network to accept batches only from  |
   279  |                    |   specific transaction signers.                        |
   280  +--------------------+--------------------------------------------------------+
   281  
   282  Restrict the type of transactions transactors can sign
   283  
   284  +--------------------+--------------------------------------------------------+
   285  | Network Scenario   | - Public - NO                                          |
   286  |                    | - Consortium - NO                                      |
   287  |                    | - Private - YES                                        |
   288  +--------------------+--------------------------------------------------------+
   289  | Description        | The validator must be able to restrict the transaction |
   290  |                    | signers that are allowed to sign transactions for a    |
   291  |                    | specific transaction family. This permissioning would  |
   292  |                    | be separate from any public key permissioning enforced |
   293  |                    | by the transaction family logic.                       |
   294  +--------------------+--------------------------------------------------------+
   295  | User Stories       | - A network operator must be able to configure the     |
   296  |                    |   whole validator network to only accept transactions  |
   297  |                    |   that were signed by allowed transaction signers for a|
   298  |                    |   specific transaction family.                         |
   299  +--------------------+--------------------------------------------------------+
   300  
   301  Support policy-based transactor permissioning
   302  
   303  +--------------------+--------------------------------------------------------+
   304  | Network Scenario   | - Public - NO                                          |
   305  |                    | - Consortium - YES                                     |
   306  |                    | - Private - YES                                        |
   307  +--------------------+--------------------------------------------------------+
   308  | Description        | The validator must be able to enforce transactor       |
   309  |                    | permissions based on defined policies.                 |
   310  +--------------------+--------------------------------------------------------+
   311  | User Stories       | - A sysadmin must be able to configure a local         |
   312  |                    |   validator to only accept transactions and batches    |
   313  |                    |   that are signed by transactors that are allowed by   |
   314  |                    |   predefined locally stored policies.                  |
   315  |                    | - A network operator must be able to configure the     |
   316  |                    |   whole validator network to only accept transactions  |
   317  |                    |   and batches that are signed by transactor that are   |
   318  |                    |   allowed by defined policies.                         |
   319  +--------------------+--------------------------------------------------------+
   320  
   321  Validator Key Permissioning
   322  ===========================
   323  The following stories are related to permissioning performed on the basis of a
   324  node’s public signing key.
   325  
   326  Allow all nodes to join the validator network
   327  
   328  +--------------------+--------------------------------------------------------+
   329  | Network Scenario   | - Public - YES                                         |
   330  |                    | - Consortium - NO                                      |
   331  |                    | - Private - NO                                         |
   332  +--------------------+--------------------------------------------------------+
   333  | Description        | The validator network must be able to be configured to |
   334  |                    | allow all validator nodes to join the network. This    |
   335  |                    | means that every validator on the network should accept|
   336  |                    | the node as a peer regardless of what its public key   |
   337  |                    | is. The validator nodes will also be able to           |
   338  |                    | participate in consensus and communicate over the      |
   339  |                    | gossip protocol. The node will still need to go through|
   340  |                    | the authorization procedure defined by the validator   |
   341  |                    | the node is trying to connect to. If, for any reason,  |
   342  |                    | the node fails the authorization procedure, it will be |
   343  |                    | rejected.                                              |
   344  +--------------------+--------------------------------------------------------+
   345  | User Stories       | - A network operator must be able to configure the     |
   346  |                    |   validator network to accept all nodes that wish to   |
   347  |                    |   connect, regardless of the node’s public key.        |
   348  +--------------------+--------------------------------------------------------+
   349  
   350  Allow only specific nodes to join the validator network
   351  
   352  +--------------------+--------------------------------------------------------+
   353  | Network Scenario   | - Public - NO                                          |
   354  |                    | - Consortium - YES                                     |
   355  |                    | - Private - YES                                        |
   356  +--------------------+--------------------------------------------------------+
   357  | Description        | The validator network must be able to be configured to |
   358  |                    | only allow nodes to join the network if the node's     |
   359  |                    | public key is permitted. In other words, if a validator|
   360  |                    | receives a connection request from a node, and the     |
   361  |                    | validator does not recognize the node’s public key, the|
   362  |                    | connection should be rejected.                         |
   363  +--------------------+--------------------------------------------------------+
   364  | User Stories       | - A network operator must be able to configure the     |
   365  |                    |   validator network to only accept connections from    |
   366  |                    |   nodes with specific public keys.                     |
   367  +--------------------+--------------------------------------------------------+
   368  
   369  Allow only specific nodes to participate in consensus
   370  
   371  +--------------------+--------------------------------------------------------+
   372  | Network Scenario   | - Public - NO                                          |
   373  |                    | - Consortium - YES                                     |
   374  |                    | - Private - YES                                        |
   375  +--------------------+--------------------------------------------------------+
   376  | Description        | The validator network must be able to be configured to |
   377  |                    | only allow specific nodes to participate in consensus. |
   378  |                    | This is separate from any restrictions enforced by the |
   379  |                    | consensus algorithm. The nodes that are not allowed to |
   380  |                    | participate in consensus can still validate blocks but |
   381  |                    | are not allowed to publish blocks.                     |
   382  +--------------------+--------------------------------------------------------+
   383  | User Stories       | - A network operator must be able to configure the     |
   384  |                    |   validator network to only allow certain nodes to     |
   385  |                    |   participate in consensus.                            |
   386  +--------------------+--------------------------------------------------------+
   387  
   388  .. Licensed under Creative Commons Attribution 4.0 International License
   389  .. https://creativecommons.org/licenses/by/4.0/