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 .

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 ')

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

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 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

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

Permission Id – this is the id from the permission table that describes access info

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 permitted

• For 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

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:

object type – “domain”

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 -””

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:

Permission Id – 4

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 account deshputyz4) in the access table

  • If 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.

1. create a new contract (fio.access).

2. create a detailed design for this access contract.

3. create detailed unit tests for the new contract (unit testing will be the only testing performed specifically on this new contract).

4. complete new contract testing

5. integrate new contract into the FIP-40 changes.

6. complete dev testing.

7. document rollout plan for FIP-40.

8. release implementation to QA

total estimation of dev. effort 3 weeks.

FIP-40 without new access contract

1. choose design approach for the project.

2. create detailed design document for the project .

3. complete integration of new logic (longer because of more code in the integration logic).

4. complete dev testing

5. document rollout plan for FIP-40

6. release implementation to QA

total estimation of dev effort 2 weeks.