github.com/google/trillian-examples@v0.0.0-20240520080811-0d40d35cef0e/binary_transparency/firmware/cmd/ft_witness/README.md (about)

     1  # STH Witness
     2  
     3  ## Introduction
     4  
     5  Firmware Transparency Demo steps outlined under [Firmware Transparency](../../../firmware) provides a robust facility against verifying that the supplied firmware update by a FW Vendor is visible via a public log server. The supplied proofs from the log server and its verification locally by clients give sufficient confidence that the FW is discoverable, and the FT log tree is consistent, as presented to individual clients by the log server.
     6  
     7  However, the current mechanism does not ensure that the view presented to all the FT clients is a consistent view of the log, i. e. the server is not presenting a forked or a different view to a subset of clients. In the transparency world, this is known as split-view attack.
     8  
     9  ## Checkpoint Witness Feature
    10  
    11  To ensure that all clients have consistent view of the log, FT demo includes an independent witness server. The role of witness server is to maintain a reference log checkpoint, which can be requested by clients for verification.  To achieve this, the witness periodically fetches the latest log checkpoint from the log server. The latest checkpoint is compared with the already saved reference log checkpoint with the witness. If different (i. e. the log server has new entries) the witness then checks the consistency of the fetched checkpoint with its previously stored reference log checkpoint to ensure that the newly received checkpoint is consistent. Upon verification the witness overwrites its own reference log checkpoint with the newly received checkpoint. The reference log checkpoint is now made available to external clients. Reference log checkpoint of witness server is now referred as “Witness checkpoint”.
    12  
    13  Any device client receiving the Firmware Update from the firmware vendor can perform additional verification steps using the Witness Server:
    14  * Device client fetches the Witness checkpoint from Witness Server
    15  * Device client receives its Update Log checkpoint (in firmware update bundle)
    16  * Device client fetches consistency proof (CProof) between Update log checkpoint and Witness checkpoint from the log server
    17  * Using CProof, client can now locally verify the consistency between the Update log checkpoint and Witness Checkpoint, to ensure that it is not presented a forked view of the FT log tree.
    18  
    19  ## Example Workflow
    20  
    21  First run the Witness Server to periodically poll the log server to fetch its witness checkpoint:
    22  
    23  ```bash
    24  # Run the witness server using the below command
    25  go run ./cmd/ft_witness/ --logtostderr -v=2 --ws_db_file="/tmp/ws_ft.db"
    26  ```
    27  
    28  The witness server will now be running at localhost:8020. We can point the flash tool at this server to perform additional checks by passing `--witness_url=http://localhost:8020` when flashing to the device, e.g:
    29  
    30  ```bash
    31  # Use the flash tool command with the witness server argument as below
    32  * `go run ./cmd/flash_tool/ --logtostderr --update_file=/tmp/update.ota --device_storage=/tmp/dummy_device --device=dummy --witness_url=http://localhost:8020`
    33  ```