Add payload inspection to htool/libhoth

Author: stevenportley

examples/BUILD

@@ -71,6 +71,7 @@ cc_binary(
         "//protocol:authz_record",
         "//protocol:host_cmd",
         "//protocol:rot_firmware_version",
+        "//protocol:payload_info",
         "//protocol:payload_status",
         "//protocol:panic",
         "//protocol:payload_update",

examples/htool.c

@@ -764,6 +764,14 @@ static const struct htool_cmd CMDS[] = {
                 {HTOOL_POSITIONAL, .name = "source-file"}, {}},
         .func = htool_payload_update,
     },
+    {
+        .verbs = (const char*[]){"payload", "info", NULL},
+        .desc = "Display payload info for a Titan image.",
+        .params =
+            (const struct htool_param[]){
+                {HTOOL_POSITIONAL, .name = "source-file"}, {}},
+        .func = htool_payload_info,
+    },
     {.verbs = (const char*[]){"flash_spi_info", NULL},
      .desc = "Get SPI NOR flash info.",
      .params = (const struct htool_param[]){{}},

examples/htool_payload.c

@@ -14,11 +14,19 @@
 
 #include "htool_payload.h"
 
+#include <errno.h>
+#include <fcntl.h>
 #include <stdio.h>
 #include <stdlib.h>
+#include <string.h>
+#include <sys/mman.h>
+#include <sys/stat.h>
+#include <sys/types.h>
+#include <unistd.h>
 
 #include "host_commands.h"
 #include "htool.h"
+#include "protocol/payload_info.h"
 #include "protocol/payload_status.h"
 
 int htool_payload_status() {
@@ -68,3 +76,69 @@ int htool_payload_status() {
   }
   return 0;
 }
+
+int htool_payload_info(const struct htool_invocation* inv) {
+  struct libhoth_device* dev = htool_libhoth_device();
+  if (!dev) {
+    return -1;
+  }
+
+  const char* image_file;
+  if (htool_get_param_string(inv, "source-file", &image_file) != 0) {
+    return -1;
+  }
+
+  int fd = open(image_file, O_RDONLY, 0);
+  if (fd == -1) {
+    fprintf(stderr, "Error opening file %s: %s\n", image_file, strerror(errno));
+    return -1;
+  }
+  struct stat statbuf;
+  if (fstat(fd, &statbuf)) {
+    fprintf(stderr, "fstat error: %s\n", strerror(errno));
+    goto cleanup2;
+  }
+  if (statbuf.st_size > SIZE_MAX) {
+    fprintf(stderr, "file too large\n");
+    goto cleanup2;
+  }
+
+  uint8_t* image = mmap(NULL, statbuf.st_size, PROT_READ, MAP_PRIVATE, fd, 0);
+  if (image == MAP_FAILED) {
+    fprintf(stderr, "mmap error: %s\n", strerror(errno));
+    goto cleanup2;
+  }
+
+  struct payload_info info;
+  if (!libhoth_payload_info(image, statbuf.st_size, &info)) {
+    fprintf(stderr, "Failed to parse payload image.  Is this a titan image?\n");
+    goto cleanup;
+  }
+
+  printf("Payload Info:\n");
+  printf("  name: %-32s\n", info.image_name);
+  printf("  family: %u\n", info.image_family);
+  printf("  version: %u.%u.%u.%u\n", info.image_version.major,
+         info.image_version.minor, info.image_version.point,
+         info.image_version.subpoint);
+  printf("  type: %u\n", info.image_type);
+  printf("  hash: ");
+  for (int i = 0; i < sizeof(info.image_hash); i++) {
+    printf("%02x", info.image_hash[i]);
+  }
+  printf("\n");
+
+cleanup:
+  if(munmap(image, statbuf.st_size) != 0) {
+    fprintf(stderr, "munmap error: %s\n", strerror(errno));
+    return -1;
+  }
+
+cleanup2:
+  if (close(fd) != 0) {
+    fprintf(stderr, "close error: %s\n", strerror(errno));
+    return -1;
+  }
+
+  return 0;
+}

examples/htool_payload.h

@@ -17,11 +17,15 @@
 
 #include <stdint.h>
 
+#include "htool.h"
+#include "htool_cmd.h"
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 int htool_payload_status();
+int htool_payload_info(const struct htool_invocation* inv);
 
 #ifdef __cplusplus
 }

protocol/BUILD

@@ -85,6 +85,7 @@ cc_library(
     deps = [
         "//transports:libhoth_device",
         ":host_cmd",
+        ":payload_info",
     ],
 )
 
@@ -231,7 +232,6 @@ cc_library(
     ],
 )
 
-
 cc_test(
     name = "spi_proxy_test",
     srcs = ["spi_proxy_test.cc"],
@@ -243,3 +243,22 @@ cc_test(
         ":spi_proxy",
     ],
 )
+
+cc_library(
+    name = "payload_info",
+    hdrs = ["payload_info.h"],
+    srcs = ["payload_info.c"],
+)
+
+cc_test(
+    name = "payload_info_test",
+    srcs = ["payload_info_test.cc"],
+    deps = [
+        "@googletest//:gtest",
+        "@googletest//:gtest_main",
+        ":payload_info",
+    ],
+    data = [
+        "//protocol/test:test_data",
+    ],
+)

protocol/meson.build

@@ -11,6 +11,7 @@ protocol_srcs = [
   'authz_record.c',
   'progress.c',
   'spi_proxy.c',
+  'payload_info.c',
 ]
 
 incdir = include_directories('..')

protocol/payload_info.c

@@ -0,0 +1,68 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "payload_info.h"
+
+#include <string.h>
+
+const struct image_descriptor* libhoth_find_image_descriptor(const uint8_t* image,
+                                                       size_t len) {
+  for (size_t off = 0; off + sizeof(struct image_descriptor) - 1 < len;
+       off += TITAN_IMAGE_DESCRIPTOR_ALIGNMENT) {
+    int64_t magic_candidate;
+    memcpy(&magic_candidate, image + off, sizeof(magic_candidate));
+    if (magic_candidate == TITAN_IMAGE_DESCRIPTOR_MAGIC) {
+      struct image_descriptor* img_dsc =
+          (struct image_descriptor*)(image + off);
+
+      if(img_dsc->descriptor_area_size + off > len) {
+        // Image descriptor is clipped
+        return NULL;
+      }
+
+      return img_dsc;
+    }
+  }
+  return NULL;
+}
+
+bool libhoth_payload_info(const uint8_t* image, size_t len,
+                          struct payload_info* payload_info) {
+  const struct image_descriptor* descr = libhoth_find_image_descriptor(image, len);
+  if (descr == NULL) {
+    return false;
+  }
+
+  memcpy(payload_info->image_name, descr->image_name,
+         sizeof(payload_info->image_name));
+  payload_info->image_name[sizeof(payload_info->image_name)-1] = 0;
+
+  payload_info->image_family = descr->image_family;
+  payload_info->image_version.major = descr->image_major;
+  payload_info->image_version.minor = descr->image_minor;
+  payload_info->image_version.point = descr->image_point;
+  payload_info->image_version.subpoint = descr->image_subpoint;
+  payload_info->image_type = descr->image_type;
+
+  if (descr->hash_type != HASH_SHA2_256) {
+    memset(payload_info->image_hash, 0, sizeof(payload_info->image_hash));
+  } else {
+    uint32_t region_size = descr->region_count * sizeof(struct image_region);
+    struct hash_sha256* hash =
+        (struct hash_sha256*)((uint8_t*)&descr->image_regions + region_size);
+    memcpy(payload_info->image_hash, hash->hash, sizeof(hash->hash));
+  }
+
+  return true;
+}