Skip to content

Commit

Permalink
init permission doc
Browse files Browse the repository at this point in the history
  • Loading branch information
fynnss committed Mar 13, 2023
1 parent 3cd9dcf commit 9d47bfd
Show file tree
Hide file tree
Showing 3 changed files with 118 additions and 4 deletions.
114 changes: 114 additions & 0 deletions docs/modules/permission.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
# permission

The permission module implements basic permission control management for Greenfield.

The data resources, including the objects, buckets, payment accounts, and groups, all have permissions related. These
permissions define whether each account can perform particular actions.

Group is a list of accounts that can be treated in the same way as a single account.

Examples of permissions are:

* Put, List, Get, Delete, Copy, and Execute data objects;
* Create, Delete, and List buckets
* Create, Delete, ListMembersOf, Leave groups
* Create, Associate payment accounts
* Grant, Revoke the above permissions

These permissions are associated with the data resources and accounts/groups, and the group definitions are stored on
the Greenfield blockchain publicly. Now they are in plain text. Later a privacy mode will be introduced based on Zero
Knowledge Proof technology.

One thing that makes the permission operation more interesting is that they can be operated from BSC directly, either
through smart contracts or by an EOA.

The basic interface semantics of permission module are similar to those of S3.

## Concepts

- **Principal**: The greenfield users or groups that can grant permission to.
- **Action**: The operations that can execute in greenfield storage network.
- **Statement**:
- **Resource**:

## State





The permission module keeps state of the following primary objects:

* Policy
* BucketPolicyToAccount: `0x11 | BigEndian(BucketID) | AccAddress -> BigEndian(PolicyID)`
* ObjectPolicyToAccount: `0x12 | BigEndian(ObjectID) | AccAddress -> BigEndian(PolicyID)`
* GroupPolicyToAccount: `0x13 | BigEndian(GroupID) | AccAddress -> BigEndian(PolicyID)`
* PolicyGroup
* BucketPolicyToGroup: `0x21 | BigEndian(BucketID) -> ProtoBuf(PolicyGroup)`
* ObjectPolicyToGroup: `0x22 | BigEndian(ObjectID) -> ProtoBuf(PolicyGroup)`
* PolicyByID: `0x31 | BigEndian(PolicyID) -> ProtoBuf(Policy)`

These primary objects should be primarily stored and accessed by the `ID` which is a auto-incremented sequence. An
additional indices are maintained per primary objects in order to compatibility with the S3 object storage.

### Policy

```protobuf
message Policy {
string id = 1 [
(cosmos_proto.scalar) = "cosmos.Uint",
(gogoproto.customtype) = "Uint",
(gogoproto.nullable) = false
];
permission.Principal principal = 2;
resource.ResourceType resource_type = 3;
string resource_id = 4 [
(cosmos_proto.scalar) = "cosmos.Uint",
(gogoproto.customtype) = "Uint",
(gogoproto.nullable) = false
];
repeated permission.Statement statements = 5;
permission.Statement member_statement = 6;
}
```

### PolicyGroup

Each resource can only grant permissions to a limited number of groups and limited number is defined by
`MaximumGroupNum` in module params.

```protobuf
message PolicyGroup {
message Item {
string policy_id = 1 [
(cosmos_proto.scalar) = "cosmos.Uint",
(gogoproto.customtype) = "Uint",
(gogoproto.nullable) = false
];
string group_id = 2 [
(cosmos_proto.scalar) = "cosmos.Uint",
(gogoproto.customtype) = "Uint",
(gogoproto.nullable) = false
];
}
repeated Item items = 1;
}
```

### params
```protobuf
// Params defines the parameters for the module.
message Params {
option (gogoproto.goproto_stringer) = false;
uint64 maximum_statements_num = 1;
uint64 maximum_group_num = 2;
}
```

## Message

## Events



4 changes: 2 additions & 2 deletions go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ require (
github.com/bits-and-blooms/bitset v1.2.0
github.com/cosmos/go-bip39 v1.0.0
github.com/cosmos/gogoproto v1.4.6
github.com/pkg/errors v0.9.1
github.com/prysmaticlabs/prysm v0.0.0-20220124113610-e26cde5e091b
github.com/rakyll/statik v0.1.7
github.com/samber/lo v1.37.0
Expand Down Expand Up @@ -169,7 +170,6 @@ require (
github.com/pelletier/go-toml v1.9.5 // indirect
github.com/pelletier/go-toml/v2 v2.0.5 // indirect
github.com/petermattis/goid v0.0.0-20180202154549-b0b1615b78e5 // indirect
github.com/pkg/errors v0.9.1 // indirect
github.com/pmezard/go-difflib v1.0.0 // indirect
github.com/prometheus/client_golang v1.12.2 // indirect
github.com/prometheus/client_model v0.2.0 // indirect
Expand Down Expand Up @@ -232,7 +232,7 @@ require (
replace (
cosmossdk.io/math => github.com/bnb-chain/greenfield-cosmos-sdk/math v0.0.0-20230228075616-68ac309b432c
github.com/confio/ics23/go => github.com/cosmos/cosmos-sdk/ics23/go v0.8.0
github.com/cosmos/cosmos-sdk => github.com/bnb-chain/greenfield-cosmos-sdk v0.0.2-0.20230309060234-a16dfc382563
github.com/cosmos/cosmos-sdk => github.com/bnb-chain/greenfield-cosmos-sdk v0.0.2-0.20230310101329-d821547e8f27
github.com/gogo/protobuf => github.com/regen-network/protobuf v1.3.3-alpha.regen.1
github.com/tendermint/tendermint => github.com/bnb-chain/greenfield-tendermint v0.0.2
)
4 changes: 2 additions & 2 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -217,8 +217,8 @@ github.com/blang/semver v3.5.1+incompatible h1:cQNTCjp13qL8KC3Nbxr/y2Bqb63oX6wdn
github.com/blang/semver v3.5.1+incompatible/go.mod h1:kRBLl5iJ+tD4TcOOxsy/0fnwebNt5EWlYSAyrTnjyyk=
github.com/bmizerany/assert v0.0.0-20160611221934-b7ed37b82869/go.mod h1:Ekp36dRnpXw/yCqJaO+ZrUyxD+3VXMFFr56k5XYrpB4=
github.com/bmizerany/pat v0.0.0-20170815010413-6226ea591a40/go.mod h1:8rLXio+WjiTceGBHIoTvn60HIbs7Hm7bcHjyrSqYB9c=
github.com/bnb-chain/greenfield-cosmos-sdk v0.0.2-0.20230309060234-a16dfc382563 h1:TSnMdnQfmYFLdUElquG7wZIKUScOheVyv7QSNC8pVwM=
github.com/bnb-chain/greenfield-cosmos-sdk v0.0.2-0.20230309060234-a16dfc382563/go.mod h1:FrFE0FmMfUYySW5GdlV45b02SYUkNguECpVdZcUJVuU=
github.com/bnb-chain/greenfield-cosmos-sdk v0.0.2-0.20230310101329-d821547e8f27 h1:whCI/WUTcRpFtwqIPOzPjnEvl+/J9Q1HCX5YaJArFOw=
github.com/bnb-chain/greenfield-cosmos-sdk v0.0.2-0.20230310101329-d821547e8f27/go.mod h1:C0poOez5FBpH4Y/oa9jmco2fRojeMsJZGOZEX+GOv8w=
github.com/bnb-chain/greenfield-cosmos-sdk/math v0.0.0-20230228075616-68ac309b432c h1:BLmdYaj7Dx0YOhfk77+KPPJSMCwpQl6f4Y30+801bf0=
github.com/bnb-chain/greenfield-cosmos-sdk/math v0.0.0-20230228075616-68ac309b432c/go.mod h1:u/MXvf8wbUbCsAEyQSSYXXMsczAsFX48e2D6JI86T4o=
github.com/bnb-chain/greenfield-tendermint v0.0.2 h1:SNb3C9QhYklaLgY6onimLHR42IlB6NQJvQqwmj/1ybM=
Expand Down

0 comments on commit 9d47bfd

Please sign in to comment.