[FAB-4749] Document signature policy limitations

The signature policy evaluation consumes signatures in the order they
are specified.  This can lead to unintuitive policy evaluation with
signature sets that appear to satisfy a policy, but do not.

This CR documents the limitation as well as a best practice to avoid
encountering the unintuitive evaluation.

[skip ci]

Change-Id: I31c5b21b92f562f98e1290fa635787d479fbcbf1
Signed-off-by: Jason Yellick <[email protected]>

Author: Jason Yellick

docs/source/policies.rst

@@ -221,6 +221,42 @@ may be expressed using the SignaturePolicy policy type. For code which
 constructs signature policies, consult
 ``fabric/common/cauthdsl/cauthdsl_builder.go``.
 
+---------
+
+**Limitations**: When evaluating a signature policy against a signature set,
+signatures are 'consumed', in the order in which they appear, regardless of
+whether they satisfy multiple policy principals.
+
+For example.  Consider a policy which requires
+
+::
+
+ 2 of [org1.Member, org1.Admin]
+
+The naive intent of this policy is to require that both an admin, and a member
+sign. For the signature set
+
+::
+
+ [org1.MemberSignature, org1.AdminSignature]
+
+the policy evaluates to true, just as expected.  However, consider the
+signature set
+
+::
+
+ [org1.AdminSignature, org1.MemberSignature]
+
+This signature set does not satisfy the policy.  This failure is because when
+``org1.AdminSignature`` satisfies the ``org1.Member`` role it is considered
+'consumed' by the ``org1.Member`` requirement.  Because the ``org1.Admin``
+principal cannot be satisfied by the ``org1.MemberSignature``, the policy
+evaluates to false.
+
+To avoid this pitfall, identities should be specified from most privileged to
+least privileged in the policy identities specification, and signatures should
+be ordered from least privileged to most privileged in the signature set.
+
 MSP Principals
 --------------