[Hyperledger Fabric v1.2] 6. Architecture Reference: Private Data

해당 글은 Hyperledger Fabric 페이지의 게시글을 번역 및 정리한 자료입니다.

원본 사이트 : https://hyperledger-fabric.readthedocs.io/en/release-1.2/private-data-arch.html

이 항목에서는 Private 데이터에 대한 설명서의 개념적 내용에 대한 이해를 전제로합니다.

Private data collection definition

컬렉션 정의는 하나 이상의 컬렉션을 포함하며 컬렉션의 조직을 나열하는 정책 정의와 승인을 제어하는 데 사용되는 속성 및 선택적으로 데이터 제거 여부를 나타내는 속성을 포함합니다.

컬렉션 정의는 chaincode 인스턴스화시 채널에 배포됩니다. 피어 CLI를 사용하여 체인 코드를 인스턴스화하는 경우 콜렉션 정의 파일은 --collections-config 플래그를 사용하여 체인 코드 인스턴스로 전달됩니다. 클라이언트 SDK를 사용하는 경우 SDK 설명서에서 컬렉션 정의 제공에 대한 정보를 확인하십시오.

컬렉션 정의는 다섯 가지 속성으로 구성됩니다. :

• name : 컬렉션의 이름.
• 정책 : 서명(Signature) 정책 구문을 사용하여 표현된 수집 데이터를 유지할 수 있는 조직 피어를 정의합니다. 각 구성원은 OR 서명 정책 목록에 포함됩니다.
• requiredPeerCount : 피어가 보증에 서명하기 전에 승인하는 피어가 Private 데이터를 성공적으로 보급해야하는 피어의 최소 수를 반환하고 제안(proposal) 응답을 클라이언트에 반환합니다. requiredPeerCount가 0이면 분배가 필요 없다는 것을 의미하지만 maxPeerCount가 0보다 큰 경우 약간의 분포가 있을 수 있습니다. requiredPeerCount가 0이면 일반적으로 Private 데이터가 손실 될 수 있으므로 권장되지 않습니다. 일반적으로 네트워크의 여러 피어에서 Private 데이터의 중복성을 보장하려면 승인시 Private 데이터를 최소한 일부 배포해야합니다.
• maxPeerCount : 데이터 중복성을 위해 현재 피어 투 피어가 데이터를 배포하려고 시도하는 다른 피어의 수입니다. endorsing 피어가 승인 시간과 커밋 시간 사이에 사용할 수 없게 되는 경우, 컬렉션 멤버이지만 아직 Private 데이터를 받지 못한 다른 피어는 Private 데이터가 배포된 피어로부터 Private 데이터를 가져올 수 있습니다. 이 값을 0으로 설정하면 Private 데이터가 보증 기간(endorsement time)에 배포되지 않으므로 모든 인증된 피어에서 Private 데이터가 강제로 가져옵니다.
• blockToLive : 데이터를 블록 단위로 Private 데이터베이스에 저장하는 기간을 나타냅니다. 데이터는 Private 데이터베이스에서 이 지정된 수의 블록에 대해 살아 있고 이후에는 제거되어 네트워크에서 이 데이터를 더 이상 사용하지 않게됩니다. Private 데이터를 무기한 유지하려면 즉, Private 데이터를 절대 지우지 않으려면 blockToLive 속성을 0으로 설정합니다.

다음은 두 가지 컬렉션 정의의 배열을 포함하는 샘플 컬렉션 정의 JSON 파일입니다. :

[
 {
    "name": "collectionMarbles",
    "policy": "OR('Org1MSP.member', 'Org2MSP.member')",
    "requiredPeerCount": 0,
    "maxPeerCount": 3,
    "blockToLive":1000000
 },
 {
    "name": "collectionMarblePrivateDetails",
    "policy": "OR('Org1MSP.member')",
    "requiredPeerCount": 0,
    "maxPeerCount": 3,
    "blockToLive":3
 }
]

이 예에서는 BYFN 샘플 네트워크 Org1 및 Org2의 조직을 사용합니다. collectionMarbles 정의의 정책은 두 조직 모두가 Private 데이터에 권한을 부여합니다. 이는 체인 코드 데이터가 ordering 서비스 노드에서 비공개로 유지되어야하는 경우의 일반적인 구성입니다. 그러나 collectionMarblePrivateDetails 정의의 정책은 채널에 있는 조직의 하위 집합 (이 경우 Org1)에 대한 액세스를 제한합니다. 실제 시나리오에서는 채널에 많은 조직이 있고 각 조직의 두 개 이상의 조직이 개인 데이터를 공유합니다.

How private data is committed

인증된 피어가 자신의 임시 데이터 저장소에 Private 데이터 복사본을 가지고 있지 않으면 피어 구성 core.yaml 파일 내의 피어 속성 peer.gossip.pvtData.pullRetryThreshold를 기반으로 구성 가능한 시간 동안 다른 인증된 피어의 Private 데이터를 가져오려고 시도합니다.

요청한 피어가 정책에 정의 된대로 컬렉션의 구성원인 경우 Private 데이터를 요청하는 피어는 Private 데이터만 반환합니다.

pullRetryThreshold를 사용할 때의 고려 사항 :

• 요청(requesting) 피어가 pullRetryThreshold 내에서 Private 데이터를 검색할 수 있으면 트랜잭션(Private 데이터 해시 포함)을 원장에게 커밋하고 Private 데이터를 다른 채널 상태 데이터와 논리적으로 분리된 상태 데이터베이스에 저장합니다.
• 요청(requesting) 피어가 pullRetryThreshold 내에서 Private 데이터를 검색 할 수 없으면 Private 데이터가 없는 블록 체인(Private 데이터 해시 포함)으로 트랜잭션을 커밋합니다.
• 피어가 Private 데이터에 대한 자격이 있지만 누락된 경우 피어는 누락된 Private 데이터를 참조하는 향후 트랜잭션을 보증할 수 없으며 누락된 키에 대한 체인 코드 쿼리가 탐지되며(상태 데이터베이스에서 키의 해시가 있는지 여부를 기반으로) 체인코드는 오류가 발생합니다.

따라서 채널의 Private 데이터를 사용할 수 있을만큼 충분히 큰 requiredPeerCount 및 maxPeerCount 속성을 설정하는 것이 중요합니다. 예를 들어 트랜잭션이 커밋되기 전에 각 endorsing 피어를 사용할 수 없게 되면 requiredPeerCount 및 maxPeerCount 속성을 통해 다른 피어에서 Private 데이터를 사용할 수 있습니다.

컬렉션이 작동하려면 크로스 조직 가십(cross organizational gossip)이 올바르게 구성되어 있어야합니다. "앵커 피어(anchor peers)"섹션에 특히 주의하면서 가십 데이터 보급 프로토콜에 대한 문서를 참조하십시오.

Endorsement

endorsing 피어는 Private 데이터를 다른 인증된 피어에게 전파하여 채널에서 Private 데이터의 가용성을 보장하는 데 중요한 역할을 합니다. 이 보급을 돕기 위해 컬렉션 정의의 maxPeerCount 및 requiredPeerCount 속성이 보급 동작을 제어합니다.

endorsing 피어가 Private 데이터를 requiredPeerCount 이상으로 성공적으로 보급할 수 없으면 오류를 클라이언트에 반환합니다. endorsing 피어는 각 기관이 Private 데이터의 사본을 갖도록 하기 위해 여러 조직의 피어에게 Private 데이터를 보급하려고 시도합니다. 트랜잭션은 체인 코드 실행 시간에 커밋되지 않으므로 피어 및 피어 투 피어를 승인하는 쪽에서는 트랜잭션이 커밋될 때까지 해당 블록 체인과 함께 로컬 임시 저장소(transient store)에 Private 데이터의 복사본을 저장합니다.

Referencing collections from chaincode

일련의 shim API는 Private 데이터를 설정하고 검색하는 데 사용할 수 있습니다.

동일한 체인 코드 데이터 작업을 채널 상태 데이터 및 Private 데이터에 적용할 수 있지만 Private 데이터의 경우 컬렉션 코드 이름은 PutPrivateData(collection, key, value) 및 GetPrivateData(collection, key)와 같이 chaincode API의 데이터와 함께 지정됩니다.

단일 체인 코드는 여러 컬렉션을 참조 할 수 있습니다.

How to pass private data in a chaincode proposal

체인 코드 제안(proposal)은 블록 체인에 저장되므로 체인 코드 제안(proposal)의 주요 부분에 Private 데이터를 포함하지 않는 것이 중요합니다. transient 필드라고 하는 체인 코드 제안(proposal)의 특수 필드는 클라이언트 (또는 체인 코드가 Private 데이터를 생성하는 데 사용할 데이터)에서 Private 데이터를 전달하고 피어에서 체인 코드를 호출하는 데 사용할 수 있습니다. 체인 코드는`GetTransient() API <https://github.com/hyperledger/fabric/blob/13447bf5ead693f07285ce63a1903c5d0d25f096/core/chaincode/shim/interfaces_stable.go>`_을 호출하여 transient 필드를 검색할 수 있습니다. 이 transient 필드는 채널 트랜잭션에서 제외됩니다.

Considerations when using private data

Querying Private Data

개인용 컬렉션 데이터는 shim API를 사용하여 일반 채널 데이터와 마찬가지로 쿼리 할 수 있습니다. :

• GetPrivateDataByRange(collection, startKey, endKey string)
• GetPrivateDataByPartialCompositeKey(collection, objectType string, keys []string)

또한 CouchDB 상태 데이터베이스의 경우 shim API를 사용하여 JSON 콘텐츠 쿼리를 전달할 수 있습니다. :

• GetPrivateDataQueryResult(collection, query string)

제한 사항 :

• range 또는 rich JSON 쿼리를 실행하는 chaincode를 호출하는 클라이언트는 위의 Private Data Dissemination 섹션의 설명에 따라 쿼리한 피어가 Private 데이터가 누락된 경우 결과 집합의 하위 집합을 받을 수 있다는 것을 알고 있어야합니다. 클라이언트는 여러 피어를 쿼리하고 결과를 비교하여 피어가 결과 집합 중 일부를 누락하고 있는지 확인할 수 있습니다.
• range 또는 rich JSON 쿼리를 실행하고 단일 트랜잭션에서 데이터를 업데이트하는 체인 코드는 지원되지 않습니다. 쿼리 결과는 Private 데이터에 액세스 할 수 없는 피어 또는 해당 Private 데이터는 없지만 접근은 가능한 피어에서 유효성을 검사할 수 없기 때문입니다. 체인 코드 호출이 Private 데이터를 쿼리하고 업데이트하는 경우 제안(proposal) 요청은 오류를 반환합니다. 응용 프로그램이 체인 코드 실행과 유효성 검사 / 커밋 시간 사이의 결과 집합 변경을 허용 할 수 있는 경우 하나의 체인 코드 함수를 호출하여 쿼리를 수행한 다음 두 번째 체인 코드 함수를 호출하여 업데이트를 수행할 수 있습니다. 모든 피어는 해시된 키 버전을 기반으로 키 읽기를 확인할 수 있기 때문에 GetPrivateData()에 대한 호출이 PutPrivateData() 호출과 동일한 트랜잭션에서 수행 될 수 있습니다.
• Private 데이터 수집은 Private 데이터를 수신하고 저장할 권한이 있는 피어의 조직만을 정의하므로 결과적으로 Private 데이터를 쿼리하는 데 사용할 수있는 피어를 의미합니다. Private 데이터 수집은 자체적으로 체인 코드 내에서 액세스 제어를 제한하지 않습니다. 예를 들어 권한이 없는 클라이언트가 Private 데이터에 액세스 할 수 있는 피어에서 체인 코드를 호출할 수 있는 경우 체인 코드 논리는 평소처럼 액세스 제어를 수행하는 수단이 필요합니다. 예를 들어 GetCreator() 체인 코드 API를 호출하거나 클라이언트 ID 체인 코드 라이브러리를 사용합니다.

Using Indexes with collections

상태 데이터베이스인 CouchDB 항목은 chaincode 설치시 META-INF/statedb/couchdb/indexes 디렉토리의 인덱스를 패키징하여 채널의 상태 데이터베이스에 적용 할 수 있는 인덱스를 설명합니다. 마찬가지로 META-INF/statedb/couchdb/collections/<collection_name>/indexes 디렉토리에 인덱스를 패키징하여 Private 데이터 수집에 인덱스를 적용할 수도 있습니다. 여기에 인덱스 예제가 있습니다.

Private Data Purging

Private 데이터를 무기한 유지하려면 즉, Private 데이터를 절대 지우지 않으려면 blockToLive 속성을 0으로 설정합니다.

커밋하기 전에 피어는 Private 데이터를 로컬 임시(transient) 데이터 저장소에 저장합니다. 이 데이터는 트랜잭션이 커밋 될 때 자동으로 제거됩니다. 그러나 트랜잭션이 채널에 제출되지 않아 커밋된 적이 없는 경우 Private 데이터는 각 피어의 임시(transient) 저장소에 남아 있습니다. 이 데이터는 피어 core.yaml 파일에서 피어의 peer.gossip.pvtData.transientstoreMaxBlockRetention 속성을 사용하여 구성 가능한 숫자 블록 후에 임시(transient) 저장소에서 제거됩니다.

Upgrading a collection definition

체인 코드에 의해 컬렉션이 참조되는 경우, 체인 코드는 업그레이드시 새 컬렉션 정의가 지정되지 않으면 이전 컬렉션 정의를 사용합니다. 업그레이드 중에 컬렉션 구성을 지정하면 기존 컬렉션 각각에 대한 정의가 포함되어야하며 새 컬렉션 정의를 추가 할 수 있습니다.

체인 업데이트는 체인이 체인 코드 업그레이드 트랜잭션을 포함하는 블록을 커밋 할 때 효과적입니다. 제거 할 수없는 채널의 블록 체인에 이전 Private 데이터 해시가있을 수 있으므로 컬렉션을 삭제할 수 없습니다.