Step 1: Requesting a digest in QLDB - Amazon Quantum Ledger Database (Amazon QLDB)

Step 1: Requesting a digest in QLDB

Amazon QLDB provides an API to request a digest that covers the current tip of the journal in your ledger. The tip of the journal refers to the latest committed block as of the time that QLDB receives your request. You can use the AWS Management Console, an AWS SDK, or the AWS Command Line Interface (AWS CLI) to get a digest.

AWS Management Console

Follow these steps to request a digest using the QLDB console.

To request a digest (console)
  1. Sign in to the AWS Management Console, and open the Amazon QLDB console at https://console.aws.amazon.com/qldb.

  2. In the navigation pane, choose Ledgers.

  3. In the list of ledgers, select the ledger name for which you want to request a digest.

  4. Choose Get digest. The Get digest dialog box displays the following digest details:

    • Digest – The SHA-256 hash value of the digest that you requested.

    • Digest tip address – The latest block location in the journal covered by the digest that you requested. An address has the following two fields:

      • strandId – The unique ID of the journal strand that contains the block.

      • sequenceNo – The index number that specifies the location of the block within the strand.

    • Ledger – The ledger name for which you requested a digest.

    • Date – The timestamp when you requested the digest.

  5. Review the digest information. Then choose Save. You can keep the default file name, or enter a new name.

    Note

    You might notice that your digest hash and tip address values change even when you don't modify any data in your ledger. This is because the console retrieves the ledger's system catalog each time that you run a query in the PartiQL editor. This is a read transaction that gets committed to the journal and causes the latest block address to change.

    This step saves a plaintext file with contents in Amazon Ion format. The file has a file name extension of .ion.txt and contains all the digest information that was listed on the preceding dialog box. The following is an example of a digest file's contents. The order of the fields can vary depending on your browser.

    { "digest": "42zaJOfV8iGutVGNaIuzQWhD5Xb/5B9lScHnvxPXm9E=",   "digestTipAddress": "{strandId:\"BlFTjlSXze9BIh1KOszcE3\",sequenceNo:73}",   "ledger": "my-ledger",   "date": "2019-04-17T16:57:26.749Z" }
  6. Save this file where you can access it in the future. Later, you can use this file to verify a document revision against.

    Important

    The document revision that you verify later must be covered by the digest that you saved. That is, the sequence number of the document's address must be less than or equal to the sequence number of the Digest tip address.

QLDB API

You can also request a digest from your ledger by using the Amazon QLDB API with an AWS SDK or the AWS CLI. The QLDB API provides the following operation 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.

For information about requesting a digest using the AWS CLI, see the get-digest command in 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 requesting a digest, 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 GetDigest provides an example of requesting a digest from the vehicle-registration sample ledger.

To verify a document revision using the digest that you saved, proceed to Step 2: Verifying your data in QLDB.