[Confidential Ledger] [Data Plane] Make application claims parameter keyword-only in verify_receipt (Azure#30231)

* Make application claims keyword only argument for verify_receipt

* Update tests after SDK change

* Update samples

* Update README

* Update changelog

* Update docstring

* Address review comments

Author: andpiccione

sdk/confidentialledger/azure-confidentialledger/CHANGELOG.md

@@ -4,10 +4,10 @@
 
 ### Features Added
 - Add `azure.confidentialledger.receipt` module for Azure Confidential Ledger write transaction receipt verification.
-- Add `verify_receipt` function to verify write transaction receipts from a receipt JSON object. The function accepts an optional list of application claims, which can be used to compute the claims digest. The computed claims digest is then compared to the `claimsDigest` value present in the receipt.
+- Add `verify_receipt` function to verify write transaction receipts from a receipt JSON object. The function accepts an optional, keyword-only, list of application claims parameter, which can be used to compute the claims digest from the given claims: the verification would fail if the computed digest value does not match the `claimsDigest` value present in the receipt.
 - Add `compute_claims_digest` function to compute the claims digest from a list of application claims JSON objects. 
 - Add sample code to get and verify a write receipt from a running Confidential Ledger instance.
-- Update README with examples and documentation for receipt verification.
+- Update README with examples and documentation for receipt verification and application claims.
 
 ### Other Changes
 - Add dependency on Python `cryptography` library (`>= 2.1.4`)

sdk/confidentialledger/azure-confidentialledger/README.md

@@ -112,6 +112,11 @@ Azure Confidential Ledger applications can attach arbitrary data, called applica
 
 Later, application claims can be revealed in their un-digested form in the receipt payload corresponding to the same transaction where they were added. This allows users to leverage the information in the receipt to re-compute the same claims digest that was attached and signed in place by the Azure Confidential Ledger instance during the transaction. The claims digest can be used as part of the write transaction receipt verification process, providing an offline way for users to fully verify the authenticity of the recorded claims.
 
+More details on the application claims format and the digest computation algorithm can be found at the following links:
+
+- [Azure Confidential Ledger application claims](https://learn.microsoft.com/azure/confidential-ledger/write-transaction-receipts#application-claims)
+- [Azure Confidential Ledger application claims digest verification](https://learn.microsoft.com/azure/confidential-ledger/verify-write-transaction-receipts#verify-application-claims-digest)
+
 Please refer to the following CCF documentation pages for more information about CCF Application claims:
 
 - [Application Claims](https://microsoft.github.io/CCF/main/use_apps/verify_tx.html#application-claims)
@@ -437,7 +442,7 @@ application_claims = get_receipt_result.get("applicationClaims", None)
 
 try:
     # Verify the contents of the receipt.
-    verify_receipt(get_receipt_result["receipt"], service_cert_content, application_claims)
+    verify_receipt(get_receipt_result["receipt"], service_cert_content, application_claims=application_claims)
     print(f"Receipt for transaction id {transaction_id} successfully verified")
 except ValueError:
     print(f"Receipt verification for transaction id {transaction_id} failed")

sdk/confidentialledger/azure-confidentialledger/azure/confidentialledger/receipt/_receipt_verification.py

@@ -32,6 +32,7 @@
 def verify_receipt(
     receipt: Dict[str, Any],
     service_cert: str,
+    *,
     application_claims: Optional[List[Dict[str, Any]]] = None,
 ) -> None:
     """Verify that a given Azure Confidential Ledger write transaction receipt
@@ -46,8 +47,8 @@ def verify_receipt(
      certificate of the Confidential Ledger service identity.
     :type service_cert: str
 
-    :param application_claims: List of application claims to be verified against the receipt.
-    :type application_claims: Optional[List[Dict[str, Any]]], optional
+    :keyword application_claims: List of application claims to be verified against the receipt.
+    :paramtype application_claims: Optional[List[Dict[str, Any]]]
 
     :raises ValueError: If the receipt verification has failed.
     """

sdk/confidentialledger/azure-confidentialledger/samples/get_and_verify_receipt.py

@@ -124,11 +124,15 @@ def main():
             service_cert_content = service_cert_file.read()
 
         # Optionally read application claims, if any
-        application_claims = get_receipt_result.get("applicationClaims", None) 
+        application_claims = get_receipt_result.get("applicationClaims", None)
 
         try:
             # Verify the contents of the receipt.
-            verify_receipt(get_receipt_result["receipt"], service_cert_content, application_claims)
+            verify_receipt(
+                get_receipt_result["receipt"],
+                service_cert_content,
+                application_claims=application_claims,
+            )
             print(f"Receipt for transaction id {transaction_id} successfully verified")
         except ValueError:
             print(f"Receipt verification for transaction id {transaction_id} failed")

sdk/confidentialledger/azure-confidentialledger/tests/receipt/test_receipt_verification.py

@@ -362,7 +362,9 @@ def test_receipt_verification_with_valid_application_claims_returns_successfully
     # Check that verify_receipt does not throw any exception
     # with a valid receipt, service certificate, and application claims
     try:
-        verify_receipt(input_receipt, input_service_cert, input_claims)
+        verify_receipt(
+            input_receipt, input_service_cert, application_claims=input_claims
+        )
     except Exception as e:
         pytest.fail(
             f"verify_receipt threw an exception with a valid receipt, service certificate, and application claims {e}"
@@ -391,4 +393,6 @@ def test_receipt_verification_with_invalid_application_claims_throws_exception(
     with pytest.raises(
         ValueError,
     ):
-        verify_receipt(input_receipt, input_service_cert, input_claims)
+        verify_receipt(
+            input_receipt, input_service_cert, application_claims=input_claims
+        )