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