Az Azure Confidential Ledger írási tranzakcióinak nyugtái

Cikk
08/07/2024

A tranzakcióintegritási garanciák érvényesítése érdekében az Azure Confidential Ledger merklefa adatstruktúrával rögzíti a nem módosítható főkönyvhöz hozzáfűzött összes tranzakcióblokk kivonatát. Az írási tranzakció véglegesítése után az Azure Confidential Ledger felhasználói titkosítási merkle-igazolást vagy nyugtát kaphatnak a bizalmas főkönyvben előállított bejegyzésen keresztül annak ellenőrzéséhez, hogy az írási művelet helyesen lett-e mentve. Az írási tranzakció visszaigazolása azt bizonyítja, hogy a rendszer véglegesítette a megfelelő tranzakciót, és annak ellenőrzésére használható, hogy a tételt ténylegesen hozzáfűzték-e a főkönyvhöz.

A Merkle-fa bizalmas főkönyvben való használatáról a CCF dokumentációjában talál további információt.

Írási tranzakció nyugtáinak lekérése

Telepítés és előfeltételek

Az Azure Confidential Ledger felhasználói az Azure Confidential Ledger ügyfélkódtárával kaphatnak visszaigazolást egy adott tranzakcióról. Az alábbi példa bemutatja, hogyan kérhet le írási visszaigazolást a Python ügyfélkódtárával, de a lépések megegyeznek az Azure Confidential Ledger bármely más támogatott SDK-jával.

Feltételezzük, hogy egy bizalmas főkönyv-erőforrás már létrejött az Azure Confidential Ledger Management könyvtár használatával. Ha még nem rendelkezik meglévő főkönyvi erőforrással, hozzon létre egyet az alábbi utasítások alapján.

Kódbemutató

Először a Python-program importálásának beállításával kezdjük.

import json 

# Import the Azure authentication library 
from azure.identity import DefaultAzureCredential 

# Import the Confidential Ledger Data Plane SDK 
from azure.confidentialledger import ConfidentialLedgerClient 
from azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient

Az alábbiakban az Azure Confidential Ledger-ügyfél beállításához használt állandó értékeket ismertetjük. Mindenképpen frissítse az állandót ledger_name a bizalmas könyvelési erőforrás egyedi nevével.

# Constants for our program 
ledger_name = "<your-unique-ledger-name>" 
identity_url = "https://identity.confidential-ledger.core.azure.com" 
ledger_url = "https://" + ledger_name + ".confidential-ledger.azure.com"

A DefaultAzureCredential osztály használatával hitelesítünk.

# Setup authentication 
credential = DefaultAzureCredential()

Ezután lekérjük és mentjük a Bizalmas főkönyv szolgáltatás tanúsítványát a Tanúsítványügyfél használatával a Bizalmas főkönyv identitás URL-címéről. A szolgáltatástanúsítvány egy hálózati identitás nyilvános kulcsú tanúsítványa, amely a TLS-kiszolgálóhitelesítés megbízhatóságának gyökerét használja. Más szóval hitelesítésszolgáltatóként (CA) használják tLS-kapcsolat létrehozásához a CCF-hálózat bármely csomópontjával.

# Create a Certificate client and use it to 
# get the service identity for our ledger 
identity_client = ConfidentialLedgerCertificateClient(identity_url) 
network_identity = identity_client.get_ledger_identity( 
     ledger_id=ledger_name 
)

# Save network certificate into a file for later use 
ledger_tls_cert_file_name = "network_certificate.pem" 

with open(ledger_tls_cert_file_name, "w") as cert_file: 
    cert_file.write(network_identity["ledgerTlsCertificate"])

Ezután használhatjuk a hitelesítő adatokat, a lekért hálózati tanúsítványt és az egyedi főkönyv URL-címét egy bizalmas főkönyv-ügyfél létrehozásához.

# Create Confidential Ledger client 
ledger_client = ConfidentialLedgerClient( 
     endpoint=ledger_url,  
     credential=credential, 
     ledger_certificate_path=ledger_tls_cert_file_name 
)

A Bizalmas főkönyv ügyfél használatával bármilyen támogatott műveletet futtathatunk egy Azure Confidential Ledger-példányon. Hozzáadhatunk például egy új tételt a főkönyvhez, és megvárhatjuk a megfelelő írási tranzakció véglegesítését.

# The method begin_create_ledger_entry returns a poller that  
# we can use to wait for the transaction to be committed 
create_entry_poller = ledger_client.begin_create_ledger_entry( 
    {"contents": "Hello World!"} 
)

create_entry_result = create_entry_poller.result()

A tranzakció véglegesítése után az ügyféllel az előző lépésben a megfelelő tranzakcióazonosító használatával megkaphatjuk a könyveléshez hozzáfűzött tételről szóló nyugtát.

# The method begin_get_receipt returns a poller that  
# we can use to wait for the receipt to be available by the system 
get_receipt_poller = ledger_client.begin_get_receipt( 
    create_entry_result["transactionId"] 
)

get_receipt_result = get_receipt_poller.result()

Mintakód

A kódbemutatóban használt teljes mintakód meg van adva.

import json 

# Import the Azure authentication library 
from azure.identity import DefaultAzureCredential 

# Import the Confidential Ledger Data Plane SDK 
from azure.confidentialledger import ConfidentialLedgerClient 
from azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient 

from receipt_verification import verify_receipt 

# Constants 
ledger_name = "<your-unique-ledger-name>" 
identity_url = "https://identity.confidential-ledger.core.azure.com" 
ledger_url = "https://" + ledger_name + ".confidential-ledger.azure.com" 

# Setup authentication 
credential = DefaultAzureCredential() 

# Create Ledger Certificate client and use it to 
# retrieve the service identity for our ledger 
identity_client = ConfidentialLedgerCertificateClient(identity_url) 
network_identity = identity_client.get_ledger_identity(ledger_id=ledger_name) 

# Save network certificate into a file for later use 
ledger_tls_cert_file_name = "network_certificate.pem" 

with open(ledger_tls_cert_file_name, "w") as cert_file: 
    cert_file.write(network_identity["ledgerTlsCertificate"]) 

# Create Confidential Ledger client 
ledger_client = ConfidentialLedgerClient( 
    endpoint=ledger_url, 
    credential=credential, 
    ledger_certificate_path=ledger_tls_cert_file_name, 
) 

# The method begin_create_ledger_entry returns a poller that 
# we can use to wait for the transaction to be committed 
create_entry_poller = ledger_client.begin_create_ledger_entry( 
    {"contents": "Hello World!"} 
) 
create_entry_result = create_entry_poller.result() 

# The method begin_get_receipt returns a poller that 
# we can use to wait for the receipt to be available by the system 
get_receipt_poller = ledger_client.begin_get_receipt( 
    create_entry_result["transactionId"] 
) 
get_receipt_result = get_receipt_poller.result() 

# Save fetched receipt into a file
with open("receipt.json", "w") as receipt_file: 
    receipt_file.write(json.dumps(get_receipt_result, sort_keys=True, indent=2))

Tranzakció visszaigazolási tartalmának írása

Íme egy példa egy JSON-válasz hasznos adatára, amelyet egy Azure Confidential Ledger-példány adott vissza a GET_RECEIPT végpont meghívásakor.

{
    "receipt": {
        "cert": "-----BEGIN CERTIFICATE-----\nMIIB0jCCAXmgAwIBAgIQPxdrEtGY+SggPHETin1XNzAKBggqhkjOPQQDAjAWMRQw\nEgYDVQQDDAtDQ0YgTmV0d29yazAeFw0yMjA3MjAxMzUzMDFaFw0yMjEwMTgxMzUz\nMDBaMBMxETAPBgNVBAMMCENDRiBOb2RlMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcD\nQgAEWy81dFeEZ79gVJnfHiPKjZ54fZvDcFlntFwJN8Wf6RZa3PaV5EzwAKHNfojj\noXT4xNkJjURBN7q+1iE/vvc+rqOBqzCBqDAJBgNVHRMEAjAAMB0GA1UdDgQWBBQS\nwl7Hx2VkkznJNkVZUbZy+TOR/jAfBgNVHSMEGDAWgBTrz538MGI/SdV8k8EiJl5z\nfl3mBTBbBgNVHREEVDBShwQK8EBegjNhcGljY2lvbmUtdGVzdC1sZWRnZXIuY29u\nZmlkZW50aWFsLWxlZGdlci5henVyZS5jb22CFWFwaWNjaW9uZS10ZXN0LWxlZGdl\ncjAKBggqhkjOPQQDAgNHADBEAiAsGawDcYcH/KzF2iK9Ldx/yABUoYSNti2Cyxum\n9RRNKAIgPB/XGh/FQS3nmZLExgBVXkDYdghQu/NCY/hHjQ9AvWg=\n-----END CERTIFICATE-----\n",
        "leafComponents": {
            "claimsDigest": "0000000000000000000000000000000000000000000000000000000000000000",
            "commitEvidence": "ce:2.40:f36ffe2930ec95d50ebaaec26e2bec56835abd051019eb270f538ab0744712a4",
            "writeSetDigest": "8452624d10bdd79c408c0f062a1917aa96711ea062c508c745469636ae1460be"
        },
        "nodeId": "70e995887e3e6b73c80bc44f9fbb6e66b9f644acaddbc9c0483cfc17d77af24f",
        "proof": [
            {
                "left": "b78230f9abb27b9b803a9cae4e4cec647a3be1000fc2241038867792d59d4bc1"
            },
            {
                "left": "a2835d4505b8b6b25a0c06a9c8e96a5204533ceac1edf2b3e0e4dece78fbaf35"
            }
        ],
        "signature": "MEUCIQCjtMqk7wOtUTgqlHlCfWRqAco+38roVdUcRv7a1G6pBwIgWKpCSdBmhzgEdwguUW/Cj/Z5bAOA8YHSoLe8KzrlqK8="
    },
    "state": "Ready",
    "transactionId": "2.40"
}

A JSON-válasz a következő mezőket tartalmazza a gyökérszinten.

nyugta: Azokat az értékeket tartalmazza, amelyek a megfelelő írási tranzakció nyugtának érvényességének ellenőrzésére használhatók.
állapot: A visszaadott JSON-válasz állapota. A lehetséges értékek a következők:
- Ready: A válaszban visszaadott nyugta elérhető
- Loading: A nyugtát még nem lehet lekérni, és a kérést újra kell próbálkozni
transactionId: Az írási tranzakció nyugtához társított tranzakcióazonosító.

A receipt mező a következő mezőket tartalmazza.

tanúsítvány: Sztring az írási tranzakciót aláíró CCF-csomópont PEM nyilvános kulcsú tanúsítványával. A szolgáltatás-identitástanúsítványnak mindig támogatnia kell az aláíró csomópont tanúsítványát. Az alábbi hivatkozáson további részleteket talál arról, hogyan lesznek rendszeresen aláírva a tranzakciók, és hogyan fűzik hozzá az aláírási tranzakciókat a ccf-ben lévő főkönyvhöz.
nodeId: Hexadecimális sztring, amely az aláíró CCF-csomópont nyilvános kulcsának SHA-256 kivonatát jelöli.
leafComponents: A levélcsomópont kivonatának összetevői a Merkle-fában , amelyek a megadott tranzakcióhoz vannak társítva. A Merkle Tree egy fa adatszerkezet, amely minden tranzakció kivonatát rögzíti, és garantálja a főkönyv integritását. A Merkle-fa CCF-ben való használatáról további információt a kapcsolódó CCF-dokumentációban talál.
proof: A Merkle Tree-csomópontok kivonatait képviselő kulcs-érték párok listája, amelyek az adott tranzakciónak megfelelő levélcsomópont kivonatával kombinálva lehetővé teszik a fa gyökérkivonatának újraszámítását. A Merkle-fa tulajdonságainak köszönhetően a fa gyökérkivonatát csak a csomópontok egy részhalmaza lehet újrafordítani. A lista elemei kulcs-érték párok formájában jelennek meg: a kulcsok jelzik a relatív pozíciót a fa szülőcsomópontja tekintetében egy bizonyos szinten; értékek a megadott csomópont SHA-256 kivonatkivonatai hexadecimális sztringekként.
serviceEndorsements: A PEM által kódolt tanúsítványsztringek listája, amelyek a korábbi szolgáltatásidentitás-tanúsítványokat jelölik. Lehetséges, hogy az aláíró csomópontot jóváhagyó szolgáltatásidentitás nem ugyanaz, mint amelyik a nyugtát kiállította. A szolgáltatástanúsítvány például megújul egy bizalmas főkönyv vészhelyreállítása után. A korábbi szolgáltatástanúsítványok listája lehetővé teszi az auditoroknak, hogy létrehozták a bizalmi láncot a CCF aláíró csomóponttól az aktuális szolgáltatástanúsítványig.
aláírás: Base64 sztring, amely a Merkle-fa gyökerének aláírását jelöli az adott tranzakcióban, az aláíró CCF-csomóponttal.

A leafComponents mező a következő mezőket tartalmazza.

claimsDigest: Hexadecimális sztring, amely a Bizalmas főkönyv alkalmazás által a tranzakció végrehajtásakor csatolt alkalmazás jogcím SHA-256 kivonatát jelöli. Az alkalmazásjogcímek jelenleg nem támogatottak, mivel a Bizalmas főkönyv alkalmazás nem csatol semmilyen jogcímet írási tranzakció végrehajtásakor.
commitEvidence: Tranzakciónként létrehozott egyedi sztring, amely a tranzakcióazonosítóból és a főkönyv titkos kulcsaiból származik. A véglegesítési bizonyítékokkal kapcsolatos további információkért tekintse meg a kapcsolódó CCF-dokumentációt.
writeSetDigest: Hexadecimális sztring, amely a Kulcs-Érték tároló SHA-256 kivonatát jelöli, amely tartalmazza a tranzakció befejezésekor írt összes kulcsot és értéket. Az írási csoporttal kapcsolatos további információkért tekintse meg a kapcsolódó CCF-dokumentációt.

Alkalmazásjogcímek

Az Azure Confidential Ledger-alkalmazások tetszőleges adatokat, úgynevezett alkalmazásjogcímeket csatolhatnak a tranzakciók írásához. Ezek a jogcímek az írási művelet során végrehajtott műveleteket jelölik. Tranzakcióhoz csatolva a jogcímobjektum SHA-256 kivonata szerepel a főkönyvben, és az írási tranzakció részeként lesz lekötött. A jogcím írási tranzakcióba való belefoglalása garantálja, hogy a jogcím-kivonat a helyén van aláírva, és nem módosítható.

Később az alkalmazásjogcímek egyszerű formátumban, ugyanazon tranzakciónak megfelelő nyugta hasznos adataiban jelennek meg, ahol hozzáadták őket. A közzétett jogcímek lehetővé teszik a felhasználók számára, hogy újrafordítják ugyanazt a jogcímkivonatot, amelyet a tranzakció során a főkönyv csatolt és aláírt. A jogcímek kivonata az írási tranzakció visszaigazolásának ellenőrzési folyamatának részeként használható, így offline módot biztosít a felhasználók számára a rögzített jogcímek hitelességének teljes ellenőrzésére.

Az alkalmazásjogcímek jelenleg az előzetes verziójú API-verzióban 2023-01-18-previewtámogatottak.

Tranzakció visszaigazolási tartalmának írása alkalmazásjogcímekkel

Íme egy példa egy JSON-válasz hasznos adatára, amelyet egy Azure Confidential Ledger-példány adott vissza, amely alkalmazásjogcímeket rögzített a GET_RECEIPT végpont hívása során.

{
  "applicationClaims": [
    {
      "kind": "LedgerEntry",
      "ledgerEntry": {
        "collectionId": "subledger:0",
        "contents": "Hello world",
        "protocol": "LedgerEntryV1",
        "secretKey": "Jde/VvaIfyrjQ/B19P+UJCBwmcrgN7sERStoyHnYO0M="
      }
    }
  ],
  "receipt": {
    "cert": "-----BEGIN CERTIFICATE-----\nMIIBxTCCAUygAwIBAgIRAMR89lUNeIghDUfpyHi3QzIwCgYIKoZIzj0EAwMwFjEU\nMBIGA1UEAwwLQ0NGIE5ldHdvcmswHhcNMjMwNDI1MTgxNDE5WhcNMjMwNzI0MTgx\nNDE4WjATMREwDwYDVQQDDAhDQ0YgTm9kZTB2MBAGByqGSM49AgEGBSuBBAAiA2IA\nBB1DiBUBr9/qapmvAIPm1o3o3LRViSOkfFVI4oPrw3SodLlousHrLz+HIe+BqHoj\n4nBjt0KAS2C0Av6Q+Xg5Po6GCu99GQSoSfajGqmjy3j3bwjsGJi5wHh1pNbPmMm/\nTqNhMF8wDAYDVR0TAQH/BAIwADAdBgNVHQ4EFgQUCPaDohOGjVgQ2Lb8Pmubg7Y5\nDJAwHwYDVR0jBBgwFoAU25KejcEmXDNnKvSLUwW/CQZIVq4wDwYDVR0RBAgwBocE\nfwAAATAKBggqhkjOPQQDAwNnADBkAjA8Ci9myzieoLoIy+7mUswVEjUG3wrEXtxA\nDRmt2PK9bTDo2m3aJ4nCQJtCWQRUlN0CMCMOsXL4NnfsSxaG5CwAVkDwLBUPv7Zy\nLfSh2oZ3Wn4FTxL0UfnJeFOz/CkDUtJI1A==\n-----END CERTIFICATE-----\n",
    "leafComponents": {
      "claimsDigest": "d08d8764437d09b2d4d07d52293cddaf40f44a3ea2176a0528819a80002df9f6",
      "commitEvidence": "ce:2.13:850a25da46643fa41392750b6ca03c7c7d117c27ae14e3322873de6322aa7cd3",
      "writeSetDigest": "6637eddb8741ab54cc8a44725be67fd9be390e605f0537e5a278703860ace035"
    },
    "nodeId": "0db9a22e9301d1167a2a81596fa234642ad24bc742451a415b8d653af056795c",
    "proof": [
      {
        "left": "bcce25aa51854bd15257cfb0c81edc568a5a5fa3b81e7106c125649db93ff599"
      },
      {
        "left": "cc82daa27e76b7525a1f37ed7379bb80f6aab99f2b36e2e06c750dd9393cd51b"
      },
      {
        "left": "c53a15cbcc97e30ce748c0f44516ac3440e3e9cc19db0852f3aa3a3d5554dfae"
      }
    ],
    "signature": "MGYCMQClZXVAFn+vflIIikwMz64YZGoH71DKnfMr3LXkQ0lhljSsvDrmtmi/oWwOsqy28PsCMQCMe4n9aXXK4R+vY0SIfRWSCCfaADD6teclFCkVNK4317ep+5ENM/5T/vDJf3V4IvI="
  },
  "state": "Ready",
  "transactionId": "2.13"
}

Az előző szakaszban bemutatott nyugtázási példához képest a JSON-válasz egy másik applicationClaims mezőt tartalmaz, amely a főkönyv által az írási tranzakció során rögzített alkalmazásjogcímek listáját jelöli. A listában szereplő applicationClaims összes objektum a következő mezőket tartalmazza.

típus: Az alkalmazás igénylésének típusa. Az érték azt jelzi, hogyan elemezheti az alkalmazás jogcímobjektumát a megadott típushoz.
ledgerEntry: A főkönyvbejegyzési adatokból származtatott alkalmazáskövetkezőt jelöl. A jogcím tartalmazza az alkalmazás által egy írási tranzakció során rögzített adatokat (például a gyűjtemény azonosítóját és a felhasználó által biztosított tartalmat), valamint az egyetlen jogcímobjektumnak megfelelő kivonat kiszámításához szükséges információkat.
kivonat: Az alkalmazásjogcímeket kivonatolt formában jeleníti meg. Ez a jogcímobjektum az alkalmazás által előre összeállított kivonatot és a számításhoz használt protokollt tartalmazza.

A ledgerEntry mező a következő mezőket tartalmazza.

protokoll: Azt a protokollt jelöli, amelyet egy jogcím kivonatának kiszámításához kell használni a megadott jogcímadatokból.
collectionId: A gyűjtemény azonosítója, amelyet a megfelelő írási tranzakció során írtak.
tartalom: A megfelelő írási tranzakció során írt főkönyv tartalma.
secretKey: Egy base64 kódolású titkos kulcs. Ezt a kulcsot a HMAC-algoritmusban kell használni az alkalmazás jogcímében megadott értékekkel a jogcím-kivonat lekéréséhez.

A digest mező a következő mezőket tartalmazza.

protokoll: Az adott jogcím kivonatának kiszámításához használt protokollt jelöli.
érték: Az alkalmazás jogcímének kivonata hexadecimális formában. Ezt az értéket az alkalmazás jogcímének teljes kivonatának kiszámításához kivonatolással protocol kell megadni.

További erőforrások

Az írási tranzakciók nyugtáiról és arról, hogy a CCF hogyan biztosítja az egyes tranzakciók integritását, tekintse meg az alábbi hivatkozásokat:

Megosztás a következőn keresztül: