Add multiple verification levels to read_ledger.py (#7674)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: eddyashton <6000239+eddyashton@users.noreply.github.com>
Co-authored-by: Eddy Ashton <edashton@microsoft.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - `GET` and `HEAD` `/node/ledger-chunk?since={seqno}` and `/node/ledger-chunk/{chunk_name}` endpoints, gated by the `LedgerChunkDownload` RPC interface operator feature. See [documentation](https://microsoft.github.io/CCF/main/operations/ledger_snapshot.html#download-endpoints) for more detail.
 - `GET` and `HEAD` `/node/ledger-chunk/{chunk_name}` and `/node/snapshot/{snapshot_name}` now support the `Want-Repr-Digest` request header and return the `Repr-Digest` response header accordingly (RFC 9530). Supported algorithms are `sha-256`, `sha-384`, and `sha-512`. If no supported algorithm is requested, the server defaults to `sha-256` (#7650).
 - `ETag` and `If-None-Match` support on `GET /node/ledger-chunk/{chunk_name}`, using SHA-256 by default for the `ETag` response header. Clients can supply `If-None-Match` with `sha-256`, `sha-384`, or `sha-512` digest ETags to avoid re-downloading unchanged content (#7652).
+- `read_ledger.py` now supports multiple verification levels via the `--verification-level` option (NONE, OFFSETS, HEADERS, MERKLE, FULL), allowing users to trade off between computation cost and security guarantees. The default remains FULL verification for backward compatibility. The `--insecure-skip-verification` flag is deprecated in favor of `--verification-level=NONE`.
 
 ### Changed
 

doc/audit/python_library.rst

@@ -79,6 +79,31 @@ The ``read_ledger.py`` command line utility can be used to parse, verify the int
 
 By default, non-committed ledger files are ignored, unless the ``--uncommitted`` command line argument is specified.
 
+Verification Levels
+~~~~~~~~~~~~~~~~~~~
+
+The ``read_ledger.py`` utility supports multiple verification levels via the ``--verification-level`` option, allowing you to trade off between computation cost and security guarantees:
+
+- ``NONE``: No verification, just parse the ledger structure. Use this for quickly reading individual ledger chunks or when integrity is not a concern.
+- ``OFFSETS``: Validate that the offset table is consistent and points to valid transaction boundaries.
+- ``HEADERS``: Validate transaction headers (size, version, and flags are valid values).
+- ``MERKLE``: Validate merkle tree consistency by checking that each signature's merkle root matches the computed tree (trusts the first signature).
+- ``FULL`` (default): Full cryptographic verification including signature validation and node certificate checks.
+
+.. code-block:: bash
+
+    # Parse a single ledger chunk without verification
+    $ read_ledger.py /path/to/ledger/chunk --verification-level=NONE
+
+    # Validate structure but skip expensive cryptographic operations
+    $ read_ledger.py /path/to/ledger/dir --verification-level=HEADERS
+
+    # Full verification (default)
+    $ read_ledger.py /path/to/ledger/dir --verification-level=FULL
+
+.. note::
+    The ``--insecure-skip-verification`` flag is deprecated. Use ``--verification-level=NONE`` instead.
+
 Alternatively, ``read_ledger.py`` can parse the content of a snapshot file:
 
 .. code-block:: bash
@@ -141,6 +166,10 @@ As with ``read_ledger.py``, non-committed ledger files are ignored, unless the `
 API
 ---
 
+.. autoclass:: ccf.ledger.VerificationLevel
+    :members:
+    :undoc-members:
+
 .. autoclass:: ccf.ledger.Ledger
     :members: