Azure Confidential Ledger client library for Java - version 1.0.23
Azure Confidential Ledger provides a service for logging to an immutable, tamper-proof ledger. As part of the Azure Confidential Computing portfolio, Azure Confidential Ledger runs in SGX enclaves. It is built on Microsoft Research's Confidential Consortium Framework.
Source code | Package (Maven) | Product Documentation | Samples
Getting started
Prerequisites
- A Java Development Kit (JDK), version 8 or later.
- Azure Subscription
- A running instance of Azure Confidential Ledger.
- A registered user in the Confidential Ledger, typically assigned during ARM resource creation, with
Administrator
privileges.
Include the Package
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-security-confidentialledger</artifactId>
<version>1.0.23</version>
</dependency>
Authenticate the client
Using Azure Active Directory
In order to interact with the Azure Confidential Ledger service, your client must present an Azure Active Directory bearer token to the service.
The simplest way of providing a bearer token is to use the DefaultAzureCredential
authentication method by providing client secret credentials is being used in this getting started section but you can find more ways to authenticate with azure-identity.
Using a client certificate
As an alternative to Azure Active Directory, clients may choose to use a client certificate to authenticate via mutual TLS. CertificateCredential
may be used for this purpose. This is not the recommended approach for anyone new to the service.
Create LedgerBaseClient with Azure Active Directory Credential
You can authenticate with Azure Active Directory using the Azure Identity library.
To use the DefaultAzureCredential provider shown below, or other credential providers provided with the Azure SDK, please include the azure-identity
package:
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.5.4</version>
</dependency>
Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.
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.
Receipts
State changes to the Confidential Ledger are saved in a data structure called a Merkle tree. To cryptographically verify that writes were correctly saved, a Merkle proof, or receipt, can be retrieved for any transaction id.
Sub-ledgers
While most use cases will involve one ledger, we provide the sub-ledger 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 sub-ledger identifier. The Confidential Ledger will always assume a constant, service-determined sub-ledger id for entries submitted without a sub-ledger 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.
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). 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 a member identity, allowing it to perform governance actions like replacing unhealthy nodes in the Confidential Ledger, or upgrading the enclave code.
Examples
Examples can be found in samples and the samples README.
Troubleshooting
Enabling Logging
Azure SDKs for Java offer a consistent logging story to help aid in troubleshooting application errors and expedite their resolution. The logs produced will capture the flow of an application before reaching the terminal state to help locate the root issue. View the logging wiki for guidance about enabling logging.
Next steps
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.
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. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.