Merge pull request #222229 from andpiccione/apiccione/update-receipt-verification-docs

prmerger-automator[bot] · web-flow · commit 29b13935f4e7 · 2022-12-23T16:11:42.000Z
Update ACL receipt docs following receipt model fixes
diff --git a/articles/confidential-ledger/verify-write-transaction-receipts.md b/articles/confidential-ledger/verify-write-transaction-receipts.md
@@ -21,13 +21,13 @@ A write transaction receipt can be verified following a specific set of steps ou
 
 ### Leaf node computation
 
-The first step is to compute the SHA-256 hash of the leaf node in the Merkle Tree corresponding to the committed transaction. A leaf node is composed of the ordered concatenation of the following fields that can be found in an Azure Confidential Ledger receipt, under `leaf_components`:
+The first step is to compute the SHA-256 hash of the leaf node in the Merkle Tree corresponding to the committed transaction. A leaf node is composed of the ordered concatenation of the following fields that can be found in an Azure Confidential Ledger receipt, under `leafComponents`:
 
-1. `write_set_digest`
-2. SHA-256 digest of `commit_evidence`
-3. `claims_digest` fields
+1. `writeSetDigest`
+2. SHA-256 digest of `commitEvidence`
+3. `claimsDigest` fields
 
-These values need to be concatenated as arrays of bytes: both `write_set_digest` and `claims_digest` would need to be converted from strings of hexadecimal digits to arrays of bytes; on the other hand, the hash of `commit_evidence` (as an array of bytes) can be obtained by applying the SHA-256 hash function over the UTF-8 encoded `commit_evidence` string.
+These values need to be concatenated as arrays of bytes: both `writeSetDigest` and `claimsDigest` would need to be converted from strings of hexadecimal digits to arrays of bytes; on the other hand, the hash of `commitEvidence` (as an array of bytes) can be obtained by applying the SHA-256 hash function over the UTF-8 encoded `commitEvidence` string.
 
 Similarly, the leaf node hash digest can be computed by applying the SHA-256 hash function over the result concatenation of the resulting bytes.
 
@@ -54,7 +54,7 @@ The third step is to verify that the cryptographic signature produced over the r
 
 In addition to the above, it's also required to verify that the signing node certificate is endorsed (that is, signed) by the current ledger certificate. This step doesn't depend on the other three previous steps and can be carried out independently from the others.
 
-It's possible that the current service identity that issued the receipt is different from the one that endorsed the signing node (for example, due to a certificate renewal). In this case, it's required to verify the chain of certificates trust from the signing node certificate (that is, the `cert` field in the receipt) up to the trusted root Certificate Authority (CA) (that is, the current service identity certificate) through other previous service identities (that is, the `service_endorsements` list field in the receipt). The `service_endorsements` list is provided as an ordered list from the oldest to the latest service identity.
+It's possible that the current service identity that issued the receipt is different from the one that endorsed the signing node (for example, due to a certificate renewal). In this case, it's required to verify the chain of certificates trust from the signing node certificate (that is, the `cert` field in the receipt) up to the trusted root Certificate Authority (CA) (that is, the current service identity certificate) through other previous service identities (that is, the `serviceEndorsements` list field in the receipt). The `serviceEndorsements` list is provided as an ordered list from the oldest to the latest service identity.
 
 Certificate endorsement need to be verified for the entire chain and follows the exact same digital signature verification process outlined in the previous subsection. There are popular open-source cryptographic libraries (for example, [OpenSSL](https://www.openssl.org/)) that can be typically used to carry out a certificate endorsement step.
 
@@ -127,13 +127,11 @@ Inside the `verify_receipt` function, we check that the given receipt is valid a
 ```python
 # Check that all the fields are present in the receipt 
 assert "cert" in receipt 
-assert "is_signature_transaction" in receipt 
-assert "leaf_components" in receipt 
-assert "claims_digest" in receipt["leaf_components"] 
-assert "commit_evidence" in receipt["leaf_components"] 
-assert "write_set_digest" in receipt["leaf_components"] 
+assert "leafComponents" in receipt 
+assert "claimsDigest" in receipt["leafComponents"] 
+assert "commitEvidence" in receipt["leafComponents"] 
+assert "writeSetDigest" in receipt["leafComponents"] 
 assert "proof" in receipt 
-assert "service_endorsements" in receipt 
 assert "signature" in receipt 
 ```
 
@@ -142,22 +140,14 @@ We initialize the variables that are going to be used in the rest of the program
 ```python
 # Set the variables 
 node_cert_pem = receipt["cert"] 
-is_signature_transaction = receipt["is_signature_transaction"] 
-claims_digest_hex = receipt["leaf_components"]["claims_digest"] 
-commit_evidence_str = receipt["leaf_components"]["commit_evidence"] 
-write_set_digest_hex = receipt["leaf_components"]["write_set_digest"] 
+claims_digest_hex = receipt["leafComponents"]["claimsDigest"] 
+commit_evidence_str = receipt["leafComponents"]["commitEvidence"] 
+write_set_digest_hex = receipt["leafComponents"]["writeSetDigest"] 
 proof_list = receipt["proof"] 
-service_endorsements_certs_pem = receipt["service_endorsements"] 
+service_endorsements_certs_pem = receipt.get("serviceEndorsements", [])
 root_node_signature = receipt["signature"] 
 ```
 
-In the following snipper, we check that the receipt isn't related to a signature transaction. Receipts for signature transactions aren't allowed for Confidential Ledger.
-
-```python
-# Check that this receipt is not for a signature transaction 
-assert not is_signature_transaction 
-```
-
 We can load the PEM certificates for the service identity, the signing node, and the endorsements certificates from previous service identities using the cryptography library.
 
 ```python
@@ -181,9 +171,9 @@ leaf_node_hex = compute_leaf_node(
 )
 ```
 
-The `compute_leaf_node` function accepts as parameters the leaf components of the receipt (the `claims_digest`, the `commit_evidence`, and the `write_set_digest`) and returns the leaf node hash in hexadecimal form.
+The `compute_leaf_node` function accepts as parameters the leaf components of the receipt (the `claimsDigest`, the `commitEvidence`, and the `writeSetDigest`) and returns the leaf node hash in hexadecimal form.
 
-As detailed above, we compute the digest of `commit_evidence` (using the SHA256 `hashlib` function). Then, we convert both `write_set_digest` and `claims_digest` into arrays of bytes. Finally, we concatenate the three arrays, and we digest the result using the SHA256 function.
+As detailed above, we compute the digest of `commitEvidence` (using the SHA256 `hashlib` function). Then, we convert both `writeSetDigest` and `claimsDigest` into arrays of bytes. Finally, we concatenate the three arrays, and we digest the result using the SHA256 function.
 
 ```python
 def compute_leaf_node( 
@@ -272,7 +262,7 @@ The last step of receipt verification is validating the certificate that was use
 check_endorsements(node_cert, service_cert, service_endorsements_certs) 
 ```
 
-Likewise, we can use the CCF utility `check_endorsements` to validate that the certificate of the signing node is endorsed by the service identity. The certificate chain could be composed of previous service certificates, so we should validate that the endorsement is applied transitively if `service_endorsements` isn't an empty list.
+Likewise, we can use the CCF utility `check_endorsements` to validate that the certificate of the signing node is endorsed by the service identity. The certificate chain could be composed of previous service certificates, so we should validate that the endorsement is applied transitively if `serviceEndorsements` isn't an empty list.
 
 ```python
 def check_endorsement(endorsee: Certificate, endorser: Certificate): 
@@ -395,29 +385,23 @@ def verify_receipt(receipt: Dict[str, Any], service_cert_pem: str) -> None:
 
     # Check that all the fields are present in the receipt 
     assert "cert" in receipt 
-    assert "is_signature_transaction" in receipt 
-    assert "leaf_components" in receipt 
-    assert "claims_digest" in receipt["leaf_components"] 
-    assert "commit_evidence" in receipt["leaf_components"] 
-    assert "write_set_digest" in receipt["leaf_components"] 
+    assert "leafComponents" in receipt 
+    assert "claimsDigest" in receipt["leafComponents"] 
+    assert "commitEvidence" in receipt["leafComponents"] 
+    assert "writeSetDigest" in receipt["leafComponents"] 
     assert "proof" in receipt 
-    assert "service_endorsements" in receipt 
     assert "signature" in receipt 
 
     # Set the variables 
     node_cert_pem = receipt["cert"] 
-    is_signature_transaction = receipt["is_signature_transaction"] 
-    claims_digest_hex = receipt["leaf_components"]["claims_digest"] 
-    commit_evidence_str = receipt["leaf_components"]["commit_evidence"] 
+    claims_digest_hex = receipt["leafComponents"]["claimsDigest"] 
+    commit_evidence_str = receipt["leafComponents"]["commitEvidence"] 
 
-    write_set_digest_hex = receipt["leaf_components"]["write_set_digest"] 
+    write_set_digest_hex = receipt["leafComponents"]["writeSetDigest"] 
     proof_list = receipt["proof"] 
-    service_endorsements_certs_pem = receipt["service_endorsements"] 
+    service_endorsements_certs_pem = receipt.get("serviceEndorsements", [])
     root_node_signature = receipt["signature"] 
 
-    # Check that this receipt is not for a signature transaction 
-    assert not is_signature_transaction 
-
     # Load service and node PEM certificates
     service_cert = load_pem_x509_certificate(service_cert_pem.encode()) 
     node_cert = load_pem_x509_certificate(node_cert_pem.encode()) 
diff --git a/articles/confidential-ledger/write-transaction-receipts.md b/articles/confidential-ledger/write-transaction-receipts.md
@@ -175,13 +175,12 @@ Here's an example of a JSON response payload returned by an Azure Confidential L
 {
     "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",
-        "is_signature_transaction": false,
-        "leaf_components": {
-            "claims_digest": "0000000000000000000000000000000000000000000000000000000000000000",
-            "commit_evidence": "ce:2.40:f36ffe2930ec95d50ebaaec26e2bec56835abd051019eb270f538ab0744712a4",
-            "write_set_digest": "8452624d10bdd79c408c0f062a1917aa96711ea062c508c745469636ae1460be"
+        "leafComponents": {
+            "claimsDigest": "0000000000000000000000000000000000000000000000000000000000000000",
+            "commitEvidence": "ce:2.40:f36ffe2930ec95d50ebaaec26e2bec56835abd051019eb270f538ab0744712a4",
+            "writeSetDigest": "8452624d10bdd79c408c0f062a1917aa96711ea062c508c745469636ae1460be"
         },
-        "node_id": "70e995887e3e6b73c80bc44f9fbb6e66b9f644acaddbc9c0483cfc17d77af24f",
+        "nodeId": "70e995887e3e6b73c80bc44f9fbb6e66b9f644acaddbc9c0483cfc17d77af24f",
         "proof": [
             {
                 "left": "b78230f9abb27b9b803a9cae4e4cec647a3be1000fc2241038867792d59d4bc1"
@@ -190,7 +189,6 @@ Here's an example of a JSON response payload returned by an Azure Confidential L
                 "left": "a2835d4505b8b6b25a0c06a9c8e96a5204533ceac1edf2b3e0e4dece78fbaf35"
             }
         ],
-        "service_endorsements": [],
         "signature": "MEUCIQCjtMqk7wOtUTgqlHlCfWRqAco+38roVdUcRv7a1G6pBwIgWKpCSdBmhzgEdwguUW/Cj/Z5bAOA8YHSoLe8KzrlqK8="
     },
     "state": "Ready",
@@ -213,25 +211,23 @@ The `receipt` field contains the following fields.
 
 * **cert**: String with the [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) public key certificate of the CCF node that signed the write transaction. The certificate of the signing node should always be endorsed by the service identity certificate. See also more details about how transactions get regularly signed and how the signature transactions are appended to the ledger in CCF at the following [link](https://microsoft.github.io/CCF/main/architecture/merkle_tree.html).
 
-* **is_signature_transaction**: Boolean value indicating whether the receipt is related to a signature transaction or not. Receipts for signature transactions can't be retrieved for Confidential Ledgers.
+* **nodeId**: Hexadecimal string representing the [SHA-256](https://en.wikipedia.org/wiki/SHA-2) hash digest of the public key of the signing CCF node.
 
-* **node_id**: Hexadecimal string representing the [SHA-256](https://en.wikipedia.org/wiki/SHA-2) hash digest of the public key of the signing CCF node.
-
-* **leaf_components**: The components of the leaf node hash in the [Merkle Tree](https://en.wikipedia.org/wiki/Merkle_tree) that are associated to the specified transaction. A Merkle Tree is a tree data structure that records the hash of every transaction and guarantees the integrity of the ledger. For more information on how a Merkle Tree is used in CCF, see the related [CCF documentation](https://microsoft.github.io/CCF/main/architecture/merkle_tree.html).
+* **leafComponents**: The components of the leaf node hash in the [Merkle Tree](https://en.wikipedia.org/wiki/Merkle_tree) that are associated to the specified transaction. A Merkle Tree is a tree data structure that records the hash of every transaction and guarantees the integrity of the ledger. For more information on how a Merkle Tree is used in CCF, see the related [CCF documentation](https://microsoft.github.io/CCF/main/architecture/merkle_tree.html).
 
 * **proof**: List of key-value pairs representing the Merkle Tree nodes hashes that, when combined with the leaf node hash corresponding to the given transaction, allow the recomputation of the root hash of the tree. Thanks to the properties of a Merkle Tree, it's possible to recompute the root hash of the tree only a subset of nodes. The elements in this list are in the form of key-value pairs: keys indicate the relative position with respect to the parent node in the tree at a certain level; values are the SHA-256 hash digests of the node given, as hexadecimal strings.
 
-* **service_endorsements**: List of PEM-encoded certificates strings representing previous service identities certificates. It's possible that the service identity that endorsed the signing node isn't the same as the one that issued the receipt. For example, the service certificate is renewed after a disaster recovery of a Confidential Ledger. The list of past service certificates allows auditors to build the chain of trust from the CCF signing node to the current service certificate.
+* **serviceEndorsements**: List of PEM-encoded certificates strings representing previous service identities certificates. It's possible that the service identity that endorsed the signing node isn't the same as the one that issued the receipt. For example, the service certificate is renewed after a disaster recovery of a Confidential Ledger. The list of past service certificates allows auditors to build the chain of trust from the CCF signing node to the current service certificate.
 
 * **signature**: Base64 string representing the signature of the root of the Merkle Tree at the given transaction, by the signing CCF node.
 
-The `leaf_components` field contains the following fields.
+The `leafComponents` field contains the following fields.
 
-* **claims_digest**: Hexadecimal string representing the SHA-256 hash digest of the [application claim](https://microsoft.github.io/CCF/main/use_apps/verify_tx.html#application-claims) attached by the Confidential Ledger application at the time the transaction was executed. Application claims are currently unsupported as the Confidential Ledger application doesn't attach any claim when executing a write transaction.
+* **claimsDigest**: Hexadecimal string representing the SHA-256 hash digest of the [application claim](https://microsoft.github.io/CCF/main/use_apps/verify_tx.html#application-claims) attached by the Confidential Ledger application at the time the transaction was executed. Application claims are currently unsupported as the Confidential Ledger application doesn't attach any claim when executing a write transaction.
 
-* **commit_evidence**: A unique string produced per transaction, derived from the transaction ID and the ledger secrets. For more information about the commit evidence, see the related [CCF documentation](https://microsoft.github.io/CCF/main/use_apps/verify_tx.html#commit-evidence).
+* **commitEvidence**: A unique string produced per transaction, derived from the transaction ID and the ledger secrets. For more information about the commit evidence, see the related [CCF documentation](https://microsoft.github.io/CCF/main/use_apps/verify_tx.html#commit-evidence).
 
-* **write_set_digest**: Hexadecimal string representing the SHA-256 hash digest of the [Key-Value store](https://microsoft.github.io/CCF/main/build_apps/kv/index.html), which contains all the keys and values written at the time the transaction was completed. For more information about the write set, see the related [CCF documentation](https://microsoft.github.io/CCF/main/overview/glossary.html#term-Write-Set).
+* **writeSetDigest**: Hexadecimal string representing the SHA-256 hash digest of the [Key-Value store](https://microsoft.github.io/CCF/main/build_apps/kv/index.html), which contains all the keys and values written at the time the transaction was completed. For more information about the write set, see the related [CCF documentation](https://microsoft.github.io/CCF/main/overview/glossary.html#term-Write-Set).
 
 ### More resources
 
