github.com/google/trillian-examples@v0.0.0-20240520080811-0d40d35cef0e/binary_transparency/firmware/api/map.go (about)

     1  // Copyright 2021 Google LLC. All Rights Reserved.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  package api
    16  
    17  import "fmt"
    18  
    19  const (
    20  	// MapHTTPGetCheckpoint is the path of the URL to get a recent map checkpoint.
    21  	MapHTTPGetCheckpoint = "ftmap/v0/get-checkpoint"
    22  	// MapHTTPGetTile is the path of the URL to get a map tile at a revision.
    23  	MapHTTPGetTile = "ftmap/v0/tile"
    24  	// MapHTTPGetAggregation is the path of the URL to get aggregated FW info.
    25  	MapHTTPGetAggregation = "ftmap/v0/aggregation"
    26  
    27  	// MapPrefixStrata is the number of prefix strata in the FT map.
    28  	MapPrefixStrata = 1
    29  	// MapTreeID is the unique tree ID salted into the map's hash functions.
    30  	MapTreeID = 12345
    31  )
    32  
    33  // AggregatedFirmware represents the results of aggregating a single piece of firmware
    34  // according to the rules described in #Aggregate().
    35  type AggregatedFirmware struct {
    36  	Index uint64
    37  	Good  bool
    38  }
    39  
    40  // DeviceReleaseLog represents firmware releases found for a single device ID.
    41  // Entries are ordered by their sequence in the original log.
    42  type DeviceReleaseLog struct {
    43  	DeviceID  string
    44  	Revisions []uint64
    45  }
    46  
    47  // MapCheckpoint is a commitment to a map built from the FW Log at a given size.
    48  // The map checkpoint contains the checkpoint of the log this was built from, with
    49  // the number of entries consumed from that input log. This allows clients to check
    50  // they are seeing the same version of the log as the map was built from. This also
    51  // provides information to allow verifiers of the map to confirm correct construction.
    52  type MapCheckpoint struct {
    53  	// LogCheckpoint is the json encoded api.LogCheckpoint.
    54  	LogCheckpoint []byte
    55  	LogSize       uint64
    56  	RootHash      []byte
    57  	Revision      uint64
    58  }
    59  
    60  // MapTile is a subtree of the whole map.
    61  type MapTile struct {
    62  	// The path from the root of the map to the root of this tile.
    63  	Path []byte
    64  	// All non-empty leaves in this tile, sorted left-to-right.
    65  	Leaves []MapTileLeaf
    66  }
    67  
    68  // MapTileLeaf is a leaf value of a MapTile.
    69  // If it belongs to a leaf tile then this represents one of the values that the
    70  // map commits to. Otherwise, this leaf represents the root of the subtree in
    71  // the stratum below.
    72  type MapTileLeaf struct {
    73  	// The path from the root of the container MapTile to this leaf.
    74  	Path []byte
    75  	// The hash value being committed to.
    76  	Hash []byte
    77  }
    78  
    79  // MapInclusionProof contains the value at the requested key and the proof to the
    80  // requested Checkpoint.
    81  type MapInclusionProof struct {
    82  	Key   []byte
    83  	Value []byte
    84  	// Proof is all of the sibling hashes down the path, keyed by the bit length of the parent node ID.
    85  	// A nil entry means that this branch is empty.
    86  	// The parent node ID is used because the root does not have a sibling.
    87  	Proof [][]byte
    88  }
    89  
    90  // String returns a compact printable representation of an InclusionProof.
    91  func (l MapInclusionProof) String() string {
    92  	return fmt.Sprintf("{key: 0x%x, value: 0x%x, proof: %x}", l.Key, l.Value, l.Proof)
    93  }