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/