poanetwork
/
quorum
mirror of https://github.com/poanetwork/quorum.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

permission: documentation update

This commit is contained in:
vsmk98 2019-05-16 10:31:36 +08:00
parent bd7a99af03 5d08369722
commit 1bc8c82cd6
1 changed files with 24 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
docs/Permissioning/Usage.md
View File

@ -1,4 +1,5 @@
This section describes the usage of the permission model for creation of a network, initial set up, and management of a network. The network management activities can be broadly categorized into:
**This section describes the usage of permission model for creation of a network, initial set up and management of network. The network management activities can be broadly categorized into:**
* [Initial network set up](#initial-network-set-up) * [Initial network set up](#initial-network-set-up)
* [Proposing a new organization into the network](#proposing-a-new-organization-into-the-network) * [Proposing a new organization into the network](#proposing-a-new-organization-into-the-network)
@ -41,7 +42,7 @@ Assuming that the network was started with the `permission-config.json` given in
] ]
``` ```
then the network will have the following configuration once it has started up: then the network will have the following configuration once it has started up:
```javascript ```
> quorumPermission.orgList > quorumPermission.orgList
[{ [{
fullOrgId: "ADMINORG", fullOrgId: "ADMINORG",
@ -102,7 +103,7 @@ Once the network is up, the network admin accounts can then propose a new organi
#### example #### example
An example to propose and approve an organization by name `ORG1` is as shown below: An example to propose and approve an organization by name `ORG1` is as shown below:
```javascript ```
> quorumPermission.addOrg("ORG1", "enode://de9c2d5937e599930832cecc1df8cc90b50839bdf635c1a4e68e1dab2d001cd4a11c626e155078cc65958a72e2d72c1342a28909775edd99cc39470172cce0ac@127.0.0.1:21004?discport=0", "0x0638e1574728b6d862dd5d3a3e0942c3be47d996", {from: "0xed9d02e382b34818e88b88a309c7fe71e65f419d"}) > quorumPermission.addOrg("ORG1", "enode://de9c2d5937e599930832cecc1df8cc90b50839bdf635c1a4e68e1dab2d001cd4a11c626e155078cc65958a72e2d72c1342a28909775edd99cc39470172cce0ac@127.0.0.1:21004?discport=0", "0x0638e1574728b6d862dd5d3a3e0942c3be47d996", {from: "0xed9d02e382b34818e88b88a309c7fe71e65f419d"})
{ {
msg: "Action completed successfully", msg: "Action completed successfully",
@ -110,7 +111,7 @@ An example to propose and approve an organization by name `ORG1` is as shown bel
} }
``` ```
Once the org is proposed, it will be in `Proposed` state awaiting approval from other network admin accounts. The org status is as shown below: Once the org is proposed, it will be in `Proposed` state awaiting approval from other network admin accounts. The org status is as shown below:
```javascript ```
> quorumPermission.orgList[1] > quorumPermission.orgList[1]
{ {
fullOrgId: "ORG1", fullOrgId: "ORG1",
@ -123,7 +124,7 @@ Once the org is proposed, it will be in `Proposed` state awaiting approval from
} }
``` ```
The network admin accounts can then approve the proposed organizations and once the majority approval is achieved, the organization status is updated as `Approved` The network admin accounts can then approve the proposed organizations and once the majority approval is achieved, the organization status is updated as `Approved`
```javascript ```
> quorumPermission.approveOrg("ORG1", "enode://de9c2d5937e599930832cecc1df8cc90b50839bdf635c1a4e68e1dab2d001cd4a11c626e155078cc65958a72e2d72c1342a28909775edd99cc39470172cce0ac@127.0.0.1:21004?discport=0", "0x0638e1574728b6d862dd5d3a3e0942c3be47d996", {from: "0xca843569e3427144cead5e4d5999a3d0ccf92b8e"}) > quorumPermission.approveOrg("ORG1", "enode://de9c2d5937e599930832cecc1df8cc90b50839bdf635c1a4e68e1dab2d001cd4a11c626e155078cc65958a72e2d72c1342a28909775edd99cc39470172cce0ac@127.0.0.1:21004?discport=0", "0x0638e1574728b6d862dd5d3a3e0942c3be47d996", {from: "0xca843569e3427144cead5e4d5999a3d0ccf92b8e"})
{ {
msg: "Action completed successfully", msg: "Action completed successfully",
@ -141,7 +142,7 @@ The network admin accounts can then approve the proposed organizations and once
} }
``` ```
The details of the new organization approved are as below: The details of the new organization approved are as below:
```javascript ```
> quorumPermission.getOrgDetails("ORG1") > quorumPermission.getOrgDetails("ORG1")
{ {
acctList: [{ acctList: [{
@ -183,7 +184,7 @@ The new node belonging to the organization can now join the network. In case the
Once the organization is approved and the node of the organization has joined the network, the organization admin can then create sub organizations, roles, add additional nodes at organization level, add accounts to the organization and change roles of existing organization level accounts. Once the organization is approved and the node of the organization has joined the network, the organization admin can then create sub organizations, roles, add additional nodes at organization level, add accounts to the organization and change roles of existing organization level accounts.
To add a sub org at `ORG1` level refer to [addSubOrg API](../Permissioning%20apis#quorumpermissionaddsuborg) To add a sub org at `ORG1` level refer to [addSubOrg API](../Permissioning%20apis#quorumpermissionaddsuborg)
```javascript ```
> quorumPermission.addSubOrg("ORG1", "SUB1", "enode://239c1f044a2b03b6c4713109af036b775c5418fe4ca63b04b1ce00124af00ddab7cc088fc46020cdc783b6207efe624551be4c06a994993d8d70f684688fb7cf@127.0.0.1:21006?discport=0", {from: eth.accounts[0]}) > quorumPermission.addSubOrg("ORG1", "SUB1", "enode://239c1f044a2b03b6c4713109af036b775c5418fe4ca63b04b1ce00124af00ddab7cc088fc46020cdc783b6207efe624551be4c06a994993d8d70f684688fb7cf@127.0.0.1:21006?discport=0", {from: eth.accounts[0]})
{ {
msg: "Action completed successfully", msg: "Action completed successfully",
@ -201,7 +202,7 @@ To add a sub org at `ORG1` level refer to [addSubOrg API](../Permissioning%20api
} }
``` ```
For adding a sub org the enode id is not mandatory. For the newly created sub org if the org admin desires to add an administration account, the org admin account will have to first create a role with `isAdmin` flag as `Y` and then assign this role to the account which belongs to the sub org. Once assigned the account will act as org admin at sub org level. Refer to [addNewRole API](../Permissioning%20apis#quorumpermissionaddnewrole) For adding a sub org the enode id is not mandatory. For the newly created sub org if the org admin desires to add an administration account, the org admin account will have to first create a role with `isAdmin` flag as `Y` and then assign this role to the account which belongs to the sub org. Once assigned the account will act as org admin at sub org level. Refer to [addNewRole API](../Permissioning%20apis#quorumpermissionaddnewrole)
```javascript ```
> quorumPermission.addNewRole("ORG1.SUB1", "SUBADMIN", 3, false, true,{from: eth.accounts[0]}) > quorumPermission.addNewRole("ORG1.SUB1", "SUBADMIN", 3, false, true,{from: eth.accounts[0]})
{ {
msg: "Action completed successfully", msg: "Action completed successfully",
@ -211,7 +212,7 @@ For adding a sub org the enode id is not mandatory. For the newly created sub or
"0x0638e1574728b6d862dd5d3a3e0942c3be47d996" "0x0638e1574728b6d862dd5d3a3e0942c3be47d996"
``` ```
The role `SUBADMIN` can now be assigned to an account at sub org `SUB1` for making the account admin for the sub org. The role `SUBADMIN` can now be assigned to an account at sub org `SUB1` for making the account admin for the sub org.
```javascript ```
> quorumPermission.addAccountToOrg("0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0", "ORG1.SUB1", "SUBADMIN", {from: "0x0638e1574728b6d862dd5d3a3e0942c3be47d996"}) > quorumPermission.addAccountToOrg("0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0", "ORG1.SUB1", "SUBADMIN", {from: "0x0638e1574728b6d862dd5d3a3e0942c3be47d996"})
{ {
msg: "Action completed successfully", msg: "Action completed successfully",
@ -243,7 +244,7 @@ The role `SUBADMIN` can now be assigned to an account at sub org `SUB1` for maki
} }
``` ```
The account `0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0` is now the admin for sub org `SUB1` and will be able to add roles, accounts and nodes to the sub org. It should be noted that the org admin account at master org level has the admin rights on all the sub organizations below. However the admin account at sub org level has control only in the sub org to which it is linked. The account `0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0` is now the admin for sub org `SUB1` and will be able to add roles, accounts and nodes to the sub org. It should be noted that the org admin account at master org level has the admin rights on all the sub organizations below. However the admin account at sub org level has control only in the sub org to which it is linked.
```javascript ```
> quorumPermission.addNewRole("ORG1.SUB1", "TRANSACT", 1, false, true,{from: "0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"}) > quorumPermission.addNewRole("ORG1.SUB1", "TRANSACT", 1, false, true,{from: "0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"})
{ {
msg: "Action completed successfully", msg: "Action completed successfully",
@ -267,7 +268,7 @@ The account `0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0` is now the admin for su
}] }]
``` ```
To add an account to an organization refer to [addAccountToOrg API](../Permissioning%20apis#quorumpermissionaddaccounttoorg). To add an account to an organization refer to [addAccountToOrg API](../Permissioning%20apis#quorumpermissionaddaccounttoorg).
```javascript ```
> quorumPermission.addAccountToOrg("0x283f3b8989ec20df621166973c93b56b0f4b5455", "ORG1.SUB1", "SUBADMIN", {from: "0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"}) > quorumPermission.addAccountToOrg("0x283f3b8989ec20df621166973c93b56b0f4b5455", "ORG1.SUB1", "SUBADMIN", {from: "0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"})
{ {
msg: "Action completed successfully", msg: "Action completed successfully",
@ -290,7 +291,7 @@ To add an account to an organization refer to [addAccountToOrg API](../Permissio
}] }]
``` ```
To suspend an account [updateAccountStatus](../Permissioning%20apis#quorumpermissionupdateaccountstatus) API can be invoked with action as 1. To suspend an account [updateAccountStatus](../Permissioning%20apis#quorumpermissionupdateaccountstatus) API can be invoked with action as 1.
```javascript ```
> quorumPermission.updateAccountStatus("ORG1.SUB1", "0x283f3b8989ec20df621166973c93b56b0f4b5455", 1, {from: "0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"}) > quorumPermission.updateAccountStatus("ORG1.SUB1", "0x283f3b8989ec20df621166973c93b56b0f4b5455", 1, {from: "0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"})
{ {
msg: "Action completed successfully", msg: "Action completed successfully",
@ -312,7 +313,7 @@ To suspend an account [updateAccountStatus](../Permissioning%20apis#quorumpermis
}] }]
``` ```
To revoke suspension of an account [updateAccountStatus](../Permissioning%20apis#quorumpermissionupdateaccountstatus) API can be invoked with action as 2. To revoke suspension of an account [updateAccountStatus](../Permissioning%20apis#quorumpermissionupdateaccountstatus) API can be invoked with action as 2.
```javascript ```
> quorumPermission.updateAccountStatus("ORG1.SUB1", "0x283f3b8989ec20df621166973c93b56b0f4b5455", 2, {from: "0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"}) > quorumPermission.updateAccountStatus("ORG1.SUB1", "0x283f3b8989ec20df621166973c93b56b0f4b5455", 2, {from: "0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"})
{ {
msg: "Action completed successfully", msg: "Action completed successfully",
@ -335,7 +336,7 @@ To revoke suspension of an account [updateAccountStatus](../Permissioning%20apis
}] }]
``` ```
To [blacklist an account updateAccountStatus](../Permissioning%20apis#quorumpermissionupdateaccountstatus) API can be invoked with action as 3. Once blacklisted no further activity will be possible on the account. To [blacklist an account updateAccountStatus](../Permissioning%20apis#quorumpermissionupdateaccountstatus) API can be invoked with action as 3. Once blacklisted no further activity will be possible on the account.
```javascript ```
> quorumPermission.updateAccountStatus("ORG1.SUB1", "0x283f3b8989ec20df621166973c93b56b0f4b5455", 3, {from: "0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"}) > quorumPermission.updateAccountStatus("ORG1.SUB1", "0x283f3b8989ec20df621166973c93b56b0f4b5455", 3, {from: "0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"})
{ {
msg: "Action completed successfully", msg: "Action completed successfully",
@ -358,7 +359,7 @@ To [blacklist an account updateAccountStatus](../Permissioning%20apis#quorumperm
}] }]
``` ```
To [add nodes addNode ](../Permissioning%20apis#quorumpermissionaddnode) at organization and sub organization level by the org admin. To [add nodes addNode ](../Permissioning%20apis#quorumpermissionaddnode) at organization and sub organization level by the org admin.
```javascript ```
> quorumPermission.addNode("ORG1.SUB1", "enode://eacaa74c4b0e7a9e12d2fe5fee6595eda841d6d992c35dbbcc50fcee4aa86dfbbdeff7dc7e72c2305d5a62257f82737a8cffc80474c15c611c037f52db1a3a7b@127.0.0.1:21005?discport=0", {from: "0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"}) > quorumPermission.addNode("ORG1.SUB1", "enode://eacaa74c4b0e7a9e12d2fe5fee6595eda841d6d992c35dbbcc50fcee4aa86dfbbdeff7dc7e72c2305d5a62257f82737a8cffc80474c15c611c037f52db1a3a7b@127.0.0.1:21005?discport=0", {from: "0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"})
{ {
msg: "Action completed successfully", msg: "Action completed successfully",
@ -376,7 +377,7 @@ To [add nodes addNode ](../Permissioning%20apis#quorumpermissionaddnode) at orga
}] }]
``` ```
Org admin can manage the status of the nodes by using [updateNodeStatus](../Permissioning%20apis#quorumpermissionupdatenodestatus) API. To deactivate a node the API can be invoked with action 1. Org admin can manage the status of the nodes by using [updateNodeStatus](../Permissioning%20apis#quorumpermissionupdatenodestatus) API. To deactivate a node the API can be invoked with action 1.
```javascript ```
> quorumPermission.getOrgDetails("ORG1.SUB1").nodeList > quorumPermission.getOrgDetails("ORG1.SUB1").nodeList
[{ [{
orgId: "ORG1.SUB1", orgId: "ORG1.SUB1",
@ -389,7 +390,7 @@ Org admin can manage the status of the nodes by using [updateNodeStatus](../Perm
}] }]
``` ```
To activate the node back invoke [updateNodeStatus](../Permissioning%20apis#quorumpermissionupdatenodestatus) API with action 2. To activate the node back invoke [updateNodeStatus](../Permissioning%20apis#quorumpermissionupdatenodestatus) API with action 2.
```javascript ```
> quorumPermission.updateNodeStatus("ORG1.SUB1", "enode://eacaa74c4b0e7a9e12d2fe5fee6595eda841d6d992c35dbbcc50fcee4aa86dfbbdeff7dc7e72c2305d5a62257f82737a8cffc80474c15c611c037f52db1a3a7b@127.0.0.1:21005?discport=0",2, {from:"0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"}) > quorumPermission.updateNodeStatus("ORG1.SUB1", "enode://eacaa74c4b0e7a9e12d2fe5fee6595eda841d6d992c35dbbcc50fcee4aa86dfbbdeff7dc7e72c2305d5a62257f82737a8cffc80474c15c611c037f52db1a3a7b@127.0.0.1:21005?discport=0",2, {from:"0x42ef6abedcb7ecd3e9c4816cd5f5a96df35bb9a0"})
{ {
msg: "Action completed successfully", msg: "Action completed successfully",
@ -409,7 +410,7 @@ To activate the node back invoke [updateNodeStatus](../Permissioning%20apis#quor
}] }]
``` ```
To blacklist a node invoke [updateNodeStatus](../Permissioning%20apis#quorumpermissionupdatenodestatus) API with action 3. Once blacklisted the node will never be able join the network again. To blacklist a node invoke [updateNodeStatus](../Permissioning%20apis#quorumpermissionupdatenodestatus) API with action 3. Once blacklisted the node will never be able join the network again.
```javascript ```
> quorumPermission.getOrgDetails("ORG1.SUB1").nodeList > quorumPermission.getOrgDetails("ORG1.SUB1").nodeList
@ -432,7 +433,7 @@ Further:
### Suspending an organization temporarily ### Suspending an organization temporarily
If there is a need to temporarily suspend all activities of an organization [updateOrgStatus](../Permissioning%20apis#quorumpermissionupdateorgstatus) API can be invoked with action 1. This can be invoked only by the network admin accounts and will reuiqre majority voting. If there is a need to temporarily suspend all activities of an organization [updateOrgStatus](../Permissioning%20apis#quorumpermissionupdateorgstatus) API can be invoked with action 1. This can be invoked only by the network admin accounts and will reuiqre majority voting.
```javascript ```
> quorumPermission.updateOrgStatus("ORG1", 1, {from: "0xed9d02e382b34818e88b88a309c7fe71e65f419d"}) > quorumPermission.updateOrgStatus("ORG1", 1, {from: "0xed9d02e382b34818e88b88a309c7fe71e65f419d"})
{ {
msg: "Action completed successfully", msg: "Action completed successfully",
@ -450,7 +451,7 @@ If there is a need to temporarily suspend all activities of an organization [upd
} }
``` ```
To approve the org, suspension majority approval from other network admin accounts is required. The api for the same is [approveOrgStatus](../Permissioning%20apis#quorumpermissionapproveorgstatus). Once approved the org status is marked as suspended. To approve the org, suspension majority approval from other network admin accounts is required. The api for the same is [approveOrgStatus](../Permissioning%20apis#quorumpermissionapproveorgstatus). Once approved the org status is marked as suspended.
```javascript ```
> quorumPermission.approveOrgStatus("ORG1", 1, {from: "0xca843569e3427144cead5e4d5999a3d0ccf92b8e"}) > quorumPermission.approveOrgStatus("ORG1", 1, {from: "0xca843569e3427144cead5e4d5999a3d0ccf92b8e"})
{ {
msg: "Action completed successfully", msg: "Action completed successfully",
@ -472,7 +473,7 @@ When the org is suspended no transaction from any of the account linked to the o
### Revoking suspension of an organization ### Revoking suspension of an organization
To revoke the suspension of an org [updateOrgStatus](../Permissioning%20apis#quorumpermissionupdateorgstatus) can be called with action as 2. This will require majority approval (API [approveOrgStatus](../Permissioning%20apis#quorumpermissionapproveorgstatus) with action 2). To revoke the suspension of an org [updateOrgStatus](../Permissioning%20apis#quorumpermissionupdateorgstatus) can be called with action as 2. This will require majority approval (API [approveOrgStatus](../Permissioning%20apis#quorumpermissionapproveorgstatus) with action 2).
```javascript ```
> quorumPermission.updateOrgStatus("ORG1", 2, {from: "0xed9d02e382b34818e88b88a309c7fe71e65f419d"}) > quorumPermission.updateOrgStatus("ORG1", 2, {from: "0xed9d02e382b34818e88b88a309c7fe71e65f419d"})
{ {
msg: "Action completed successfully", msg: "Action completed successfully",
@ -499,7 +500,7 @@ Once the revoke is approved, all accounts in the organization and sub organizati
### Assigning admin privileges at organization and network level ### Assigning admin privileges at organization and network level
There may be a scenario where one of the accounts at the organization level needs to have network admin level permissions and be able to perform network admin activities. Similarly there can be a need to change the admin account at organization level. Both these activities can be performed by existing network admin accounts only, and will require majority approval from the network admin accounts. The API usage details are as below. There may be a scenario where one of the accounts at the organization level needs to have network admin level permissions and be able to perform network admin activities. Similarly there can be a need to change the admin account at organization level. Both these activities can be performed by existing network admin accounts only, and will require majority approval from the network admin accounts. The API usage details are as below.
To assign network admin or org admin role to an account invoke [assignAdminRole](../Permissioning%20apis#quorumpermissionassignadminrole). To assign network admin or org admin role to an account invoke [assignAdminRole](../Permissioning%20apis#quorumpermissionassignadminrole).
```javascript ```
> quorumPermission.assignAdminRole("ORG1", "0x0638e1574728b6d862dd5d3a3e0942c3be47d996", "ADMIN", {from: "0xed9d02e382b34818e88b88a309c7fe71e65f419d"}) > quorumPermission.assignAdminRole("ORG1", "0x0638e1574728b6d862dd5d3a3e0942c3be47d996", "ADMIN", {from: "0xed9d02e382b34818e88b88a309c7fe71e65f419d"})
{ {
msg: "Action completed successfully", msg: "Action completed successfully",
@ -515,7 +516,7 @@ To assign network admin or org admin role to an account invoke [assignAdminRole]
} }
``` ```
To approve the assignment of network admin role invoke [approveAdminRole](../Permissioning%20apis#quorumpermissionapproveadminrole) API. To approve the assignment of network admin role invoke [approveAdminRole](../Permissioning%20apis#quorumpermissionapproveadminrole) API.
```javascript ```
> quorumPermission.approveAdminRole("ORG1", "0x0638e1574728b6d862dd5d3a3e0942c3be47d996", {from: eth.accounts[0]}) > quorumPermission.approveAdminRole("ORG1", "0x0638e1574728b6d862dd5d3a3e0942c3be47d996", {from: eth.accounts[0]})
{ {
msg: "Action completed successfully", msg: "Action completed successfully",