github.com/kchristidis/fabric@v1.0.4-0.20171028114726-837acd08cde1/docs/source/endorsement-policies.rst (about) 1 Endorsement policies 2 ==================== 3 4 Endorsement policies are used to instruct a peer on how to decide 5 whether a transaction is properly endorsed. When a peer receives a 6 transaction, it invokes the VSCC (Validation System Chaincode) 7 associated with the transaction's Chaincode as part of the transaction 8 validation flow to determine the validity of the transaction. Recall 9 that a transaction contains one or more endorsement from as many 10 endorsing peers. VSCC is tasked to make the following determinations: - 11 all endorsements are valid (i.e. they are valid signatures from valid 12 certificates over the expected message) - there is an appropriate number 13 of endorsements - endorsements come from the expected source(s) 14 15 Endorsement policies are a way of specifying the second and third 16 points. 17 18 Endorsement policy design 19 ------------------------- 20 21 Endorsement policies have two main components: - a principal - a 22 threshold gate 23 24 A principal ``P`` identifies the entity whose signature is expected. 25 26 A threshold gate ``T`` takes two inputs: an integer ``t`` (the 27 threshold) and a list of ``n`` principals or gates; this gate 28 essentially captures the expectation that out of those ``n`` principals 29 or gates, ``t`` are requested to be satisfied. 30 31 For example: - ``T(2, 'A', 'B', 'C')`` requests a signature from any 2 32 principals out of 'A', 'B' or 'C'; - ``T(1, 'A', T(2, 'B', 'C'))`` 33 requests either one signature from principal ``A`` or 1 signature from 34 ``B`` and ``C`` each. 35 36 Endorsement policy syntax in the CLI 37 ------------------------------------ 38 39 In the CLI, a simple language is used to express policies in terms of 40 boolean expressions over principals. 41 42 A principal is described in terms of the MSP that is tasked to validate 43 the identity of the signer and of the role that the signer has within 44 that MSP. Currently, two roles are supported: **member** and **admin**. 45 Principals are described as ``MSP``.\ ``ROLE``, where ``MSP`` is the MSP 46 ID that is required, and ``ROLE`` is either one of the two strings 47 ``member`` and ``admin``. Examples of valid principals are 48 ``'Org0.admin'`` (any administrator of the ``Org0`` MSP) or 49 ``'Org1.member'`` (any member of the ``Org1`` MSP). 50 51 The syntax of the language is: 52 53 ``EXPR(E[, E...])`` 54 55 where ``EXPR`` is either ``AND`` or ``OR``, representing the two boolean 56 expressions and ``E`` is either a principal (with the syntax described 57 above) or another nested call to ``EXPR``. 58 59 For example: - ``AND('Org1.member', 'Org2.member', 'Org3.member')`` 60 requests 1 signature from each of the three principals - 61 ``OR('Org1.member', 'Org2.member')`` requests 1 signature from either 62 one of the two principals - 63 ``OR('Org1.member', AND('Org2.member', 'Org3.member'))`` requests either 64 one signature from a member of the ``Org1`` MSP or 1 signature from a 65 member of the ``Org2`` MSP and 1 signature from a member of the ``Org3`` 66 MSP. 67 68 Specifying endorsement policies for a chaincode 69 ----------------------------------------------- 70 71 Using this language, a chaincode deployer can request that the 72 endorsements for a chaincode be validated against the specified policy. 73 NOTE - the default policy requires one signature from a member of the 74 ``DEFAULT`` MSP). This is used if a policy is not specified in the CLI. 75 76 The policy can be specified at deploy time using the ``-P`` switch, 77 followed by the policy. 78 79 For example: 80 81 :: 82 83 peer chaincode deploy -C testchainid -n mycc -p github.com/hyperledger/fabric/examples/chaincode/go/chaincode_example02 -c '{"Args":["init","a","100","b","200"]}' -P "AND('Org1.member', 'Org2.member')" 84 85 This command deploys chaincode ``mycc`` on chain ``testchainid`` with 86 the policy ``AND('Org1.member', 'Org2.member')``. 87 88 Future enhancements 89 ------------------- 90 91 In this section we list future enhancements for endorsement policies: - 92 alongside the existing way of identifying principals by their 93 relationship with an MSP, we plan to identify principals in terms of the 94 *Organization Unit (OU)* expected in their certificates; this is useful 95 to express policies where we request signatures from any identity 96 displaying a valid certificate with an OU matching the one requested in 97 the definition of the principal. - instead of the syntax ``AND(., .)`` 98 we plan to move to a more intuitive syntax ``. AND .`` - we plan to 99 expose generalized threshold gates in the language as well alongside 100 ``AND`` (which is the special ``n``-out-of-``n`` gate) and ``OR`` (which 101 is the special ``1``-out-of-``n`` gate) 102 103 .. Licensed under Creative Commons Attribution 4.0 International License 104 https://creativecommons.org/licenses/by/4.0/ 105