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

  • Cikk

A tranzakcióintegritási garanciák érvényesítése érdekében az Azure Confidential Ledger Merkle-fa adatstruktúrával rögzíti a nem módosítható tranzakciónaplóhoz 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 tranzakcióban létrehozott 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 annak igazolására szolgál, hogy a rendszer véglegesítette a megfelelő tranzakciót, és annak ellenőrzésére használható, hogy a bejegyzést ténylegesen hozzáfűzték-e a tranzakciónaplóhoz.

A Merkle-fa bizalmas tranzakciónaplókban 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 egy írási visszaigazolást a Python ügyfélkódtárával, de a lépések megegyeznek az Azure Confidential Ledger egyéb támogatott SDK-jával.

Feltételezzük, hogy egy Bizalmas tranzakciónapló-erőforrás már létre lett hozva az Azure Confidential Ledger Management kódtárának használatával. Ha még nem rendelkezik meglévő tranzakciónapló-erőforrással, hozzon létre egyet az alábbi utasításokat követve.

Kódbemutató

Először beállítjuk a Python-program importálásait.

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 Confidential Ledger-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 hitelesítéshez a DefaultAzureCredential osztályt használjuk.

# Setup authentication 
credential = DefaultAzureCredential()

Ezután lekérjük és mentjük a Confidential Ledger szolgáltatástanúsítványt a Tanúsítványügyfél használatával a Confidential Ledger Identity 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, amelyet a TLS-kiszolgáló hitelesítésének megbízhatósági gyökereként használnak. 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 tranzakciónapló URL-címét egy bizalmas tranzakciónapló-ü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 Confidential Ledger-ügyféllel bármilyen támogatott műveletet futtathatunk egy Azure Confidential Ledger-példányon. Például hozzáfűzhetünk egy új bejegyzést a tranzakciónaplóhoz, és megvárhatjuk, amíg a megfelelő írási tranzakció le lesz véglegesítve.

# 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óval megkaphatjuk a tranzakcióazonosítóval hozzáfűzött tételt.

# 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: Tartalmazza azokat az értékeket, amelyek a megfelelő írási tranzakció nyugta érvényességének ellenőrzésére használhatók.

  • state: 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 nyugta még nem kérhető le, é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.

  • cert: Sztring az írási tranzakciót aláíró CCF-csomópont PEM nyilvános kulcsú tanúsítványával. A szolgáltatásidentitás-tanúsítványnak mindig támogatnia kell az aláíró csomópont tanúsítványát. A következő hivatkozáson további részleteket is megtudhat arról, hogy a tranzakciók hogyan lesznek rendszeresen aláírva, és hogyan fűzik hozzá az aláírási tranzakciókat a CCF tranzakciónaplójához.

  • nodeId: Hexadecimális sztring, amely az aláíró CCF-csomópont nyilvános kulcsának SHA-256 kivonatát jelöli.

  • leafComponents: A Merkle-fában lévő levélcsomópont kivonatának összetevői, 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 tranzakciónapló integritását. A Merkle-fa CCF-ben való használatáról a kapcsolódó CCF-dokumentációban talál további információt.

  • proof: A Merkle-fa csomópontok kivonatait jelölő 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 korábbi szolgáltatásidentitás-tanúsítványoknak megfelelő PEM-kódolású tanúsítványsztringek listája. Lehetséges, hogy az aláíró csomópontot jóváhagyó szolgáltatásidentitás nem egyezik meg a nyugtát kiállítóval. A szolgáltatástanúsítvány például egy bizalmas tranzakciónapló vészhelyreállítása után újul meg. 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.

  • signature: 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 tranzakció végrehajtásakor a Confidential Ledger alkalmazás által csatolt alkalmazásjogcím SHA-256 kivonatát jelöli. Az alkalmazásjogcímek jelenleg nem támogatottak, mivel a Confidential Ledger 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 tranzakció 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 Key-Value tároló SHA-256 kivonatának kivonatát jelöli, amely tartalmazza a tranzakció befejezésekor írt összes kulcsot és értéket. Az írási készlettel 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 bekerül a tranzakciónaplóba, és le lesz véglegesítve az írási tranzakció részeként. A jogcím írási tranzakcióba való belefoglalása garantálja, hogy a jogcím-kivonat be van írva, és nem módosítható.

Később az alkalmazásjogcímek egyszerű formátumban is feltárhatók a nyugta hasznos adataiban, amely ugyanannak a tranzakciónak felel meg, amelyben 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ím-kivonatot, amelyet a tranzakció során a főkönyv csatolt és aláírt. A jogcímek kivonata az írási tranzakció nyugta-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 adatra, amelyet egy Azure Confidential Ledger-példány adott vissza, amely rögzítette az alkalmazásjogcímeket a GET_RECEIPT végpont meghívásakor.

{
  "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 nyugta példához képest a JSON-válasz egy másik applicationClaims mezőt tartalmaz, amely az írási tranzakció során a főkönyv által rögzített alkalmazásjogcímek listáját tartalmazza. A listában minden applicationClaims objektum a következő mezőket tartalmazza.

  • kind: A kérelem igénylésének fajtáját jelöli. Az érték azt jelzi, hogyan elemezheti az alkalmazásjogcím objektumát a megadott típushoz.

  • ledgerEntry: A tranzakciónapló-beviteli adatokból származtatott alkalmazásjogcímet jelöli. A jogcím tartalmazza az alkalmazás által az í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.

  • digest: Egy alkalmazásjogcímet jelöl kivonatolt formában. Ez a jogcímobjektum az alkalmazás által előre lefordí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.

  • contents: A tranzakciónapló tartalma, amelyet a megfelelő írási tranzakció során írtak.

  • secretKey: Egy base64 kódolású titkos kulcs. Ezt a kulcsot a HMAC-algoritmusban kell használni az alkalmazásjogcímben megadott értékekkel a jogcím-kivonat lekéréséhez.

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

  • protocol: Az adott jogcím kivonatának kiszámításához használt protokollt jelöli.

  • value: Az alkalmazásjogcím kivonata hexadecimális formában. Ezt az értéket kivonatolással kell kiegészíteni az protocol alkalmazásjogcím teljes kivonatának kiszámításához.

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:

Következő lépések