Step 2: Verifying your data in QLDB

Important

End of support notice: Existing customers will be able to use Amazon QLDB until end of support on 07/31/2025. For more details, see Migrate an Amazon QLDB Ledger to Amazon Aurora PostgreSQL.

Amazon QLDB provides an API to request a proof for a specified document ID and its associated block. You must also provide the tip address of a digest that you previously saved, as described in Step 1: Requesting a digest in QLDB. You can use the AWS Management Console, an AWS SDK, or the AWS CLI to get a proof.

Then, you can use the proof returned by QLDB to verify the document revision against the saved digest, using a client-side API. This gives you control over the algorithm that you use to verify your data.

AWS Management Console

This section describes the steps to verify a document revision against a previously saved digest using the Amazon QLDB console.

Before you start, make sure that you follow the steps in Step 1: Requesting a digest in QLDB. Verification requires a previously saved digest that covers the revision that you want to verify.

To verify a document revision (console)

1. Open the Amazon QLDB console at https://console.aws.amazon.com/qldb.

2. First, query your ledger for the id and blockAddress of the revision that you want to verify. These fields are included in the document's metadata, which you can query in the committed view.

   The document id is a system-assigned unique ID string. The blockAddress is an Ion structure that specifies the block location where the revision was committed.

   In the navigation pane, choose PartiQL editor.

3. Choose the ledger name in which you want to verify a revision.

4. In the query editor window, enter a SELECT statement in the following syntax, and then choose Run.

   SELECT metadata.id, blockAddress FROM _ql_committed_table_name
   WHERE criteria

   For example, the following query returns a document from the VehicleRegistration table in the sample ledger created in Getting started with the Amazon QLDB console.

   SELECT r.metadata.id, r.blockAddress FROM _ql_committed_VehicleRegistration AS r 
   WHERE r.data.VIN = 'KM8SRDHF6EU074761'

5. Copy and save the id and blockAddress values that your query returns. Be sure to omit the double quotes for the id field. In Amazon Ion, string data types are delimited with double quotes. For example, you must copy only the alphanumeric text in the following snippet.

   "LtMNJYNjSwzBLgf7sLifrG"

6. Now that you have a document revision selected, you can start the process of verifying it.

   In the navigation pane, choose Verification.

7. On the Verify document form, under Specify the document that you want to verify, enter the following input parameters:

   • Ledger – The ledger in which you want to verify a revision.

   • Block address – The blockAddress value returned by your query in step 4.

   • Document ID – The id value returned by your query in step 4.

8. Under Specify the digest to use for verification, select the digest that you previously saved by choosing Choose digest. If the file is valid, this auto-populates all the digest fields on your console. Or, you can manually copy and paste the following values directly from your digest file:

   • Digest – The digest value from your digest file.

   • Digest tip address – The digestTipAddress value from your digest file.

9. Review your document and digest input parameters, and then choose Verify.

   The console automates two steps for you:

   1. Request a proof from QLDB for your specified document.

   2. Use the proof returned by QLDB to call a client-side API, which verifies your document revision against the provided digest. To examine this verification algorithm, see the following section QLDB API to download the code example.

   The console displays the results of your request in the Verification results card. For more information, see Verification results.

QLDB API

You can also verify a document revision by using the Amazon QLDB API with an AWS SDK or the AWS CLI. The QLDB API provides the following operations for use by application programs:

• GetDigest – Returns the digest of a ledger at the latest committed block in the journal. The response includes a 256-bit hash value and a block address.

• GetBlock – Returns a block object at a specified address in a journal. Also returns a proof of the specified block for verification if DigestTipAddress is provided.

• GetRevision – Returns a revision data object for a specified document ID and block address. Also returns a proof of the specified revision for verification if DigestTipAddress is provided.

For complete descriptions of these API operations, see the Amazon QLDB API reference.

For information about verifying data using the AWS CLI, see the AWS CLI Command Reference.

Sample application

For Java code examples, see the GitHub repository aws-samples/amazon-qldb-dmv-sample-java. For instructions on how to download and install this sample application, see Installing the Amazon QLDB Java sample application. Before doing a verification, make sure that you follow Steps 1–3 in the Java tutorial to create a sample ledger and load it with sample data.

The tutorial code in class GetRevision provides an example of requesting a proof for a document revision and then verifying that revision. This class runs the following steps:

1. Requests a new digest from the sample ledger vehicle-registration.

2. Requests a proof for a sample document revision from the VehicleRegistration table in the vehicle-registration ledger.

3. Verifies the sample revision using the returned digest and proof.