Fine-Grained Access Control Library Functions

The library package provides the following functions for Resources, Groups and ACLs as well as global functions.

Global Functions

Function Description
Initialization(identity *x509.Certificate, stub shim.ChaincodeStubInterface) (error) (error)

When the chaincode is instantiated, the Initialization function is called. That function will initialize the world state with some built in access control lists. These built in lists are used to bootstrap the environment. So there needs to be access control on who can create resources, groups, and ACLs. If the identify is nil, then use the caller's identify.

After the bootstrap is done, the following entities are created:

  • A resource named ".Resources". A corresponding ACL named ".Resources.ACL" will be created with a single identity pattern in it of the form "%CN%bob.smith@oracle.com", using the actual common name, and the access will be CREATE, READ, UPDATE, and DELETE access.
  • A group named ".Groups". A corresponding ACL named ".Groups.ACL" will be created with a single identity pattern in it of the form "%CN%bob.smith@oracle.com", using the actual common name, and the access will be CREATE, READ, UPDATE, and DELETE access.
  • An ACL named ".ACLs". A corresponding ACL control list named ".ACLs.ACL" will be created with a single identity pattern in it of the form "%CN%bob.smith@oracle.com", using the actual common name, and the access will be CREATE, READ, UPDATE, and DELETE access.
NewGroupManager(identity *x509.Certificate, stub shim.ChaincodeStubInterface) (*GroupManager, error)

Get the group manager that's used for all group related operations.

Identity: the default identity for related operation. If it's nil, then use caller's identity.
NewACLManager(identity *x509.Certificate, stub shim.ChaincodeStubInterface) (*ACLManager, error)

Get the ACL manager that's used for all ACL related operations.

Identity: the default identity for related operation. If it's nil, then use caller's identity.
NewResourceManager(identity *x509.Certificate, stub shim.ChaincodeStubInterface) (*ResourceManager, error)

Get the resource manager that's used for all resource related operations.

Identity: the default identity for related operation. If it's nil, then use caller's identity.

Access Control List (ACL) Functions

Definition of ACL structure:
type ACL struct {
  Name string
  Description string
  Accesses []string  // CREATE, READ, UPDATE, and DELETE, or whatever the end-user defined
  Patterns []string    // identities
  Allowed bool          // true means allows access.
  BindACLs []string  // The list of ACL , control who can call the APIs of this struct
}
  • Accesses: The Accesses string is a list of comma-separated arbitrary access names and completely up to the application except for four: CREATE, READ, UPDATE, and DELETE. These access values are used in maintaining the fine grained access control. Applications can use their own access strings such as "register", "invoke", or "query", or even such things as access to field names such as "owner", "quantity", and so on.
  • Allowed: Allowed determines whether identities that match a pattern are allowed access (true) or prohibited access (false). You could have an access control list that indicates Bob has access to "CREATE", and another one that indicates group Oracle (of which Bob is a member) is prohibited from "CREATE". Whether Bob has access or not depends upon the order of the access control lists associated with the entity in question.
  • BindACLs: The BindACLs parameter will form the initial access control list.

ACL functions:

Function Description
Create(acl ACL, identity *x509.Certificate) (error)

Creates a new ACL. Duplicate named ACL are not allowed.

To create a new ACL, the identity needs to have CREATE access to the bootstrap resource named ".ACLs". If identity is nil, the default identity specified in newACLManager() is used.
Get(aclName string, identity *x509.Certificate) (ACL, error)

Get a named ACL.

The identity must have READ access to the named ACL. If identity is nil, the default identity specified in newACLManager() is used.
Delete(aclName string, identity *x509.Certificate) (error)

Delete a specified ACL.

The identity must have DELETE access to the named ACL. If identity is nil, the default identity specified in newACLManager() is used.
Update(acl ACL, identity *x509.Certificate) (error)

Update an ACL.

The identity must have UPDATE access to the named resource, and the named ACL must exist. If identity is nil, the default identity specified in NewACLManager() is used.
AddPattern(aclName string, pattern string, identity *x509.Certificate) (error)

Adds a new identity pattern to the named ACL. The identity must have UPDATE access to the named ACL.

If identity is nil, the default identity specified in newACLManager() is used.
RemovePattern(aclName string, pattern string, identity *X509Certificate) (error)

Removes the identity pattern from the ACL. The identity must have UPDATE access to the named ACL.

If identity is nil, the default identity specified in newACLManager() is used.
AddAccess(aclname string, access string, identity *X509Certificate) (error)

Adds a new access to the named ACL. The identity must have UPDATE access to the named ACL.

If identity is nil, the default identity specified in newACLManager() is used.
RemoveAccess(aclName string, access string, identity *X509Certificate) (error)

Removes the access from the ACL. The identity must have UPDATE access to the named ACL.

If identity is nil, the default identity specified in newACLManager() is used.
UpdateDescription(aclName string, newDescription string, identity *X509Certificate) (error)

Update the description.

The identity must have UPDATE access to the named ACL. If identity is nil, the default identity specified in newACLManager() is used.
AddBeforeACL(aclName string, beforeName string, newBindACL string, identity *X509Certificate) (error)

Adds a bind ACL before the existing named ACL. If the named ACL is empty or not found, the ACL is added to the beginning of the bind ACL list.

The identity must have UPDATE access to the named ACL. If the identity is nil, the default identity specified in newACLManager() is used.
AddAfterACL(aclName string, afterName string, newBindACL string, identity *X509Certificate) (error)

Adds a bind ACL after the existing named ACL. If the named ACL is empty or not found, the ACL is added to the end of the bind ACL list.

The identity must have UPDATE access to the named ACL. If the identity is nil, the default identity specified in newACLManager() is used.
RemoveBindACL(aclName string, removeName string, identity *X509Certificate) (error)

Removes the removeName ACL from the bind ACL list.

The identity must have UPDATE access to the named ACL. If the identity is nil, the default identity specified in newACLManager() is used.
GetAll(identity *x509.Certificate) ([]ACL, error)

Get all the ACLs.

The identity must have READ access to the named ACL. If the identity is nil, the default identity specified in newACLManager() is used.

Group Functions

Definition of Group structure:
type Group struct {
    Name string
    Description string
    Members []string     // identity patterns, except GRP.
    BindACLs []string    // The list of ACLs, controls who can access this group.
}

Definition of GroupManager functions:

Function Description
Create(group Group, identity *x509.Certificate) (error)

Create a new group.

The identity must have CREATE access to bootstrap group ".Group". If identity is nil, the default identity specified in NewGroupManager() is used.
Get(groupName string, identity *x509.Certificate) (Group, error)

Get a specified group.

The identity must have READ access to this group. If identity is nil, the default identity specified in NewGroupManager() is used.
Delete(groupName string, identity *x509.Certificate) (error)

Delete a specified group.

The identity must have DELETE access to this group. If identity is nil, the default identity specified in NewGroupManager () is used.
AddMembers(groupName string, member []string, identity *x509.Certificate) (error)

Add one or more members into the group.

The identity must have UPDATE access to this group. If identity is nil, the default identity specified in NewGroupManager () is used.
RemoveMembers(groupName string, member []string, identity *x509.Certificate) (error)

Remove one or more member from a group.

The identity must have UPDATE access to this group. If identity is nil, the default identity specified in NewGroupManager () is used.
UpdateDescription(groupName string, newDes string, identity *x509.Certificate) (error)

Update the description.

The identity must have UPDATE access to this group. If identity is nil, the default identity specified in NewGroupManager () is used.
AddBeforeACL(groupName string, beforeName string, aclName string, identity *x509.Certificate) (error)

Adds an bind ACL to the group before the existing named ACL. If the named ACL is empty or not found, the ACL is added to the beginning of the list of bind ACL for the resource.

The identity must have UPDATE access to the named group. If identity is nil, the default identity specified in NewGroupManager () is used.
AddAfterACL(groupName string, afterName string, aclName string, identity *x509.Certificate) (error)

Adds a bind ACL to the group after the existing named ACL. If the named ACL is empty or not found, the ACL is added to the end of the list of bind ACL for the group.

The identity must have UPDATE access to the named group. If the identity is nil, the default identity specified in NewGroupManager () is used.
RemoveBindACL(groupName string, aclName string, identity *x509.Certificate) (error)

Removes the named ACL from the bind ACL list of the named group.

The identity must have UPDATE access to the named group. If the identity is nil, the default identity specified in NewGroupManager () is used.
GetAll(identity *x509.Certificate) ([]Group, error)

Get all groups.

The identity must have READ access to these groups. If identity is nil, the default identity specified in NewGroupManager () is used.

Resource Functions

Definition of Resource structure:
type Resource struct {
     Name string
     Description string
     BindACLs []string      // The name list of ACL, controls who can access this resource
}

Resource Functions:

Fuction Description
Create(resource Resource, identity *x509.Certificate) (error)

Create a new resource. Duplicate named resources are not allowed.

The identity needs to have CREATE access to the bootstrap resource named ".Resources" If identity is null, the default identity specified in NewResourceManager() is used.
Get(resName string, identity *x509.Certificate) (Resource, error)

Get a specified resource.

The identity must have READ access to the resource. If identity is null, the default identity specified in NewResourceManager() is used.
Delete(resName string, identity *x509.Certificate) (error)

Delete a named resource.

The identity must have DELETE access to the named resource. If identity is null, the default identity specified in NewResourceManager() is used.
UpdateDescription(resourceName string, newDes string, identity *x509.Certificate) (error)

Update the description.

The identity must have UPDATE access to this resource. If identity is nil, the default identity specified in NewResourceManager() is used.
AddBeforeACL(resourceName string, beforeName string, aclName string, identity *x509.Certificate) (error)

Adds a bind ACL to the resource before the existing named ACL. If the named ACL is empty or not found, the ACL is added to the beginning of the list of bind ACL for the resource.

The identity must have UPDATE access to the named resource. If identity is nil, the default identity specified in NewResourceManager() is used.
AddAfterACL(resourceName string, afterName string, aclName string, identity *x509.Certificate) (error)

Adds a bind ACL to the resource after the existing named ACL. If the named ACL is empty or not found, the ACL is added to the end of the list of bind ACL for the resource.

The identity must have UPDATE access to the named resource. If the identity is nil, the default identity specified in NewResourceManager() is used.
RemoveBindACL(resourceName string, aclName string, identity *x509.Certificate) (error)

Removes the named ACL from the bind ACL list of the named resource.

The identity must have UPDATE access to the named resource. If the identity is nil, the default identity specified in NewResourceManager() is used.
CheckAccess(resName string, access string, identity *x509.Certificate) (bool, error)

Check whether the current user has the specified access to the named resource.

If the identity is nil, the default identity specified in NewResourceManager() is used.
GetAll(identity *x509.Certificate) ([]Resource, error)

Get all resources.

The identity must have READ access to these resources. If identity is nil, the default identity specified in NewResourceManager() is used.