Policies

Audience: Architects, application and smart contract developers, administrators

In this topic, we’ll cover:

Note: this topic describes a network that does not use a “system channel”, a channel that the ordering service is bootstrapped with and the ordering service exclusively controls. Since the release of v2.3, using system channel is now considered the legacy process as compared to the process to Create a channel without a system channel. For a version of this topic that includes information about the system channel, check out Policies from the v2.2 documentation.

What is a policy

At its most basic level, a policy is a set of rules that define the structure for how decisions are made and specific outcomes are reached. To that end, policies typically describe a who and a what, such as the access or rights that an individual has over an asset. We can see that policies are used throughout our daily lives to protect assets of value to us, from car rentals, health, our homes, and many more.

For example, an insurance policy defines the conditions, terms, limits, and expiration under which an insurance payout will be made. The policy is agreed to by the policy holder and the insurance company, and defines the rights and responsibilities of each party.

Whereas an insurance policy is put in place for risk management, in Hyperledger Fabric, policies are the mechanism for infrastructure management. Fabric policies represent how members come to agreement on accepting or rejecting changes to the network, a channel, or a smart contract. Policies are agreed to by the channel members when the channel is originally configured, but they can also be modified as the channel evolves. For example, they describe the criteria for adding or removing members from a channel, change how blocks are formed, or specify the number of organizations required to endorse a smart contract. All of these actions are described by a policy which defines who can perform the action. Simply put, everything you want to do on a Fabric network is controlled by a policy.

Why are policies needed

Policies are one of the things that make Hyperledger Fabric different from other blockchains like Ethereum or Bitcoin. In those systems, transactions can be generated and validated by any node in the network. The policies that govern the network are fixed at any point in time and can only be changed using the same process that governs the code. Because Fabric is a permissioned blockchain whose users are recognized by the underlying infrastructure, those users have the ability to decide on the governance of the network before it is launched, and change the governance of a running network.

Policies allow members to decide which organizations can access or update a Fabric network, and provide the mechanism to enforce those decisions. Policies contain the lists of organizations that have access to a given resource, such as a user or system chaincode. They also specify how many organizations need to agree on a proposal to update a resource, such as a channel or smart contracts. Once they are written, policies evaluate the collection of signatures attached to transactions and proposals and validate if the signatures fulfill the governance agreed to by the network.

How are policies implemented

Policies are defined within the relevant administrative domain of a particular action defined by the policy. For example, the policy for adding a peer organization to a channel is defined within the administrative domain of the peer organizations (known as the Application group). Similarly, adding ordering nodes in the consenter set of the channel is controlled by a policy inside the Orderer group. Actions that cross both the peer and orderer organizational domains are contained in the Channel group.

Typically, these policies default to the “majority of admins” of the group they fall under (a majority of peer organization admins for example, or in the case of Channel policies, a majority of both peer organizations and orderer organizations), though they can be specified to any rule a user wishes to define. Check out Signature policies for more information.

Access control lists (ACLs)

Network administrators will be especially interested in the Fabric use of ACLs, which provide the ability to configure access to resources by associating those resources with existing policies. These “resources” could be functions on system chaincode (e.g., “GetBlockByNumber” on the “qscc” system chaincode) or other resources (e.g.,who can receive Block events). ACLs refer to policies defined in an application channel configuration and extends them to control additional resources. The default set of Fabric ACLs is visible in the configtx.yaml file under the Application: &ApplicationDefaults section but they can and should be overridden in a production environment. The list of resources named in configtx.yaml is the complete set of all internal resources currently defined by Fabric.

In that file, ACLs are expressed using the following format:

# ACL policy for chaincode to chaincode invocation
peer/ChaincodeToChaincode: /Channel/Application/Writers

Where peer/ChaincodeToChaincode represents the resource being secured and /Channel/Application/Writers refers to the policy which must be satisfied for the associated transaction to be considered valid.

For a deeper dive into ACLS, refer to the topic in the Operations Guide on ACLs.

Smart contract endorsement policies

Every smart contract inside a chaincode package has an endorsement policy that specifies how many peers belonging to different channel members need to execute and validate a transaction against a given smart contract in order for the transaction to be considered valid. Hence, the endorsement policies define the organizations (through their peers) who must “endorse” (i.e., approve of) the execution of a proposal.

Modification policies

There is one last type of policy that is crucial to how policies work in Fabric, the Modification policy. Modification policies specify the group of identities required to sign (approve) any configuration update. It is the policy that defines how the policy is updated. Thus, each channel configuration element includes a reference to a policy which governs its modification.

How do you write a policy in Fabric

If you want to change anything in Fabric, the policy associated with the resource describes who needs to approve it, either with an explicit sign off from individuals, or an implicit sign off by a group. In the insurance domain, an explicit sign off could be a single member of the homeowners insurance agents group. And an implicit sign off would be analogous to requiring approval from a majority of the managerial members of the homeowners insurance group. This is particularly useful because the members of that group can change over time without requiring that the policy be updated. In Hyperledger Fabric, explicit sign offs in policies are expressed using the Signature syntax and implicit sign offs use the ImplicitMeta syntax.

Signature policies

Signature policies define specific types of users who must sign in order for a policy to be satisfied such as OR('Org1.peer', 'Org2.peer'). These policies are considered the most versatile because they allow for the construction of extremely specific rules like: “An admin of org A and 2 other admins, or 5 of 6 organization admins”. The syntax supports arbitrary combinations of AND, OR and NOutOf. For example, a policy can be easily expressed by using AND('Org1.member', 'Org2.member') which means that a signature from at least one member in Org1 AND one member in Org2 is required for the policy to be satisfied.

ImplicitMeta policies

ImplicitMeta policies are only valid in the context of channel configuration which is based on a tiered hierarchy of policies in a configuration tree. ImplicitMeta policies aggregate the result of policies deeper in the configuration tree that are ultimately defined by Signature policies. They are Implicit because they are constructed implicitly based on the current organizations in the channel configuration, and they are Meta because their evaluation is not against specific MSP principals, but rather against other sub-policies below them in the configuration tree.

The following diagram illustrates the tiered policy structure for an application channel and shows how the ImplicitMeta channel configuration admins policy, named /Channel/Admins, is resolved when the sub-policies named Admins below it in the configuration hierarchy are satisfied where each check mark represents that the conditions of the sub-policy were satisfied.

policies.policies

As you can see in the diagram above, ImplicitMeta policies, Type = 3, use a different syntax, "<ANY|ALL|MAJORITY> <SubPolicyName>", for example:

`MAJORITY sub policy: Admins`

The diagram shows a sub-policy Admins, which refers to all the Admins policy below it in the configuration tree. You can create your own sub-policies and name them whatever you want and then define them in each of your organizations.

As mentioned above, a key benefit of an ImplicitMeta policy such as MAJORITY Admins is that when you add a new admin organization to the channel, you do not have to update the channel policy. Therefore ImplicitMeta policies are considered to be more flexible as organizations are added. Recall that ImplicitMeta policies ultimately resolve the Signature sub-policies underneath them in the configuration tree as the diagram shows.

You can also define an application level implicit policy to operate across organizations, in a channel for example, and either require that ANY of them are satisfied, that ALL are satisfied, or that a MAJORITY are satisfied. This format lends itself to much better, more natural defaults, so that each organization can decide what it means for a valid endorsement.

Further granularity and control can be achieved if you include NodeOUs in your organization definition. Organization Units (OUs) are defined in the Fabric CA client configuration file and can be associated with an identity when it is created. In Fabric, NodeOUs provide a way to classify identities in a digital certificate hierarchy. For instance, an organization having specific NodeOUs enabled could require that a ‘peer’ sign for it to be a valid endorsement, whereas an organization without any might simply require that any member can sign.

An example: channel configuration policy

Understanding policies begins with examining the configtx.yaml where the channel policies are defined. We can use the configtx.yaml file in the Fabric test network to see examples of both policy syntax types. We are going to examine the configtx.yaml file used by the fabric-samples/test-network sample.

The first section of the file defines the organizations that will be members of the channel. Inside each organization definition are the default policies for that organization, Readers, Writers, Admins, and Endorsement, although you can name your policies anything you want. Each policy has a Type which describes how the policy is expressed (Signature or ImplicitMeta) and a Rule.

The test network example below shows the Org1 organization definition in the channel, where the policy Type is Signature and the Endorsement: policy rule is defined as "OR('Org1MSP.peer')". This policy specifies that a peer that is a member of Org1MSP is required to sign. It is these signature policies that become the sub-policies that the ImplicitMeta policies point to.

Click here to see an example of an organization defined with signature policies 

- &Org1
       # DefaultOrg defines the organization which is used in the sampleconfig
       # of the fabric.git development environment
       Name: Org1MSP

       # ID to load the MSP definition as
       ID: Org1MSP

       MSPDir: ../organizations/peerOrganizations/org1.example.com/msp

       # Policies defines the set of policies at this level of the config tree
       # For organization policies, their canonical path is usually
       #   /Channel/<Application|Orderer>/<OrgName>/<PolicyName>
       Policies:
           Readers:
               Type: Signature
               Rule: "OR('Org1MSP.admin', 'Org1MSP.peer', 'Org1MSP.client')"
           Writers:
               Type: Signature
               Rule: "OR('Org1MSP.admin', 'Org1MSP.client')"
           Admins:
               Type: Signature
               Rule: "OR('Org1MSP.admin')"
           Endorsement:
               Type: Signature
               Rule: "OR('Org1MSP.peer')"

The next example shows the ImplicitMeta policy type used in the Application section of the configtx.yaml. These set of policies lie on the /Channel/Application/ path. If you use the default set of Fabric ACLs, these policies define the behavior of many important features of application channels, such as who can query the channel ledger, invoke a chaincode, or update a channel config. These policies point to the sub-policies defined for each organization. The Org1 defined in the section above contains Reader, Writer, and Admin sub-policies that are evaluated by the Reader, Writer, and Admin ImplicitMeta policies in the Application section. Because the test network is built with the default policies, you can use the example Org1 to query the channel ledger, invoke a chaincode, and approve channel updates for any test network channel that you create.

Click here to see an example of ImplicitMeta policies 

################################################################################
#
#   SECTION: Application
#
#   - This section defines the values to encode into a config transaction or
#   genesis block for application related parameters
#
################################################################################
Application: &ApplicationDefaults

    # Organizations is the list of orgs which are defined as participants on
    # the application side of the network
    Organizations:

    # Policies defines the set of policies at this level of the config tree
    # For Application policies, their canonical path is
    #   /Channel/Application/<PolicyName>
    Policies:
        Readers:
            Type: ImplicitMeta
            Rule: "ANY Readers"
        Writers:
            Type: ImplicitMeta
            Rule: "ANY Writers"
        Admins:
            Type: ImplicitMeta
            Rule: "MAJORITY Admins"
        LifecycleEndorsement:
            Type: ImplicitMeta
            Rule: "MAJORITY Endorsement"
        Endorsement:
            Type: ImplicitMeta
            Rule: "MAJORITY Endorsement"

Fabric chaincode lifecycle

In the Fabric 2.0 release, a new chaincode lifecycle process was introduced, whereby a more democratic process is used to govern chaincode on the network. The new process allows multiple organizations to vote on how a chaincode will be operated before it can be used on a channel. This is significant because it is the combination of this new lifecycle process and the policies that are specified during that process that dictate the security across the network. More details on the flow are available in the Fabric chaincode lifecycle concept topic, but for purposes of this topic you should understand how policies are used in this flow. The new flow includes two steps where policies are specified: when chaincode is approved by organization members, and when it is committed to the channel.

The Application section of the configtx.yaml file includes the default chaincode lifecycle endorsement policy. In a production environment you would customize this definition for your own use case.

################################################################################
#
#   SECTION: Application
#
#   - This section defines the values to encode into a config transaction or
#   genesis block for application related parameters
#
################################################################################
Application: &ApplicationDefaults

    # Organizations is the list of orgs which are defined as participants on
    # the application side of the network
    Organizations:

    # Policies defines the set of policies at this level of the config tree
    # For Application policies, their canonical path is
    #   /Channel/Application/<PolicyName>
    Policies:
        Readers:
            Type: ImplicitMeta
            Rule: "ANY Readers"
        Writers:
            Type: ImplicitMeta
            Rule: "ANY Writers"
        Admins:
            Type: ImplicitMeta
            Rule: "MAJORITY Admins"
        LifecycleEndorsement:
            Type: ImplicitMeta
            Rule: "MAJORITY Endorsement"
        Endorsement:
            Type: ImplicitMeta
            Rule: "MAJORITY Endorsement"
  • The LifecycleEndorsement policy governs who needs to approve a chaincode definition.
  • The Endorsement policy is the default endorsement policy for a chaincode. More on this below.

Chaincode endorsement policies

The endorsement policy is specified for a chaincode when it is approved and committed to the channel using the Fabric chaincode lifecycle (that is, one endorsement policy covers all of the state associated with a chaincode). The endorsement policy can be specified either by reference to an endorsement policy defined in the channel configuration or by explicitly specifying a Signature policy.

If an endorsement policy is not explicitly specified during the approval step, the default Endorsement policy "MAJORITY Endorsement" is used which means that a majority of the peers belonging to the different channel members (organizations) need to execute and validate a transaction against the chaincode in order for the transaction to be considered valid. This default policy allows organizations that join the channel to become automatically added to the chaincode endorsement policy. If you don’t want to use the default endorsement policy, use the Signature policy format to specify a more complex endorsement policy (such as requiring that a chaincode be endorsed by one organization, and then one of the other organizations on the channel).

Signature policies also allow you to include principals which are simply a way of matching an identity to a role. Principals are just like user IDs or group IDs, but they are more versatile because they can include a wide range of properties of an actor’s identity, such as the actor’s organization, organizational unit, role or even the actor’s specific identity. When we talk about principals, they are the properties which determine their permissions. Principals are described as 'MSP.ROLE', where MSP represents the required MSP ID (the organization), and ROLE represents one of the four accepted roles: Member, Admin, Client, and Peer. A role is associated to an identity when a user enrolls with a CA. You can customize the list of roles available on your Fabric CA.

Some examples of valid principals are:

  • ‘Org0.Admin’: an administrator of the Org0 MSP
  • ‘Org1.Member’: a member of the Org1 MSP
  • ‘Org1.Client’: a client of the Org1 MSP
  • ‘Org1.Peer’: a peer of the Org1 MSP
  • ‘OrdererOrg.Orderer’: an orderer in the OrdererOrg MSP

There are cases where it may be necessary for a particular state (a particular key-value pair, in other words) to have a different endorsement policy. This state-based endorsement allows the default chaincode-level endorsement policies to be overridden by a different policy for the specified keys.

For a deeper dive on how to write an endorsement policy refer to the topic on Endorsement policies in the Operations Guide.

Note: Policies work differently depending on which version of Fabric you are using:

  • In Fabric releases prior to 2.0, chaincode endorsement policies can be updated during chaincode instantiation or by using the chaincode lifecycle commands. If not specified at instantiation time, the endorsement policy defaults to “any member of the organizations in the channel”. For example, a channel with “Org1” and “Org2” would have a default endorsement policy of “OR(‘Org1.member’, ‘Org2.member’)”.
  • Starting with Fabric 2.0, Fabric introduced a new chaincode lifecycle process that allows multiple organizations to agree on how a chaincode will be operated before it can be used on a channel. The new process requires that organizations agree to the parameters that define a chaincode, such as name, version, and the chaincode endorsement policy.

Overriding policy definitions

Hyperledger Fabric includes default policies which are useful for getting started, developing, and testing your blockchain, but they are meant to be customized in a production environment. You should be aware of the default policies in the configtx.yaml file. Channel configuration policies can be extended with arbitrary verbs, beyond the default Readers, Writers, Admins in configtx.yaml.

For more information on overriding policy definitions when creating a channel, check out Channel policies and Creating a channel without a system channel.

For information about how to update a channel, check out Updating a channel configuration for more information.