Fabric Chaincode Endorsement Policies Simplified

Endorsement Policies in Hyperledger Fabric work as an instruction for endorsing peers to validate whether a transaction is properly endorsed or not. In Hyperledger Fabric there is a VSCC (Valid System Chaincode) invoked with every chaincode's transaction on each peer after it receives a transaction proposal, and what it does is, it compares the endorsement signatures with which transaction is signed off as a transaction contains one or more endorsements from many endorsing peers. VSCC determines:

1. All transactions endorsements are valid (i.e. they contain valid signatures for valid certificates from authorized source) .
2. The number of transaction endorsements matches the requirement of endorsements declared in the endorsement policy.
3. Endorsement is from an authorized expected source.

Roles allowed in the endorsement policy to be checked by VSCC:
i. peer
ii. client
iii. member
iv. admin

[NOTE: These roles must only be defined as strings at the setEnrollment api after the registeration of the user on the blockchain through the CA following any SDK implementation.]

VSCC checks the role of the signing identity against the endorsement policy defined, this role must be one of the above four roles for succeeding the approval of endorsement policies, otherwise the ENDORSEMENT_POLICY_FAILURE Error will be thrown at the endorsing peer where the signature set does not satisfy the endorsement policy or the no. Of signatures required by the policy cannot be collected.

Lets understand the forrmat of the endorsement policy to be defined for the Node SDK based client for communicating with the Blockchain.

Sample Policy 1:
 

{
  "identities": [
    { "role": { "name": "member", "mspId": "Org1MSP" }},
    { "role": { "name": "member", "mspId": "Org2MSP" }}
  ],
  "policy": {
    "1-of": [{ "signed-by": 0 }, { "signed-by": 1 }]
  }
}

Sample Policy 2:
 

{
  "identities": [
    { "role": { "name": "member", "mspId": "Org1MSP" }},
    { "role": { "name": "member", "mspId": "Org2MSP" }},
    { "role": { "name": "admin", "mspId": "Org1MSP" }}
  ],
  "policy": {
    "2-of": [
      { "signed-by": 2},
      { "1-of": [{ "signed-by": 0 }, { "signed-by": 1 }]}
    ]
  }
}

There are two parts of the endorsement plicy in each of the sample policies:
1. Identities: its an array of the registerd blockhain identities checked for their roles and the MSP they belong to.
2. policy: an object containing the nOf format policies which is a “Signature Set Policy” whre the n is the number of mminimum signatures required out of the specifeid signature of identites. One can create as complex of the Signature policy as he/she desire.
The sample policy 1 has two identities from Org1MSP and Org2 MSP respectively. And the SignatureSet Policy says:
 

"policy": {
    "1-of": [{ "signed-by": 0 }, { "signed-by": 1 }]
  }

Either it should signed by 0 (with role member) which the identity 1 in the identities aray (identity Org1MSP) or signed by 1 (with role member) which the identity 2 in the identities aray (identity Org2MSP). Thus this policy will succeed if a transaction is being signed by a member of any org Org1MSP of Org2MSP. Similarly the Sample Policy 2 dictates, a transaction against this policy will only be succeeded if it is signed by i. Admin of the OrdererMSP ii. Member of any of the organizations either Org1MSP or Org2MSP.