Advanced Topics

Crytographic Verification

One of the most powerful features of QLDB is the ability to crytographically verify that a document revision (e.g. the state of a record at a particular point in time). This proves that the record exists at the same location in the journal and has not been altered in any way, since it was first written.

Step 1 - Get Digest

The first step to carry out verification is to retrieve the digest. This can be carried out using the getDigest method on the QLDB service in the AWS SDK. This is also available on the CLI:

aws qldb get-digest --name qldb-guide

This method returns the digest of the ledger at the latest committed block in the journal. An example response is shown below:

    "DigestTipAddress": {
        "IonText": "{strandId:\"GadsaE07Jm09FAL3odPrDx\",sequenceNo:277}"
    "Digest": "4zXgZ/7+e0jKpxhnNcF7ydYGMoEsRbOH84QbVz40w2w="

The response includes the SHA-256 hash value representing the digest, and a block address of the latest block location covered by the digest. This consists of the strand ID and the sequence number for the location in the chain.

Step 2 - Get Block Address and ID

The second step is to get hold of the block address and the document ID for the specific document revision to be verified. An example PartiQL statement is shown below:

SELECT blockAddress, FROM _ql_committed_{TABLE_NAME} WHERE data.{ID} = ?

Step 3 - Get Revision

The third step is to retrieve a Proof object for the specific document revision. This can be carried out using the getRevision method on the QLDB service in the AWS SDK. This is also available on the CLI. This method passes in the following parameters in the request body to the specified ledger:

   "BlockAddress": { 
      "IonText": "string"
   "DigestTipAddress": { 
      "IonText": "string"
   "DocumentId": "string"

The BlockAddress and DocumentID are the values retrieved in Step 2, and the DigestTipAddress is retrieved in Step 1.

If successful, the service returns a Proof object in Amazon ION format, and the document revision data object in Amazon ION format.

The Proof object contains the list of hashes required to recalculate the specified digest using a Merkle tree, starting with the specified document revision. An example of a Proof object is shown below:


An example of the document revision object is shown below:


Step 4 - Recalculate Digest

The next step is to build up a candidate digest to represent the entire ledger by using the Proof hashes.

This starts off by taking the hash from the document revision, and pairing it with the first hash in the Proof hashes list. These two hash values are sorted, concatenated, and then a new hash value generated from the concatenated values. This essentially uses a reduce function, by carrying out this action on each element in the hashes list, until only a single hash value remains. This is the recalculated digest.

Step 5 - Compare Digest Values

The final step is to compared the recalculated digest from the previous step, with the digest value returned in the first step. If both values are the same, then we have successfully verified the record.


At Reinvent 2019, AWS announcing the private preview of QLDB Streaming

Streaming Preview