Step 6: Verify a document in a ledger - Amazon Quantum Ledger Database (Amazon QLDB)
To request a digestTo verify a document revision

Step 6: Verify a document in a ledger

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.

With Amazon QLDB, you can efficiently verify the integrity of a document in your ledger's journal by using cryptographic hashing with SHA-256. In this example, Alexis and Brent decide to upgrade to a new model by trading in the vehicle with VIN 1N4AL11D75C109151 at a car dealership. The dealership starts the process by verifying the vehicle's ownership with the registration office.

To learn more about how verification and cryptographic hashing work in QLDB, see Data verification in Amazon QLDB.

In this step, you verify a document revision in the vehicle-registration ledger. First, you request a digest, which is returned as an output file and acts as a signature of your ledger's entire change history. Then, you request a proof for the revision relative to that digest. Using this proof, the integrity of your revision is verified if all validation checks pass.

To request a digest

  1. 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 vehicle-registration.

  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.

    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": "vehicle-registration",
  "date": "2019-04-17T16:57:26.749Z"
}

  6. Save this file where you can access it later. In the following steps, you use this file to verify a document revision against.

After you have a ledger digest saved, you can start the process of verifying a document revision against that digest.

Note

In a production use case for verification, you use a digest that was previously saved rather than doing the two tasks consecutively. As a best practice, request and save the digest as soon as a revision that you want to verify later is written to the journal.

To verify a document revision

  1. First, query your ledger for the id and blockAddress of the document 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 of the QLDB console, choose PartiQL editor.

  2. Choose the vehicle-registration ledger.

  3. In the query editor window, enter the following statement, and then choose Run.

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

  4. 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.

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

    In the navigation pane, choose Verification.

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

    • Ledger – Choose vehicle-registration.

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

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

  7. 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.

  8. 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.

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

  9. To test the verification logic, repeat steps 6–8 under To verify a document revision, but change a single character in the Digest input string. This should cause your Verify request to fail with an appropriate error message.

If you no longer need to use the vehicle-registration ledger, proceed to Step 7 (optional): Clean up resources.