FIP-40 design guide
Description
This document contains a detailed look at the design possibility for FIP-40 where we consider to add a generalized architectural design pattern for the permissions/access control that are being considered in FIP-40.
fips/fip-0040.md at master ยท fioprotocol/fips
Overview
There are well established design patterns for authorization/access control. We will explore theseโฆ.
Please see the following link for an overview of the authentication and authorization design pattern concepts which are foundational for this discussion. There are many links reflecting the various authorization design patterns that are very mature in operating system design and system design. We chose this one arbitrarily (any example should serve us well)
Pattern-Oriented Software Architecture - Access control pattern
When considering how to design a generalized access model for the FIO protocols uses we will use the following vernacular .
ย
Grantor โ the granting/owning account of a given access control (the owner of a domain).
Object โ the object that is being access controlled (for FIP-40 this is the domain).
Grantee โ the non grantor account that is granted the ability to register fio handles on a specific domain in the FIO protocol.
Access control โ the json definition of the access control, a name, along with any other specific information that defines the important aspects of this permission. (for FIP-40 ' โnameโ:โregfionandleondomainโ, โdomainโ:โTHEDOMAINNAMEโ, โdomainidโ:idofdomainfromdomains ')
AccessGroup โ this is a grouping of grantees by access control.
Query Requirements
The following query-ability requirements have been identified during brainstorming of the various lookups that might be useful for the contracts, block producers, and other community members.
ย
Get all grantees by domain name โ (this will require paging approaches as there can conceivably be 100s of thousands of more accounts using this new access control on a given domain).
Get all the objects that have a certain access control โ
by owning account. โ get all domains owned by this account that are using this access control.
all-inclusive -- get all domains protocol wide that are using this access control.
Get a list of all access controls granted on a given object โ get a comprehensive list of accesses on an object.
Get a list of accounts using the access control in the FIO protocol โ return a paging enabled by account view of accounts using this access control.
Get a yes/no answer does this account have this access control granted.
ย
Proposed Table Scheme
We propose the following table scheme as a straw man for further consideration and discussion.
Assumptions
This straw man can be further generalized to provide more adaptability of the FIO protocol going forward. This straw man was chosen as a sensible compromise that will also meet the use cases for the applications of fee and payment that have been discussed by Pawel.
The scheme will contain the following tables which will exist in state:
Permissions table โ this table captures the info relating to an access control on a given object for a given grantor that can be used by owning accounts
Access table โ this table records the grantees given access to the access control on an object.
Permissions table
Id โ the unique id for each record in the table
object type โ the name of the type of object to be controlled. ( the object is a string โdomainโ). Object types are pre-defined by FIO.
object type hash โ hash of the object type
object name โ the name of the object being controlled. (for this example the domain name). Defined by the owner.
object name hash โ the hash of the object name
permission name โ the name of the permission (for this example โregfionandleondomainโ). Permission names are pre-defined by FIO.
permission name hash โ hash of the permission name
permission control hash โ combine object type, object name, permission name and hash them for permission lookup.
Auxilliary info -any other useful info relating to this permission control contained in a json string
Owner. โ Fio account owning the permission group (e.g., the domain owner account)
candidate indexes
primary index
id โ provide a unique id for each record for admin purposes.
secondary index
object type hash โ lookup by object type
object name hash โ lookup by object name
permission name hash - lookup by permission name
permission control hash โ lookup by permission control (combined hash)
owner โ lookup by owner
ย Access table
Id โ provide a unique id for records for adminstration purposes.
Permission Id โ this is the id from the permission table that describes access info
Grantee account โ this is the account of the grantee.
Access hash โ hash of grantee account and permission id
ย
candidate indexes
primary index
id โ provide a unique index for each record for admin purposes.
secondary indices
permission id โ lookup by permission id
grantee account โ lookup by grantee account
access hash โ lookup by unique hash (hasAccess)
fio.access contract actions
grantperm โ this action will create a new permission in the permission table and add an entry for access in the access table.
parameters
grantee account โ deshputyz
actor โ asdftredg
object type โโdomainโ
object name โ โfredspaceโ
permission name โ โregfiohandleondomainโ
Auxilliary info - โโ (this means no aux info for this access)
this will perform steps 2 and 3 in the below example.
ย
removeperm โ this action will remove a permission and associated access records from the permission table.
permission name
actor โ the calling account, must the the owner of the target state object for this permission (for domain access the owner account of the domain).
NOTE โ must think this call through, as the number of accounts to be removed may be large, so maybe we remove a fixed number per call and throw โno work exceptionโ when there are none left to remove..
decision โ we will not permit the blank to be used, any calls that might exceed time limits on the chain will be examined as the detailed design continues.
ย
removeaccess โ this action will remove a specific access previously granted to an account, removing the specified accounts record from the access table for the specified permission.
parameters
grantee account โ the account for which to remove the permission.
permission name โ the name of the permission which is being removed from the account.
actor โ the calling account, must the the owner of the target state object for this permission (for domain access the owner account of the domain).
ย
ย
ย
ย
Example: demonstrating use of permission tables
Preconditions
As noted above, FIO will pre-define the set of the acceptable
permission names
that are permittedFor FIP-40 (for example) there will be only one permission name that is permissible:
regfiohandleondomain
Accounts
Grantor account
asdftredg
-- this account will be the owner of domain "fredspace"Grantee account
deshputyz
-- this account will be the non domain owning account registering fio handles on "fredspace"
Step 1. Grantor account calls permission action
In this step, the Grantor account asdftredg
will invoke an action on the fio.access
contract to create a new permission (if it does not already exist) and assign that permission to the Grantee
grant access
parameters
grantee account โ deshputyz
actor โ asdftredg
object type โโdomainโ
object name โ โfredspaceโ
permission name โ โregfionandleondomainโ
Auxilliary info - โโ (this means no aux info for this access)
Step 2: Action creates Permission Table entry (creates a permission)
The action will look in the permission info table for a permission with the same object type, object name, and permission name (i.e., the permission control hash), if it exists then the existing permission will be used. if it doesn't exist a new permission will be added.
Permission table entry:
Id โ 4
object type โ โdomainโ
object type hash โ 0xgfhglj;ghj;ghghe;ghjghgjhgd
object name โ โfredspaceโ
object name hash โoxkgljgkljglkghjkljgkhkghkgjgklgjkljgklgj
permission name โ โregfionandleondomainโ
permission name hash โ 0xoituoieunkletighighiotuiighioeieuteiourgy
permission control hash โ combine object type, object name, permission name and hash them for access lookup.
Auxilliary info -โโ
Owner. โ asdftredg
Step 3: Action creates Access Table entry (assigns permission to Grantee)
Next the action will look in the access table for an entry for deshputyz
If it exists it will be verified if it doesnt it will be created:
Access table entry:
Id โ 10
Permission Id โ 4
Grantee account โ deshputyz
access hash โ the hash of account and access info id..
Step 4. Checking permissions during an addaddress
action call
Now we can check access when addaddress
is called by the Grantee account:
has access --
parameters
grantee account -- deshputyz
object type โ โdomainโ
object name โ โfredspaceโ
permission name โ- regfionandleondomain
The getter:
hashes the combination of (object type, object name, permission name)
looks up the permission by the hash
gets the id (e.g., Id 4)
looks for the
access hash
(the hash of the permission Id and the accountdeshputyz4
) in the access tableIf it finds a match, the access call returns true.
Because it is the Grantee calling the action, the Grantee pays the fees
ย
ย
ย
ย
ย
ย
project planning --
ย
FIP-40 path with new access contract.
ย
create a new contract (fio.access).
create a detailed design for this access contract.
create detailed unit tests for the new contract (unit testing will be the only testing performed specifically on this new contract).
complete new contract testing
integrate new contract into the FIP-40 changes.
complete dev testing.
document rollout plan for FIP-40.
release implementation to QA
total estimation of dev. effort 3 weeks.
ย
ย
FIP-40 without new access contract
choose design approach for the project.
create detailed design document for the project .
complete integration of new logic (longer because of more code in the integration logic).
complete dev testing
document rollout plan for FIP-40
release implementation to QA
total estimation of dev effort 2 weeks.
ย