[Hyperledger Fabric v2.0] Policies

Policies in Hyperledger Fabric

Hyperledger Fabric 블록체 네트워크 policies 에 따라 운영

이 policy 들은 일반적으로 channel configuration 에 위치함

본 문서의 목적;

• policy 들이 channel configuration 에 어떻게 정의 되는가
• policy 들이 channel configuration 과 어떻게 상호 작용을 하는가

c.f.) policy 들은 chaincode 와 같은 곳에 위치 할 수도 있음, 이는 channel configuration 과는 연관이 없음

What is a Policy?

policy 에 대한 가장 기본적인 설명은 다음과 같을 수 있음;

• policy 는 function 이다; 서명된 데이터를 입력으로 받고 성공적으로 검증 후에 polic 만족 여부에 대한 에러를 출력

policy 에 대한 상세한 설명은 다음과 같을 수 있음;

• policy 는 서명자 혹은 데이터의 서명 값이 특정 조건을 만족하여 해당 서명이 'valid' 한지 테스트
• 이를 통해 특정 트랜잭션에 대해 올바른 party 들이 동의를 했는지 결정하는데 활용

policy 는 예를 들어 다음과 같이 정의 될 수 있음

• 5개의 서로 다른 organization 에서 2곳 이상이 필수로 서명을 해야 함
• 특정 organization 의 특정 member 가 필수로 서명을 해야 함
• 두 개의 특정 인증서로 필수로 서명을 해야 함

Policy Types

policy 에는 다음과 같이 두 종류로 구성 될 수 있음;

1. SignaturePolicy
   • 가장 강력한 policy
   • MSP Principals 에 따른 검증 조합으로 policy 정의
   • AND, OR, NOutOf 의 조합을 통해 규칙을 정할 수 있음
   • 예를 들어; orgA admin AND 다른 2 admins, OR 20 org admin 들 중에서 11개의 org admin
2. ImplicitMetaPolicy
   • SignaturePolicy 만큼 유연하지 않음
   • configuration 에 따른 유효성만을 확인
   • configuration 계층 말단에서 SignaturePolicy 들에 정의된 내용에 따라 policies 검증 결과를 추합
   • 다음과 같은 규칙이 있을 수 있음; 과반수의 org policy 를 만족 해야 함

policy 들은 fabric-protos/common/policies.proto 에 정의된 common.Policy 메시지에 인코딩 됨

해당 메시지는 다음과 같음;

 

message Policy {
    enum PolicyType {
        UNKNOWN = 0; // Reserved to check for proper initialization
        SIGNATURE = 1;
        MSP = 2;
        IMPLICIT_META = 3;
    }
    int32 type = 1; // For outside implementors, consider the first 1000 types reserved, otherwise one of PolicyType
    bytes policy = 2;
}

policy 를 인코딩 하기 위해서;

• type 필드에 SIGNATURE 혹은 IMPLICIT_META 중에 선택하여 입력
• policy 필드에 대응되는 policy proto 실행 내용을 마샬링 함

Configuration and Policies

The channel configuration is expressed as a hierarchy of configuration groups, each of which has a set of values and policies associated with them. For a validly configured application channel with two application organizations and one ordering organization, the configuration looks minimally as follows:

Channel:
    Policies:
        Readers
        Writers
        Admins
    Groups:
        Orderer:
            Policies:
                Readers
                Writers
                Admins
            Groups:
                OrdereringOrganization1:
                    Policies:
                        Readers
                        Writers
                        Admins
        Application:
            Policies:
                Readers
----------->    Writers
                Admins
            Groups:
                ApplicationOrganization1:
                    Policies:
                        Readers
                        Writers
                        Admins
                ApplicationOrganization2:
                    Policies:
                        Readers
                        Writers
                        Admins

Consider the Writers policy referred to with the -------> mark in the above example. This policy may be referred to by the shorthand notation /Channel/Application/Writers. Note that the elements resembling directory components are group names, while the last component resembling a file basename is the policy name.

Different components of the system will refer to these policy names. For instance, to call Deliver on the orderer, the signature on the request must satisfy the /Channel/Readers policy. However, to gossip a block to a peer will require that the /Channel/Application/Readers policy be satisfied.

By setting these different policies, the system can be configured with rich access controls.

Constructing a SignaturePolicy

SignaturePolicy 는 protobuf 방식으로 다음과 같이 표현 됨;

message SignaturePolicyEnvelope {
    int32 version = 1;
    SignaturePolicy policy = 2;
    repeated MSPPrincipal identities = 3;
}

message SignaturePolicy {
    message NOutOf {
        int32 N = 1;
        repeated SignaturePolicy policies = 2;
    }
    oneof Type {
        int32 signed_by = 1;
        NOutOf n_out_of = 2;
    }
}

message MSPPrincipal {

    enum Classification {
        ROLE = 0;
        ORGANIZATION_UNIT = 1;
        IDENTITY  = 2;
    }

    Classification principal_classification = 1;

    bytes principal = 2;
}

protobuf 에서 외부와 통신을 위한 SignaturePolicyEnvelope 에는 다음과 같은 내용이 정의됨;

• version : 버전 (현재는 0 만 지원함)
• policy : identities 와 인덱싱 되어 관련된 policy 규칙
• identities : MSPPricipal 로 표현되는 identities

SignaturePolicy 는 재귀적인 데이터 구조

• 이를 통해 MSPPrincipal 혹은 SignaturePolicy 들의 모음에서 단일 서명에 대해 전체 중 N 인원이 만족 되어야 한다는 요구사항을 표현

예를 들면 다음과 같음;

SignaturePolicyEnvelope{
    version: 0,
    policy: SignaturePolicy{
        n_out_of: NOutOf{
            N: 2,
            policies: [
                SignaturePolicy{ signed_by: 0 },
                SignaturePolicy{ signed_by: 1 },
            ],
        },
    },
    identities: [mspP1, mspP2],
}

위 내용은 다음을 표현;

• SignaturePolicy 에는 mspP1 과 mspP2 가 참여
• mspP1 과 mspP2 모두에 대해 서명이 만족 되어야 하는 필수조건

좀더 복잡한 예제는 다음과 같음;

SignaturePolicyEnvelope{
    version: 0,
    policy: SignaturePolicy{
        n_out_of: NOutOf{
            N: 2,
            policies: [
                SignaturePolicy{ signed_by: 0 },
                SignaturePolicy{
                    n_out_of: NOutOf{
                        N: 1,
                        policies: [
                            SignaturePolicy{ signed_by: 1 },
                            SignaturePolicy{ signed_by: 2 },
                        ],
                    },
                },
            ],
        },
    },
    identities: [mspP1, mspP2, mspP3],
}

위 내용은 다음을 표현;

• SignaturePolicy 에는 mspP1 , mspP2, mspP3 가 참여
• mspP1 의 서명은 필수로 만족
• mspP2 와 mspP3 중 하나의 서명은 필수로 만족

코드로서 signature policy 를 구성할 때는 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

The MSP Principal is a generalized notion of cryptographic identity. Although the MSP framework is designed to work with types of cryptography other than X.509, for the purposes of this document, the discussion will assume that the underlying MSP implementation is the default MSP type, based on X.509 cryptography.

An MSP Principal is defined in fabric-protos/msp_principal.proto as follows:

message MSPPrincipal {

    enum Classification {
        ROLE = 0;
        ORGANIZATION_UNIT = 1;
        IDENTITY  = 2;
    }

    Classification principal_classification = 1;

    bytes principal = 2;
}

The principal_classification must be set to either ROLE or IDENTITY. The ORGANIZATIONAL_UNIT is at the time of this writing not implemented.

In the case of IDENTITY the principal field is set to the bytes of a certificate literal.

However, more commonly the ROLE type is used, as it allows the principal to match many different certs issued by the MSP’s certificate authority.

In the case of ROLE, the principal is a marshaled MSPRole message defined as follows:

message MSPRole {
    string msp_identifier = 1;

    enum MSPRoleType {
        MEMBER = 0; // Represents an MSP Member
        ADMIN  = 1; // Represents an MSP Admin
        CLIENT = 2; // Represents an MSP Client
        PEER = 3; // Represents an MSP Peer
    }

    MSPRoleType role = 2;
}

The msp_identifier is set to the ID of the MSP (as defined by the MSPConfig proto in the channel configuration for an org) which will evaluate the signature, and the Role is set to either MEMBER, ADMIN, CLIENT or PEER. In particular:

1. MEMBER matches any certificate issued by the MSP.
2. ADMIN matches certificates enumerated as admin in the MSP definition.
3. CLIENT (PEER) matches certificates that carry the client (peer) Organizational unit.

(see MSP Documentation)

Constructing an ImplicitMetaPolicy

The ImplicitMetaPolicy is only validly defined in the context of channel configuration. It is Implicit because it is constructed implicitly based on the current configuration, and it is Meta because its evaluation is not against MSP principals, but rather against other policies. It is defined in fabric-protos/common/policies.proto as follows:

message ImplicitMetaPolicy {
    enum Rule {
        ANY = 0;      // Requires any of the sub-policies be satisfied, if no sub-policies exist, always returns true
        ALL = 1;      // Requires all of the sub-policies be satisfied
        MAJORITY = 2; // Requires a strict majority (greater than half) of the sub-policies be satisfied
    }
    string sub_policy = 1;
    Rule rule = 2;
}

For example, consider a policy defined at /Channel/Readers as

ImplicitMetaPolicy{
    rule: ANY,
    sub_policy: "foo",
}

This policy will implicitly select the sub-groups of /Channel, in this case, Application and Orderer, and retrieve the policy of name foo, to give the policies /Channel/Application/foo and /Channel/Orderer/foo. Then, when the policy is evaluated, it will check to see if ANY of those two policies evaluate without error. Had the rule been ALL it would require both.

Consider another policy defined at /Channel/Application/Writers where there are 3 application orgs defined, OrgA, OrgB, and OrgC.

ImplicitMetaPolicy{
    rule: MAJORITY,
    sub_policy: "bar",
}

In this case, the policies collected would be /Channel/Application/OrgA/bar, /Channel/Application/OrgB/bar, and /Channel/Application/OrgC/bar. Because the rule requires a MAJORITY, this policy will require that 2 of the three organization’s bar policies are satisfied.

Policy Defaults

The configtxgen tool uses policies which must be specified explicitly in configtx.yaml.

Note that policies higher in the hierarchy are all defined as ImplicitMetaPolicys while leaf nodes necessarily are defined as SignaturePolicys. This set of defaults works nicely because the ImplicitMetaPolicies do not need to be redefined as the number of organizations change, and the individual organizations may pick their own rules and thresholds for what is means to be a Reader, Writer, and Admin.