# Azure Confidential Ledger client library for Python
Azure Confidential Ledger provides a service for logging to an immutable, tamper-proof ledger. As part of the [Azure Confidential Computing][azure_confidential_computing] portfolio, Azure Confidential Ledger runs in secure, hardware-based trusted execution environments, also known as enclaves. It is built on Microsoft Research's [Confidential Consortium Framework][ccf].
[Source code][confidential_ledger_client_src]
| [Package (PyPI)][pypi_package_confidential_ledger]
| [Package (Conda)](https://anaconda.org/microsoft/azure-confidentialledger/)
| [API reference documentation][reference_docs]
| [Product documentation][confidential_ledger_docs]
## Getting started
### Install packages
Install [azure-confidentialledger][pypi_package_confidential_ledger] and [azure-identity][azure_identity_pypi] with [pip][pip]:
```Bash
pip install azure-identity azure-confidentialledger
```
[azure-identity][azure_identity] is used for Azure Active Directory
authentication as demonstrated below.
### Prerequisites
* An [Azure subscription][azure_sub]
* Python 3.6 or later
* A running instance of Azure Confidential Ledger.
* A registered user in the Confidential Ledger, typically assigned during [ARM][azure_resource_manager] resource creation, with `Administrator` privileges.
### Authenticate the client
#### Using Azure Active Directory
This document demonstrates using [DefaultAzureCredential][default_cred_ref] to authenticate to the Confidential Ledger via Azure Active Directory. However, `ConfidentialLedgerClient` accepts any [azure-identity][azure_identity] credential. See the [azure-identity][azure_identity] documentation for more information about other credentials.
#### Using a client certificate
As an alternative to Azure Active Directory, clients may choose to use a client certificate to authenticate via mutual TLS. `azure.confidentialledger.ConfidentialLedgerCertificateCredential` may be used for this purpose.
### Create a client
`DefaultAzureCredential` will automatically handle most Azure SDK client scenarios. To get started, set environment variables for the AAD identity registered with your Confidential Ledger.
```bash
export AZURE_CLIENT_ID="generated app id"
export AZURE_CLIENT_SECRET="random password"
export AZURE_TENANT_ID="tenant id"
```
Then, `DefaultAzureCredential` will be able to authenticate the `ConfidentialLedgerClient`.
Constructing the client also requires your Confidential Ledger's URL and id, which you can get from the Azure CLI or the Azure Portal. When you have retrieved those values, please replace instances of `"my-ledger-id"` and `"https://my-ledger-id.confidential-ledger.azure.com"` in the examples below. You may also need to replace `"https://identity.confidential-ledger.core.azure.com"` with the hostname from the `identityServiceUri` in the ARM description of your ledger.
Because Confidential Ledgers use self-signed certificates securely generated and stored in an enclave, the signing certificate for each Confidential Ledger must first be retrieved from the Confidential Ledger Identity Service.
```python
from azure.confidentialledger import ConfidentialLedgerClient
from azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient
from azure.identity import DefaultAzureCredential
identity_client = ConfidentialLedgerCertificateClient()
network_identity = identity_client.get_ledger_identity(
ledger_id="my-ledger-id"
)
ledger_tls_cert_file_name = "ledger_certificate.pem"
with open(ledger_tls_cert_file_name, "w") as cert_file:
cert_file.write(network_identity["ledgerTlsCertificate"])
credential = DefaultAzureCredential()
ledger_client = ConfidentialLedgerClient(
endpoint="https://my-ledger-id.confidential-ledger.azure.com",
credential=credential,
ledger_certificate_path=ledger_tls_cert_file_name
)
```
Conveniently, the `ConfidentialLedgerClient` constructor will fetch the ledger TLS certificate (and write it to the specified file) if it is provided with a non-existent file. The user is responsible for removing the created file as needed.
```python
from azure.confidentialledger import ConfidentialLedgerClient
from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()
ledger_client = ConfidentialLedgerClient(
endpoint="https://my-ledger-id.confidential-ledger.azure.com",
credential=credential,
ledger_certificate_path="ledger_certificate.pem"
)
# The ledger TLS certificate is written to `ledger_certificate.pem`.
```
To make it clear that a file is being used for the ledger TLS certificate, subsequent examples will explicitly write the ledger TLS certificate to a file.
## Key concepts
### Ledger entries and transactions
Every write to Azure Confidential Ledger generates an immutable ledger entry in the service. Writes, also referred to as transactions, are uniquely identified by transaction ids that increment with each write. Once written, ledger entries may be retrieved at any time.
### Collections
While most use cases involve just one collection per Confidential Ledger, we provide the collection id feature in case semantically or logically different groups of data need to be stored in the same Confidential Ledger.
Ledger entries are retrieved by their `collectionId`. The Confidential Ledger will always assume a constant, service-determined `collectionId` for entries written without a `collectionId` specified.
### Users
Users are managed directly with the Confidential Ledger instead of through Azure. Users may be AAD-based, identified by their AAD object id, or certificate-based, identified by their PEM certificate fingerprint.
### Receipts
To enforce transaction integrity guarantees, an Azure Confidential Ledger uses a [Merkle tree][merkle_tree_wiki] data structure to record the hash of all transactions blocks that are appended to the immutable ledger. After a write transaction is committed, Azure Confidential Ledger users can get a cryptographic Merkle proof, or receipt, over the entry produced in a Confidential Ledger to verify that the write operation was correctly saved. A write transaction receipt is proof that the system has committed the corresponding transaction and can be used to verify that the entry has been effectively appended to the ledger.
Please refer to the following [article](https://learn.microsoft.com/azure/confidential-ledger/write-transaction-receipts) for more information about Azure Confidential Ledger write transaction receipts.
### Receipt Verification
After getting a receipt for a write transaction, Azure Confidential Ledger users can verify the contents of the fetched receipt following a verification algorithm. The success of the verification is proof that the write operation associated to the receipt was correctly appended into the immutable ledger.
Please refer to the following [article](https://learn.microsoft.com/azure/confidential-ledger/verify-write-transaction-receipts) for more information about the verification process for Azure Confidential Ledger write transaction receipts.
### Application Claims
Azure Confidential Ledger applications can attach arbitrary data, called application claims, to write transactions. These claims represent the actions executed during a write operation. When attached to a transaction, the SHA-256 digest of the claims object is included in the ledger and committed as part of the write transaction. This guarantees that the digest is signed in place and cannot be tampered with.
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)
- [User-Defined Claims in Receipts](https://microsoft.github.io/CCF/main/build_apps/example_cpp.html#user-defined-claims-in-receipts)
### Confidential computing
[Azure Confidential Computing][azure_confidential_computing] allows you to isolate and protect your data while it is being processed in the cloud. Azure Confidential Ledger runs on Azure Confidential Computing virtual machines, thus providing stronger data protection with encryption of data in use.
### Confidential Consortium Framework
Azure Confidential Ledger is built on Microsoft Research's open-source [Confidential Consortium Framework (CCF)][ccf]. Under CCF, applications are managed by a consortium of members with the ability to submit proposals to modify and govern application operation. In Azure Confidential Ledger, Microsoft Azure owns an operator member identity that allows it to perform governance and maintenance actions like replacing unhealthy nodes in the Confidential Ledger and upgrading the enclave code.
## Examples
This section contains code snippets covering common tasks, including:
- [Append entry](#append-entry)
- [Retrieving ledger entries](#retrieving-ledger-entries)
- [Making a ranged query](#making-a-ranged-query)
- [Managing users](#managing-users)
- [Using certificate authentication](#using-certificate-authentication)
- [Verify write transaction receipts](#verify-write-transaction-receipts)
### Append entry
Data that needs to be stored immutably in a tamper-proof manner can be saved to Azure Confidential Ledger by appending an entry to the ledger.
Since Confidential Ledger is a distributed system, rare transient failures may cause writes to be lost. For entries that must be preserved, it is advisable to verify that the write became durable. For less important writes where higher client throughput is preferred, the wait step may be skipped.
```python
from azure.confidentialledger import ConfidentialLedgerClient
from azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient
from azure.identity import DefaultAzureCredential
identity_client = ConfidentialLedgerCertificateClient()
network_identity = identity_client.get_ledger_identity(
ledger_id="my-ledger-id"
)
ledger_tls_cert_file_name = "ledger_certificate.pem"
with open(ledger_tls_cert_file_name, "w") as cert_file:
cert_file.write(network_identity["ledgerTlsCertificate"])
credential = DefaultAzureCredential()
ledger_client = ConfidentialLedgerClient(
endpoint="https://my-ledger-id.confidential-ledger.azure.com",
credential=credential,
ledger_certificate_path=ledger_tls_cert_file_name
)
post_entry_result = ledger_client.create_ledger_entry(
{"contents": "Hello world!"}
)
transaction_id = post_entry_result["transactionId"]
wait_poller = ledger_client.begin_wait_for_commit(transaction_id)
wait_poller.wait()
print(f'Ledger entry at transaction id {transaction_id} has been committed successfully')
```
Alternatively, the client may wait for commit when writing a ledger entry.
```python
from azure.confidentialledger import ConfidentialLedgerClient
from azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient
from azure.identity import DefaultAzureCredential
identity_client = ConfidentialLedgerCertificateClient()
network_identity = identity_client.get_ledger_identity(
ledger_id="my-ledger-id"
)
ledger_tls_cert_file_name = "ledger_certificate.pem"
with open(ledger_tls_cert_file_name, "w") as cert_file:
cert_file.write(network_identity["ledgerTlsCertificate"])
credential = DefaultAzureCredential()
ledger_client = ConfidentialLedgerClient(
endpoint="https://my-ledger-id.confidential-ledger.azure.com",
credential=credential,
ledger_certificate_path=ledger_tls_cert_file_name
)
post_poller = ledger_client.begin_create_ledger_entry(
{"contents": "Hello world again!"}
)
new_post_result = post_poller.result()
print(
'The new ledger entry has been committed successfully at transaction id '
f'{new_post_result["transactionId"]}'
)
```
### Retrieving ledger entries
Getting ledger entries older than the latest may take some time as the service is loading historical entries, so a poller is provided.
Ledger entries are retrieved by collection. The returned value is the value contained in the specified collection at the point in time identified by the transaction id.
```python
from azure.confidentialledger import ConfidentialLedgerClient
from azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient
from azure.identity import DefaultAzureCredential
identity_client = ConfidentialLedgerCertificateClient()
network_identity = identity_client.get_ledger_identity(
ledger_id="my-ledger-id"
)
ledger_tls_cert_file_name = "ledger_certificate.pem"
with open(ledger_tls_cert_file_name, "w") as cert_file:
cert_file.write(network_identity["ledgerTlsCertificate"])
credential = DefaultAzureCredential()
ledger_client = ConfidentialLedgerClient(
endpoint="https://my-ledger-id.confidential-ledger.azure.com",
credential=credential,
ledger_certificate_path=ledger_tls_cert_file_name
)
post_poller = ledger_client.begin_create_ledger_entry(
{"contents": "Original hello"}
)
post_result = post_poller.result()
post_transaction_id = post_result["transactionId"]
latest_entry = ledger_client.get_current_ledger_entry()
print(
f'Current entry (transaction id = {latest_entry["transactionId"]}) '
f'in collection {latest_entry["collectionId"]}: {latest_entry["contents"]}'
)
post_poller = ledger_client.begin_create_ledger_entry(
{"contents": "Hello!"}
)
post_result = post_poller.result()
get_entry_poller = ledger_client.begin_get_ledger_entry(post_transaction_id)
older_entry = get_entry_poller.result()
print(
f'Contents of {older_entry["entry"]["collectionId"]} at {post_transaction_id}: {older_entry["entry"]["contents"]}'
)
```
### Making a ranged query
Ledger entries may be retrieved over a range of transaction ids. Entries will only be returned from the default or specified collection.
```python
from azure.confidentialledger import ConfidentialLedgerClient
from azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient
from azure.identity import DefaultAzureCredential
identity_client = ConfidentialLedgerCertificateClient()
network_identity = identity_client.get_ledger_identity(
ledger_id="my-ledger-id"
)
ledger_tls_cert_file_name = "ledger_certificate.pem"
with open(ledger_tls_cert_file_name, "w") as cert_file:
cert_file.write(network_identity["ledgerTlsCertificate"])
credential = DefaultAzureCredential()
ledger_client = ConfidentialLedgerClient(
endpoint="https://my-ledger-id.confidential-ledger.azure.com",
credential=credential,
ledger_certificate_path=ledger_tls_cert_file_name
)
post_poller = ledger_client.begin_create_ledger_entry(
{"contents": "First message"}
)
first_transaction_id = post_poller.result()["transactionId"]
for i in range(10):
ledger_client.create_ledger_entry(
{"contents": f"Message {i}"}
)
post_poller = ledger_client.begin_create_ledger_entry(
{"contents": "Last message"}
)
last_transaction_id = post_poller.result()["transactionId"]
ranged_result = ledger_client.list_ledger_entries(
from_transaction_id=first_transaction_id,
to_transaction_id=last_transaction_id,
)
for entry in ranged_result:
print(f'Contents at {entry["transactionId"]}: {entry["contents"]}')
```
### Managing users
Users with `Administrator` privileges can manage users of the Confidential Ledger directly with the Confidential Ledger itself. Available roles are `Reader` (read-only), `Contributor` (read and write), and `Administrator` (read, write, and add or remove users).
```python
from azure.confidentialledger import ConfidentialLedgerClient
from azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient
from azure.identity import DefaultAzureCredential
identity_client = ConfidentialLedgerCertificateClient()
network_identity = identity_client.get_ledger_identity(
ledger_id="my-ledger-id"
)
ledger_tls_cert_file_name = "ledger_certificate.pem"
with open(ledger_tls_cert_file_name, "w") as cert_file:
cert_file.write(network_identity["ledgerTlsCertificate"])
credential = DefaultAzureCredential()
ledger_client = ConfidentialLedgerClient(
endpoint="https://my-ledger-id.confidential-ledger.azure.com",
credential=credential,
ledger_certificate_path=ledger_tls_cert_file_name
)
user_id = "some AAD object id"
user = ledger_client.create_or_update_user(
user_id, {"assignedRole": "Contributor"}
)
# A client may now be created and used with AAD credentials (i.e. AAD-issued JWT tokens) for the user identified by `user_id`.
user = ledger_client.get_user(user_id)
assert user["userId"] == user_id
assert user["assignedRole"] == "Contributor"
ledger_client.delete_user(user_id)
# For a certificate-based user, their user ID is the fingerprint for their PEM certificate.
user_id = "PEM certificate fingerprint"
user = ledger_client.create_or_update_user(
user_id, {"assignedRole": "Reader"}
)
user = ledger_client.get_user(user_id)
assert user["userId"] == user_id
assert user["assignedRole"] == "Reader"
ledger_client.delete_user(user_id)
```
### Using certificate authentication
Clients may authenticate with a client certificate in mutual TLS instead of via an Azure Active Directory token. `ConfidentialLedgerCertificateCredential` is provided for such clients.
```python
from azure.confidentialledger import (
ConfidentialLedgerCertificateCredential,
ConfidentialLedgerClient,
)
from azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient
identity_client = ConfidentialLedgerCertificateClient()
network_identity = identity_client.get_ledger_identity(
ledger_id="my-ledger-id"
)
ledger_tls_cert_file_name = "ledger_certificate.pem"
with open(ledger_tls_cert_file_name, "w") as cert_file:
cert_file.write(network_identity["ledgerTlsCertificate"])
credential = ConfidentialLedgerCertificateCredential(
certificate_path="Path to user certificate PEM file"
)
ledger_client = ConfidentialLedgerClient(
endpoint="https://my-ledger-id.confidential-ledger.azure.com",
credential=credential,
ledger_certificate_path=ledger_tls_cert_file_name
)
```
### Verify write transaction receipts
Clients can leverage the receipt verification library in the SDK to verify write transaction receipts issued by Azure Confidential Legder instances. The utility can be used to fully verify receipts offline as the verification algorithm does not require to be connected to a Confidential ledger or any other Azure service.
Once a new entry has been appended to the ledger (please refer to [this example](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/confidentialledger/azure-confidentialledger#append-entry)), it is possible to get a receipt for the committed write transaction.
```python
from azure.confidentialledger import ConfidentialLedgerClient
from azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient
from azure.identity import DefaultAzureCredential
# Replace this with the Confidential Ledger ID
ledger_id = "my-ledger-id"
# Setup authentication
credential = DefaultAzureCredential()
# Create a Ledger Certificate client and use it to
# retrieve the service identity for our ledger
identity_client = ConfidentialLedgerCertificateClient()
network_identity = identity_client.get_ledger_identity(
ledger_id=ledger_id
)
# Save ledger service certificate into a file for later use
ledger_tls_cert_file_name = "ledger_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=f"https://{ledger_id}.confidential-ledger.azure.com",
credential=credential,
ledger_certificate_path=ledger_tls_cert_file_name
)
# The method begin_get_receipt returns a poller that
# we can use to wait for the receipt to be available for retrieval
get_receipt_poller = ledger_client.begin_get_receipt(transaction_id)
get_receipt_result = get_receipt_poller.result()
print(f"Write receipt for transaction id {transaction_id} was successfully retrieved: {get_receipt_result}")
```
After fetching a receipt for a write transaction, it is possible to call the `verify_receipt` function to verify that the receipt is valid. The function can accept an optional list of application claims to verify against the receipt claims digest.
```python
from azure.confidentialledger.receipt import (
verify_receipt,
)
# Read contents of service certificate file saved in previous step.
with open(ledger_tls_cert_file_name, "r") as service_cert_file:
service_cert_content = service_cert_file.read()
# Optionally read application claims, if any
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=application_claims)
print(f"Receipt for transaction id {transaction_id} successfully verified")
except ValueError:
print(f"Receipt verification for transaction id {transaction_id} failed")
```
A full sample Python program that shows how to append a new entry to a running Confidential Ledger instance, get a receipt for the committed transaction, and verify the receipt contents can be found under the [samples](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples) folder: [get_and_verify_receipt.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/get_and_verify_receipt.py).
### Async API
This library includes a complete async API supported on Python 3.5+. To use it, you must first install an async transport, such as [aiohttp](https://pypi.org/project/aiohttp). See the [azure-core documentation](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/CLIENT_LIBRARY_DEVELOPER.md#transport) for more information.
An async client is obtained from `azure.confidentialledger.aio`. Methods have the same names and signatures as the synchronous client. Samples may be found [here](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples).
## Troubleshooting
### General
Confidential Ledger clients raise exceptions defined in [azure-core][azure_core_exceptions]. For example, if you try to get a transaction that doesn't exist, `ConfidentialLedgerClient` raises [ResourceNotFoundError](https://aka.ms/azsdk-python-core-exceptions-resource-not-found-error):
```python
from azure.core.exceptions import ResourceNotFoundError
from azure.confidentialledger import ConfidentialLedgerClient
from azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient
from azure.identity import DefaultAzureCredential
identity_client = ConfidentialLedgerCertificateClient()
network_identity = identity_client.get_ledger_identity(
ledger_id="my-ledger-id"
)
ledger_tls_cert_file_name = "ledger_certificate.pem"
with open(ledger_tls_cert_file_name, "w") as cert_file:
cert_file.write(network_identity["ledgerTlsCertificate"])
credential = DefaultAzureCredential()
ledger_client = ConfidentialLedgerClient(
endpoint="https://my-ledger-id.confidential-ledger.azure.com",
credential=credential,
ledger_certificate_path=ledger_tls_cert_file_name
)
try:
ledger_client.begin_get_ledger_entry(
transaction_id="10000.100000" # Using a very high id that probably doesn't exist in the ledger if it's relatively new.
)
except ResourceNotFoundError as e:
print(e.message)
```
### Logging
This library uses the standard
[logging](https://docs.python.org/3.5/library/logging.html) library for logging. Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO level.
Detailed DEBUG level logging, including request/response bodies and unredacted headers, can be enabled on a client with the `logging_enable` argument:
```python
import logging
import sys
from azure.confidentialledger import ConfidentialLedgerClient
from azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient
from azure.identity import DefaultAzureCredential
# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)
identity_client = ConfidentialLedgerCertificateClient()
network_identity = identity_client.get_ledger_identity(
ledger_id="my-ledger-id"
)
ledger_tls_cert_file_name = "ledger_certificate.pem"
with open(ledger_tls_cert_file_name, "w") as cert_file:
cert_file.write(network_identity["ledgerTlsCertificate"])
credential = DefaultAzureCredential()
# This client will log detailed information about its HTTP sessions, at DEBUG level.
ledger_client = ConfidentialLedgerClient(
endpoint="https://my-ledger-id.confidential-ledger.azure.com",
credential=credential,
ledger_certificate_path=ledger_tls_cert_file_name,
logging_enable=True,
)
```
Similarly, `logging_enable` can enable detailed logging for a single operation, even when it isn't enabled for the client:
```python
ledger_client.get_current_ledger_entry(logging_enable=True)
```
## Next steps
### More sample code
These code samples show common scenario operations with the Azure Confidential Ledger client library.
#### Common scenarios
- Writing to the ledger:
- [write_to_ledger.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/write_to_ledger.py)
- [write_to_ledger_async.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/write_to_ledger_async.py) (async version)
- Write many ledger entries and retrieve them all afterwards:
- [list_ledger_entries.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/list_ledger_entries.py)
- [list_ledger_entries_async.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/list_ledger_entries_async.py) (async version)
- Manage users using service-implemented role-based access control:
- [manage_users.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/manage_users.py)
- [manage_users_async.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/manage_users_async.py) (async version)
#### Advanced scenarios
- Using collections:
- [use_collections.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/use_collections.py)
- [use_collections_async.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/use_collections_async.py) (async version)
- Getting receipts for ledger writes:
- [get_receipt.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/get_receipt.py)
- [get_receipt_async.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/get_receipt_async.py) (async version)
- Verifying service details:
- [verify_service.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/verify_service.py)
- [verify_service_async.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/verify_service_async.py) (async version)
### Additional Documentation
For more extensive documentation on Azure Confidential Ledger, see the
[API reference documentation][reference_docs]. You may also read more about Microsoft Research's open-source [Confidential Consortium Framework][ccf].
## Contributing
This project welcomes contributions and suggestions. Most contributions require
you to agree to a Contributor License Agreement (CLA) declaring that you have
the right to, and actually do, grant us the rights to use your contribution.
For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether
you need to provide a CLA and decorate the PR appropriately (e.g., label,
comment). Simply follow the instructions provided by the bot. You will only
need to do this once across all repos using our CLA.
This project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct].
For more information, see the
[Code of Conduct FAQ][code_of_conduct_faq] or
contact opencode@microsoft.com with any additional questions or comments.
[azure_cli]: https://docs.microsoft.com/cli/azure
[azure_cloud_shell]: https://shell.azure.com/bash
[azure_confidential_computing]: https://azure.microsoft.com/solutions/confidential-compute
[azure_core_exceptions]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/core/azure-core#azure-core-library-exceptions
[azure_identity]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity
[azure_identity_pypi]: https://pypi.org/project/azure-identity/
[azure_resource_manager]: https://docs.microsoft.com/azure/azure-resource-manager/management/overview
[azure_sub]: https://azure.microsoft.com/free
[ccf]: https://github.com/Microsoft/CCF
[code_of_conduct]: https://opensource.microsoft.com/codeofconduct
[code_of_conduct_faq]: https://opensource.microsoft.com/codeofconduct/faq
[confidential_ledger_client_src]: https://aka.ms/azsdk/python/confidentialledger/src
[confidential_ledger_docs]: https://aka.ms/confidentialledger-servicedocs
[default_cred_ref]: https://aka.ms/azsdk/python/identity/docs#azure.identity.DefaultAzureCredential
[pip]: https://pypi.org/project/pip/
[pypi_package_confidential_ledger]: https://aka.ms/azsdk/python/confidentialledger/pypi
[reference_docs]: https://aka.ms/azsdk/python/confidentialledger/ref-docs
# Release History
## 1.1.1 (2023-08-01)
### Bugs Fixed
- Allow some `ResourceNotFoundError` occurrences in `begin_wait_for_commit` to account for unexpected loss of session stickiness. These errors may occur when the connected node changes and transactions have not been fully replicated.
## 1.1.0 (2023-05-09)
### 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, 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 and application claims.
### Other Changes
- Add dependency on Python `cryptography` library (`>= 2.1.4`)
- Add tests for receipt verification models and receipt verification public method.
- Add tests for application claims models and digest computation public method.
## 1.0.0 (2022-07-19)
GA Data Plane Python SDK for Confidential Ledger.
### Bugs Fixed
- User ids that are certificate fingerprints are no longer URL-encoded in the request URI.
### Breaking Changes
- Removed all models. Methods now return JSON directly.
- `sub_ledger_id` fields are now named `collection_id`.
- `azure.confidentialledger.identity_service` has been renamed to `azure.confidentialledger.certificate`.
- `ConfidentialLedgerIdentityServiceClient` is now `ConfidentialLedgerCertificateClient`.
- `post_ledger_entry` has been renamed to `create_ledger_entry`.
### Other Changes
- Python 2.7 is no longer supported. Please use Python version 3.7 or later.
- Convenience poller methods added for certain long-running operations.
- Add new supported API version: `2022-05-13`.
## 1.0.0b1 (2021-05-12)
- This is the initial release of the Azure Confidential Ledger library.
Raw data
{
"_id": null,
"home_page": "https://github.com/Azure/azure-sdk-for-python",
"name": "azure-confidentialledger",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Microsoft Corporation",
"author_email": "accledgerdevs@microsoft.com",
"download_url": "https://files.pythonhosted.org/packages/c7/e5/5e07345475de8edc74c9620145b12ce8d9f4502697947fa909f531ba419f/azure-confidentialledger-1.1.1.zip",
"platform": null,
"description": "# Azure Confidential Ledger client library for Python\n\nAzure Confidential Ledger provides a service for logging to an immutable, tamper-proof ledger. As part of the [Azure Confidential Computing][azure_confidential_computing] portfolio, Azure Confidential Ledger runs in secure, hardware-based trusted execution environments, also known as enclaves. It is built on Microsoft Research's [Confidential Consortium Framework][ccf].\n\n[Source code][confidential_ledger_client_src]\n| [Package (PyPI)][pypi_package_confidential_ledger]\n| [Package (Conda)](https://anaconda.org/microsoft/azure-confidentialledger/)\n| [API reference documentation][reference_docs]\n| [Product documentation][confidential_ledger_docs]\n\n## Getting started\n### Install packages\nInstall [azure-confidentialledger][pypi_package_confidential_ledger] and [azure-identity][azure_identity_pypi] with [pip][pip]:\n```Bash\npip install azure-identity azure-confidentialledger\n```\n[azure-identity][azure_identity] is used for Azure Active Directory\nauthentication as demonstrated below.\n\n### Prerequisites\n* An [Azure subscription][azure_sub]\n* Python 3.6 or later\n* A running instance of Azure Confidential Ledger.\n* A registered user in the Confidential Ledger, typically assigned during [ARM][azure_resource_manager] resource creation, with `Administrator` privileges.\n\n### Authenticate the client\n#### Using Azure Active Directory\nThis document demonstrates using [DefaultAzureCredential][default_cred_ref] to authenticate to the Confidential Ledger via Azure Active Directory. However, `ConfidentialLedgerClient` accepts any [azure-identity][azure_identity] credential. See the [azure-identity][azure_identity] documentation for more information about other credentials.\n\n#### Using a client certificate\nAs an alternative to Azure Active Directory, clients may choose to use a client certificate to authenticate via mutual TLS. `azure.confidentialledger.ConfidentialLedgerCertificateCredential` may be used for this purpose.\n\n### Create a client\n`DefaultAzureCredential` will automatically handle most Azure SDK client scenarios. To get started, set environment variables for the AAD identity registered with your Confidential Ledger.\n```bash\nexport AZURE_CLIENT_ID=\"generated app id\"\nexport AZURE_CLIENT_SECRET=\"random password\"\nexport AZURE_TENANT_ID=\"tenant id\"\n```\nThen, `DefaultAzureCredential` will be able to authenticate the `ConfidentialLedgerClient`.\n\nConstructing the client also requires your Confidential Ledger's URL and id, which you can get from the Azure CLI or the Azure Portal. When you have retrieved those values, please replace instances of `\"my-ledger-id\"` and `\"https://my-ledger-id.confidential-ledger.azure.com\"` in the examples below. You may also need to replace `\"https://identity.confidential-ledger.core.azure.com\"` with the hostname from the `identityServiceUri` in the ARM description of your ledger.\n\nBecause Confidential Ledgers use self-signed certificates securely generated and stored in an enclave, the signing certificate for each Confidential Ledger must first be retrieved from the Confidential Ledger Identity Service.\n\n```python\nfrom azure.confidentialledger import ConfidentialLedgerClient\nfrom azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient\nfrom azure.identity import DefaultAzureCredential\n\nidentity_client = ConfidentialLedgerCertificateClient()\nnetwork_identity = identity_client.get_ledger_identity(\n ledger_id=\"my-ledger-id\"\n)\n\nledger_tls_cert_file_name = \"ledger_certificate.pem\"\nwith open(ledger_tls_cert_file_name, \"w\") as cert_file:\n cert_file.write(network_identity[\"ledgerTlsCertificate\"])\n\ncredential = DefaultAzureCredential()\nledger_client = ConfidentialLedgerClient(\n endpoint=\"https://my-ledger-id.confidential-ledger.azure.com\",\n credential=credential,\n ledger_certificate_path=ledger_tls_cert_file_name\n)\n```\n\nConveniently, the `ConfidentialLedgerClient` constructor will fetch the ledger TLS certificate (and write it to the specified file) if it is provided with a non-existent file. The user is responsible for removing the created file as needed.\n\n```python\nfrom azure.confidentialledger import ConfidentialLedgerClient\nfrom azure.identity import DefaultAzureCredential\n\ncredential = DefaultAzureCredential()\nledger_client = ConfidentialLedgerClient(\n endpoint=\"https://my-ledger-id.confidential-ledger.azure.com\",\n credential=credential,\n ledger_certificate_path=\"ledger_certificate.pem\"\n)\n\n# The ledger TLS certificate is written to `ledger_certificate.pem`.\n```\n\nTo make it clear that a file is being used for the ledger TLS certificate, subsequent examples will explicitly write the ledger TLS certificate to a file.\n\n## Key concepts\n### Ledger entries and transactions\nEvery write to Azure Confidential Ledger generates an immutable ledger entry in the service. Writes, also referred to as transactions, are uniquely identified by transaction ids that increment with each write. Once written, ledger entries may be retrieved at any time.\n\n### Collections\nWhile most use cases involve just one collection per Confidential Ledger, we provide the collection id feature in case semantically or logically different groups of data need to be stored in the same Confidential Ledger.\n\nLedger entries are retrieved by their `collectionId`. The Confidential Ledger will always assume a constant, service-determined `collectionId` for entries written without a `collectionId` specified.\n\n### Users\nUsers are managed directly with the Confidential Ledger instead of through Azure. Users may be AAD-based, identified by their AAD object id, or certificate-based, identified by their PEM certificate fingerprint.\n\n### Receipts\n\nTo enforce transaction integrity guarantees, an Azure Confidential Ledger uses a [Merkle tree][merkle_tree_wiki] data structure to record the hash of all transactions blocks that are appended to the immutable ledger. After a write transaction is committed, Azure Confidential Ledger users can get a cryptographic Merkle proof, or receipt, over the entry produced in a Confidential Ledger to verify that the write operation was correctly saved. A write transaction receipt is proof that the system has committed the corresponding transaction and can be used to verify that the entry has been effectively appended to the ledger.\n\nPlease refer to the following [article](https://learn.microsoft.com/azure/confidential-ledger/write-transaction-receipts) for more information about Azure Confidential Ledger write transaction receipts.\n\n### Receipt Verification\n\nAfter getting a receipt for a write transaction, Azure Confidential Ledger users can verify the contents of the fetched receipt following a verification algorithm. The success of the verification is proof that the write operation associated to the receipt was correctly appended into the immutable ledger.\n\nPlease refer to the following [article](https://learn.microsoft.com/azure/confidential-ledger/verify-write-transaction-receipts) for more information about the verification process for Azure Confidential Ledger write transaction receipts.\n\n### Application Claims\nAzure Confidential Ledger applications can attach arbitrary data, called application claims, to write transactions. These claims represent the actions executed during a write operation. When attached to a transaction, the SHA-256 digest of the claims object is included in the ledger and committed as part of the write transaction. This guarantees that the digest is signed in place and cannot be tampered with.\n\nLater, 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.\n\nMore details on the application claims format and the digest computation algorithm can be found at the following links:\n\n- [Azure Confidential Ledger application claims](https://learn.microsoft.com/azure/confidential-ledger/write-transaction-receipts#application-claims)\n- [Azure Confidential Ledger application claims digest verification](https://learn.microsoft.com/azure/confidential-ledger/verify-write-transaction-receipts#verify-application-claims-digest)\n\nPlease refer to the following CCF documentation pages for more information about CCF Application claims:\n\n- [Application Claims](https://microsoft.github.io/CCF/main/use_apps/verify_tx.html#application-claims)\n- [User-Defined Claims in Receipts](https://microsoft.github.io/CCF/main/build_apps/example_cpp.html#user-defined-claims-in-receipts)\n\n### Confidential computing\n[Azure Confidential Computing][azure_confidential_computing] allows you to isolate and protect your data while it is being processed in the cloud. Azure Confidential Ledger runs on Azure Confidential Computing virtual machines, thus providing stronger data protection with encryption of data in use.\n\n### Confidential Consortium Framework\nAzure Confidential Ledger is built on Microsoft Research's open-source [Confidential Consortium Framework (CCF)][ccf]. Under CCF, applications are managed by a consortium of members with the ability to submit proposals to modify and govern application operation. In Azure Confidential Ledger, Microsoft Azure owns an operator member identity that allows it to perform governance and maintenance actions like replacing unhealthy nodes in the Confidential Ledger and upgrading the enclave code.\n\n## Examples\nThis section contains code snippets covering common tasks, including:\n- [Append entry](#append-entry)\n- [Retrieving ledger entries](#retrieving-ledger-entries)\n- [Making a ranged query](#making-a-ranged-query)\n- [Managing users](#managing-users)\n- [Using certificate authentication](#using-certificate-authentication)\n- [Verify write transaction receipts](#verify-write-transaction-receipts)\n\n### Append entry\nData that needs to be stored immutably in a tamper-proof manner can be saved to Azure Confidential Ledger by appending an entry to the ledger.\n\nSince Confidential Ledger is a distributed system, rare transient failures may cause writes to be lost. For entries that must be preserved, it is advisable to verify that the write became durable. For less important writes where higher client throughput is preferred, the wait step may be skipped.\n\n```python\nfrom azure.confidentialledger import ConfidentialLedgerClient\nfrom azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient\nfrom azure.identity import DefaultAzureCredential\n\nidentity_client = ConfidentialLedgerCertificateClient()\nnetwork_identity = identity_client.get_ledger_identity(\n ledger_id=\"my-ledger-id\"\n)\n\nledger_tls_cert_file_name = \"ledger_certificate.pem\"\nwith open(ledger_tls_cert_file_name, \"w\") as cert_file:\n cert_file.write(network_identity[\"ledgerTlsCertificate\"])\n\ncredential = DefaultAzureCredential()\nledger_client = ConfidentialLedgerClient(\n endpoint=\"https://my-ledger-id.confidential-ledger.azure.com\",\n credential=credential,\n ledger_certificate_path=ledger_tls_cert_file_name\n)\n\npost_entry_result = ledger_client.create_ledger_entry(\n {\"contents\": \"Hello world!\"}\n )\ntransaction_id = post_entry_result[\"transactionId\"]\n\nwait_poller = ledger_client.begin_wait_for_commit(transaction_id)\nwait_poller.wait()\nprint(f'Ledger entry at transaction id {transaction_id} has been committed successfully')\n```\n\nAlternatively, the client may wait for commit when writing a ledger entry.\n\n```python\nfrom azure.confidentialledger import ConfidentialLedgerClient\nfrom azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient\nfrom azure.identity import DefaultAzureCredential\n\nidentity_client = ConfidentialLedgerCertificateClient()\nnetwork_identity = identity_client.get_ledger_identity(\n ledger_id=\"my-ledger-id\"\n)\n\nledger_tls_cert_file_name = \"ledger_certificate.pem\"\nwith open(ledger_tls_cert_file_name, \"w\") as cert_file:\n cert_file.write(network_identity[\"ledgerTlsCertificate\"])\n\ncredential = DefaultAzureCredential()\nledger_client = ConfidentialLedgerClient(\n endpoint=\"https://my-ledger-id.confidential-ledger.azure.com\",\n credential=credential,\n ledger_certificate_path=ledger_tls_cert_file_name\n)\n\npost_poller = ledger_client.begin_create_ledger_entry(\n {\"contents\": \"Hello world again!\"}\n)\nnew_post_result = post_poller.result()\nprint(\n 'The new ledger entry has been committed successfully at transaction id '\n f'{new_post_result[\"transactionId\"]}'\n)\n```\n\n### Retrieving ledger entries\nGetting ledger entries older than the latest may take some time as the service is loading historical entries, so a poller is provided.\n\nLedger entries are retrieved by collection. The returned value is the value contained in the specified collection at the point in time identified by the transaction id.\n\n```python\nfrom azure.confidentialledger import ConfidentialLedgerClient\nfrom azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient\nfrom azure.identity import DefaultAzureCredential\n\nidentity_client = ConfidentialLedgerCertificateClient()\nnetwork_identity = identity_client.get_ledger_identity(\n ledger_id=\"my-ledger-id\"\n)\n\nledger_tls_cert_file_name = \"ledger_certificate.pem\"\nwith open(ledger_tls_cert_file_name, \"w\") as cert_file:\n cert_file.write(network_identity[\"ledgerTlsCertificate\"])\n\ncredential = DefaultAzureCredential()\nledger_client = ConfidentialLedgerClient(\n endpoint=\"https://my-ledger-id.confidential-ledger.azure.com\",\n credential=credential,\n ledger_certificate_path=ledger_tls_cert_file_name\n)\n\npost_poller = ledger_client.begin_create_ledger_entry(\n {\"contents\": \"Original hello\"}\n)\npost_result = post_poller.result()\n\npost_transaction_id = post_result[\"transactionId\"]\n\nlatest_entry = ledger_client.get_current_ledger_entry()\nprint(\n f'Current entry (transaction id = {latest_entry[\"transactionId\"]}) '\n f'in collection {latest_entry[\"collectionId\"]}: {latest_entry[\"contents\"]}'\n)\n\npost_poller = ledger_client.begin_create_ledger_entry(\n {\"contents\": \"Hello!\"}\n)\npost_result = post_poller.result()\n\nget_entry_poller = ledger_client.begin_get_ledger_entry(post_transaction_id)\nolder_entry = get_entry_poller.result()\nprint(\n f'Contents of {older_entry[\"entry\"][\"collectionId\"]} at {post_transaction_id}: {older_entry[\"entry\"][\"contents\"]}'\n)\n```\n\n### Making a ranged query\nLedger entries may be retrieved over a range of transaction ids. Entries will only be returned from the default or specified collection.\n\n```python\nfrom azure.confidentialledger import ConfidentialLedgerClient\nfrom azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient\nfrom azure.identity import DefaultAzureCredential\n\nidentity_client = ConfidentialLedgerCertificateClient()\nnetwork_identity = identity_client.get_ledger_identity(\n ledger_id=\"my-ledger-id\"\n)\n\nledger_tls_cert_file_name = \"ledger_certificate.pem\"\nwith open(ledger_tls_cert_file_name, \"w\") as cert_file:\n cert_file.write(network_identity[\"ledgerTlsCertificate\"])\n\ncredential = DefaultAzureCredential()\nledger_client = ConfidentialLedgerClient(\n endpoint=\"https://my-ledger-id.confidential-ledger.azure.com\",\n credential=credential,\n ledger_certificate_path=ledger_tls_cert_file_name\n)\n\npost_poller = ledger_client.begin_create_ledger_entry(\n {\"contents\": \"First message\"}\n)\nfirst_transaction_id = post_poller.result()[\"transactionId\"]\n\nfor i in range(10):\n ledger_client.create_ledger_entry(\n {\"contents\": f\"Message {i}\"}\n )\n\npost_poller = ledger_client.begin_create_ledger_entry(\n {\"contents\": \"Last message\"}\n)\nlast_transaction_id = post_poller.result()[\"transactionId\"]\n\nranged_result = ledger_client.list_ledger_entries(\n from_transaction_id=first_transaction_id,\n to_transaction_id=last_transaction_id,\n)\nfor entry in ranged_result:\n print(f'Contents at {entry[\"transactionId\"]}: {entry[\"contents\"]}')\n```\n\n### Managing users\nUsers with `Administrator` privileges can manage users of the Confidential Ledger directly with the Confidential Ledger itself. Available roles are `Reader` (read-only), `Contributor` (read and write), and `Administrator` (read, write, and add or remove users).\n\n```python\nfrom azure.confidentialledger import ConfidentialLedgerClient\nfrom azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient\nfrom azure.identity import DefaultAzureCredential\n\nidentity_client = ConfidentialLedgerCertificateClient()\nnetwork_identity = identity_client.get_ledger_identity(\n ledger_id=\"my-ledger-id\"\n)\n\nledger_tls_cert_file_name = \"ledger_certificate.pem\"\nwith open(ledger_tls_cert_file_name, \"w\") as cert_file:\n cert_file.write(network_identity[\"ledgerTlsCertificate\"])\n\ncredential = DefaultAzureCredential()\nledger_client = ConfidentialLedgerClient(\n endpoint=\"https://my-ledger-id.confidential-ledger.azure.com\",\n credential=credential,\n ledger_certificate_path=ledger_tls_cert_file_name\n)\n\nuser_id = \"some AAD object id\"\nuser = ledger_client.create_or_update_user(\n user_id, {\"assignedRole\": \"Contributor\"}\n)\n# A client may now be created and used with AAD credentials (i.e. AAD-issued JWT tokens) for the user identified by `user_id`.\n\nuser = ledger_client.get_user(user_id)\nassert user[\"userId\"] == user_id\nassert user[\"assignedRole\"] == \"Contributor\"\n\nledger_client.delete_user(user_id)\n\n# For a certificate-based user, their user ID is the fingerprint for their PEM certificate.\nuser_id = \"PEM certificate fingerprint\"\nuser = ledger_client.create_or_update_user(\n user_id, {\"assignedRole\": \"Reader\"}\n)\n\nuser = ledger_client.get_user(user_id)\nassert user[\"userId\"] == user_id\nassert user[\"assignedRole\"] == \"Reader\"\n\nledger_client.delete_user(user_id)\n```\n\n### Using certificate authentication\nClients may authenticate with a client certificate in mutual TLS instead of via an Azure Active Directory token. `ConfidentialLedgerCertificateCredential` is provided for such clients.\n\n```python\nfrom azure.confidentialledger import (\n ConfidentialLedgerCertificateCredential,\n ConfidentialLedgerClient,\n)\nfrom azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient\n\nidentity_client = ConfidentialLedgerCertificateClient()\nnetwork_identity = identity_client.get_ledger_identity(\n ledger_id=\"my-ledger-id\"\n)\n\nledger_tls_cert_file_name = \"ledger_certificate.pem\"\nwith open(ledger_tls_cert_file_name, \"w\") as cert_file:\n cert_file.write(network_identity[\"ledgerTlsCertificate\"])\n\ncredential = ConfidentialLedgerCertificateCredential(\n certificate_path=\"Path to user certificate PEM file\"\n)\nledger_client = ConfidentialLedgerClient(\n endpoint=\"https://my-ledger-id.confidential-ledger.azure.com\",\n credential=credential,\n ledger_certificate_path=ledger_tls_cert_file_name\n)\n```\n\n### Verify write transaction receipts\n\nClients can leverage the receipt verification library in the SDK to verify write transaction receipts issued by Azure Confidential Legder instances. The utility can be used to fully verify receipts offline as the verification algorithm does not require to be connected to a Confidential ledger or any other Azure service.\n\nOnce a new entry has been appended to the ledger (please refer to [this example](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/confidentialledger/azure-confidentialledger#append-entry)), it is possible to get a receipt for the committed write transaction.\n\n```python\nfrom azure.confidentialledger import ConfidentialLedgerClient\nfrom azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient\nfrom azure.identity import DefaultAzureCredential\n\n# Replace this with the Confidential Ledger ID \nledger_id = \"my-ledger-id\"\n\n# Setup authentication\ncredential = DefaultAzureCredential()\n\n# Create a Ledger Certificate client and use it to\n# retrieve the service identity for our ledger\nidentity_client = ConfidentialLedgerCertificateClient()\nnetwork_identity = identity_client.get_ledger_identity(\n ledger_id=ledger_id\n)\n\n# Save ledger service certificate into a file for later use\nledger_tls_cert_file_name = \"ledger_certificate.pem\"\nwith open(ledger_tls_cert_file_name, \"w\") as cert_file:\n cert_file.write(network_identity[\"ledgerTlsCertificate\"])\n\n# Create Confidential Ledger client\nledger_client = ConfidentialLedgerClient(\n endpoint=f\"https://{ledger_id}.confidential-ledger.azure.com\",\n credential=credential,\n ledger_certificate_path=ledger_tls_cert_file_name\n)\n\n# The method begin_get_receipt returns a poller that\n# we can use to wait for the receipt to be available for retrieval \nget_receipt_poller = ledger_client.begin_get_receipt(transaction_id)\nget_receipt_result = get_receipt_poller.result()\n\nprint(f\"Write receipt for transaction id {transaction_id} was successfully retrieved: {get_receipt_result}\")\n```\n\nAfter fetching a receipt for a write transaction, it is possible to call the `verify_receipt` function to verify that the receipt is valid. The function can accept an optional list of application claims to verify against the receipt claims digest.\n\n```python\nfrom azure.confidentialledger.receipt import (\n verify_receipt,\n)\n\n# Read contents of service certificate file saved in previous step.\nwith open(ledger_tls_cert_file_name, \"r\") as service_cert_file:\n service_cert_content = service_cert_file.read()\n\n# Optionally read application claims, if any\napplication_claims = get_receipt_result.get(\"applicationClaims\", None) \n\ntry:\n # Verify the contents of the receipt.\n verify_receipt(get_receipt_result[\"receipt\"], service_cert_content, application_claims=application_claims)\n print(f\"Receipt for transaction id {transaction_id} successfully verified\")\nexcept ValueError:\n print(f\"Receipt verification for transaction id {transaction_id} failed\")\n```\n\nA full sample Python program that shows how to append a new entry to a running Confidential Ledger instance, get a receipt for the committed transaction, and verify the receipt contents can be found under the [samples](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples) folder: [get_and_verify_receipt.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/get_and_verify_receipt.py).\n\n### Async API\nThis library includes a complete async API supported on Python 3.5+. To use it, you must first install an async transport, such as [aiohttp](https://pypi.org/project/aiohttp). See the [azure-core documentation](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/CLIENT_LIBRARY_DEVELOPER.md#transport) for more information.\n\nAn async client is obtained from `azure.confidentialledger.aio`. Methods have the same names and signatures as the synchronous client. Samples may be found [here](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples).\n\n## Troubleshooting\n### General\nConfidential Ledger clients raise exceptions defined in [azure-core][azure_core_exceptions]. For example, if you try to get a transaction that doesn't exist, `ConfidentialLedgerClient` raises [ResourceNotFoundError](https://aka.ms/azsdk-python-core-exceptions-resource-not-found-error):\n\n```python\nfrom azure.core.exceptions import ResourceNotFoundError\nfrom azure.confidentialledger import ConfidentialLedgerClient\nfrom azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient\nfrom azure.identity import DefaultAzureCredential\n\nidentity_client = ConfidentialLedgerCertificateClient()\nnetwork_identity = identity_client.get_ledger_identity(\n ledger_id=\"my-ledger-id\"\n)\n\nledger_tls_cert_file_name = \"ledger_certificate.pem\"\nwith open(ledger_tls_cert_file_name, \"w\") as cert_file:\n cert_file.write(network_identity[\"ledgerTlsCertificate\"])\n\ncredential = DefaultAzureCredential()\nledger_client = ConfidentialLedgerClient(\n endpoint=\"https://my-ledger-id.confidential-ledger.azure.com\",\n credential=credential,\n ledger_certificate_path=ledger_tls_cert_file_name\n)\n\ntry:\n ledger_client.begin_get_ledger_entry(\n transaction_id=\"10000.100000\" # Using a very high id that probably doesn't exist in the ledger if it's relatively new.\n )\nexcept ResourceNotFoundError as e:\n print(e.message)\n```\n\n### Logging\nThis library uses the standard\n[logging](https://docs.python.org/3.5/library/logging.html) library for logging. Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO level.\n\nDetailed DEBUG level logging, including request/response bodies and unredacted headers, can be enabled on a client with the `logging_enable` argument:\n```python\nimport logging\nimport sys\n\nfrom azure.confidentialledger import ConfidentialLedgerClient\nfrom azure.confidentialledger.certificate import ConfidentialLedgerCertificateClient\nfrom azure.identity import DefaultAzureCredential\n\n# Create a logger for the 'azure' SDK\nlogger = logging.getLogger('azure')\nlogger.setLevel(logging.DEBUG)\n\n# Configure a console output\nhandler = logging.StreamHandler(stream=sys.stdout)\nlogger.addHandler(handler)\n\nidentity_client = ConfidentialLedgerCertificateClient()\nnetwork_identity = identity_client.get_ledger_identity(\n ledger_id=\"my-ledger-id\"\n)\n\nledger_tls_cert_file_name = \"ledger_certificate.pem\"\nwith open(ledger_tls_cert_file_name, \"w\") as cert_file:\n cert_file.write(network_identity[\"ledgerTlsCertificate\"])\n\ncredential = DefaultAzureCredential()\n\n# This client will log detailed information about its HTTP sessions, at DEBUG level.\nledger_client = ConfidentialLedgerClient(\n endpoint=\"https://my-ledger-id.confidential-ledger.azure.com\",\n credential=credential,\n ledger_certificate_path=ledger_tls_cert_file_name,\n logging_enable=True,\n)\n```\n\nSimilarly, `logging_enable` can enable detailed logging for a single operation, even when it isn't enabled for the client:\n```python\nledger_client.get_current_ledger_entry(logging_enable=True)\n```\n\n## Next steps\n### More sample code\nThese code samples show common scenario operations with the Azure Confidential Ledger client library.\n\n#### Common scenarios\n\n- Writing to the ledger:\n - [write_to_ledger.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/write_to_ledger.py) \n - [write_to_ledger_async.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/write_to_ledger_async.py) (async version)\n\n- Write many ledger entries and retrieve them all afterwards:\n - [list_ledger_entries.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/list_ledger_entries.py)\n - [list_ledger_entries_async.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/list_ledger_entries_async.py) (async version)\n\n- Manage users using service-implemented role-based access control: \n - [manage_users.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/manage_users.py)\n - [manage_users_async.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/manage_users_async.py) (async version)\n\n#### Advanced scenarios\n\n- Using collections: \n - [use_collections.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/use_collections.py)\n - [use_collections_async.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/use_collections_async.py) (async version)\n \n- Getting receipts for ledger writes: \n - [get_receipt.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/get_receipt.py)\n - [get_receipt_async.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/get_receipt_async.py) (async version)\n \n- Verifying service details: \n - [verify_service.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/verify_service.py) \n - [verify_service_async.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/confidentialledger/azure-confidentialledger/samples/verify_service_async.py) (async version)\n\n### Additional Documentation\nFor more extensive documentation on Azure Confidential Ledger, see the\n[API reference documentation][reference_docs]. You may also read more about Microsoft Research's open-source [Confidential Consortium Framework][ccf].\n\n## Contributing\nThis project welcomes contributions and suggestions. Most contributions require\nyou to agree to a Contributor License Agreement (CLA) declaring that you have\nthe right to, and actually do, grant us the rights to use your contribution.\nFor details, visit https://cla.microsoft.com.\n\nWhen you submit a pull request, a CLA-bot will automatically determine whether\nyou need to provide a CLA and decorate the PR appropriately (e.g., label,\ncomment). Simply follow the instructions provided by the bot. You will only\nneed to do this once across all repos using our CLA.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct].\nFor more information, see the\n[Code of Conduct FAQ][code_of_conduct_faq] or\ncontact opencode@microsoft.com with any additional questions or comments.\n\n\n[azure_cli]: https://docs.microsoft.com/cli/azure\n[azure_cloud_shell]: https://shell.azure.com/bash\n[azure_confidential_computing]: https://azure.microsoft.com/solutions/confidential-compute\n[azure_core_exceptions]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/core/azure-core#azure-core-library-exceptions\n[azure_identity]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity\n[azure_identity_pypi]: https://pypi.org/project/azure-identity/\n[azure_resource_manager]: https://docs.microsoft.com/azure/azure-resource-manager/management/overview\n[azure_sub]: https://azure.microsoft.com/free\n[ccf]: https://github.com/Microsoft/CCF\n[code_of_conduct]: https://opensource.microsoft.com/codeofconduct\n[code_of_conduct_faq]: https://opensource.microsoft.com/codeofconduct/faq\n[confidential_ledger_client_src]: https://aka.ms/azsdk/python/confidentialledger/src\n[confidential_ledger_docs]: https://aka.ms/confidentialledger-servicedocs\n[default_cred_ref]: https://aka.ms/azsdk/python/identity/docs#azure.identity.DefaultAzureCredential\n[pip]: https://pypi.org/project/pip/\n[pypi_package_confidential_ledger]: https://aka.ms/azsdk/python/confidentialledger/pypi\n[reference_docs]: https://aka.ms/azsdk/python/confidentialledger/ref-docs\n\n\n# Release History\n\n## 1.1.1 (2023-08-01)\n### Bugs Fixed\n- Allow some `ResourceNotFoundError` occurrences in `begin_wait_for_commit` to account for unexpected loss of session stickiness. These errors may occur when the connected node changes and transactions have not been fully replicated.\n\n## 1.1.0 (2023-05-09)\n\n### Features Added\n- Add `azure.confidentialledger.receipt` module for Azure Confidential Ledger write transaction receipt verification.\n- 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.\n- Add `compute_claims_digest` function to compute the claims digest from a list of application claims JSON objects. \n- Add sample code to get and verify a write receipt from a running Confidential Ledger instance.\n- Update README with examples and documentation for receipt verification and application claims.\n\n### Other Changes\n- Add dependency on Python `cryptography` library (`>= 2.1.4`)\n- Add tests for receipt verification models and receipt verification public method.\n- Add tests for application claims models and digest computation public method.\n\n## 1.0.0 (2022-07-19)\n\nGA Data Plane Python SDK for Confidential Ledger.\n\n### Bugs Fixed\n- User ids that are certificate fingerprints are no longer URL-encoded in the request URI.\n\n### Breaking Changes\n- Removed all models. Methods now return JSON directly.\n- `sub_ledger_id` fields are now named `collection_id`.\n- `azure.confidentialledger.identity_service` has been renamed to `azure.confidentialledger.certificate`.\n- `ConfidentialLedgerIdentityServiceClient` is now `ConfidentialLedgerCertificateClient`.\n- `post_ledger_entry` has been renamed to `create_ledger_entry`.\n\n### Other Changes\n- Python 2.7 is no longer supported. Please use Python version 3.7 or later.\n- Convenience poller methods added for certain long-running operations.\n- Add new supported API version: `2022-05-13`.\n\n## 1.0.0b1 (2021-05-12)\n\n- This is the initial release of the Azure Confidential Ledger library.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Microsoft Azure Confidential Ledger Client Library for Python",
"version": "1.1.1",
"project_urls": {
"Bug Reports": "https://github.com/Azure/azure-sdk-for-python/issues",
"Homepage": "https://github.com/Azure/azure-sdk-for-python",
"Source": "https://github.com/Azure/azure-sdk-python"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e7d9197b4c2328fde0e6b5979fcfcdd010d32be9897e64010fb136599e4b2fb4",
"md5": "29fe882faaa3be1ff8e9a4c17cfb6c8f",
"sha256": "f6cc82c425f3313cc02560780b066d63c56b99199bd1e35c7cb34dfbdfb033a0"
},
"downloads": -1,
"filename": "azure_confidentialledger-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "29fe882faaa3be1ff8e9a4c17cfb6c8f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 101542,
"upload_time": "2023-08-11T21:06:56",
"upload_time_iso_8601": "2023-08-11T21:06:56.882513Z",
"url": "https://files.pythonhosted.org/packages/e7/d9/197b4c2328fde0e6b5979fcfcdd010d32be9897e64010fb136599e4b2fb4/azure_confidentialledger-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c7e55e07345475de8edc74c9620145b12ce8d9f4502697947fa909f531ba419f",
"md5": "748cb35fc1a22d8fae06a8be0e16b63f",
"sha256": "8a8ee6103e6f6de8a3c5bb952542d4e4002066c7e3973a9278011c1515850a70"
},
"downloads": -1,
"filename": "azure-confidentialledger-1.1.1.zip",
"has_sig": false,
"md5_digest": "748cb35fc1a22d8fae06a8be0e16b63f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 176890,
"upload_time": "2023-08-11T21:06:54",
"upload_time_iso_8601": "2023-08-11T21:06:54.664677Z",
"url": "https://files.pythonhosted.org/packages/c7/e5/5e07345475de8edc74c9620145b12ce8d9f4502697947fa909f531ba419f/azure-confidentialledger-1.1.1.zip",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-11 21:06:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Azure",
"github_project": "azure-sdk-for-python",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "azure-confidentialledger"
}
JSON
