From e68dc2a2fd7272464fc3f943fc4ebea33e93b7f6 Mon Sep 17 00:00:00 2001
From: Gareth <31602864+gmacf@users.noreply.github.com>
Date: Fri, 10 Nov 2023 04:22:58 +0000
Subject: [PATCH] Update Bootz proto fields with more documentation.

---
 proto/bootz.proto | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/proto/bootz.proto b/proto/bootz.proto
index 3f53ef9..fe836e8 100644
--- a/proto/bootz.proto
+++ b/proto/bootz.proto
@@ -49,6 +49,9 @@ service Bootstrap {
 // description of the chassis and its constituent control cards.
 message GetBootstrapDataRequest {
   ChassisDescriptor chassis_descriptor = 1;
+  // Describes the current state of the active control card making the
+  // bootstrap request. For fixed form factor devices, the active control
+  // card is the chassis itself.
   ControlCardState control_card_state = 2;
   // A nonce that the bootstrap server should use when signing the response.
   // Not settting this field indicates that the device is configured not to
@@ -120,7 +123,7 @@ message BootstrapDataResponse {
   // The device should set this hash as its Bootloader password.
   string boot_password_hash = 3;
   // This certificate should be used to validate the server when reporting
-  // progress.
+  // progress. The format is a base64 encoding of an x509 DER certificate.
   string server_trust_cert = 4;
   // Boot configuration is specified as structured data.
   BootConfig boot_config = 5;
@@ -149,19 +152,26 @@ message GetBootstrapDataResponse {
   // This should not be set if the device does not check for ownership
   // voucher, which is indicated by the device not setting the nonce field
   // in the GetBootstrapDataRequest message.
+  // The field is a CMS message (RFC 5652) signed by a trusted
+  // vendor Certificate Authority.
   bytes ownership_voucher = 101;
   // This should not be set if the device does not check for ownership
   // voucher, which is indicated by the device not setting the nonce field
   // in the GetBootstrapDataRequest message.
+  // The field is a CMS message (RFC 5652) which includes and is 
+  // signed by the OwnershipCertificate.
   bytes ownership_certificate = 102;
   // This is a signature of the serialized_bootstrap_data field,
   // using the ownership_certificate.
   // This should not be set if the device does not check for ownership
   // voucher, which is indicated by the device not setting the nonce field
   // in the GetBootstrapDataRequest message.
+  // The field is a base64-encoding of a signature generated using PKCS1v15 
+  // with SHA256 as the hashing algorithm.
   string response_signature = 103;
   // Contains the wire format encoding of the BootstrapDataSigned 
-  // message. This field should be verified with the response_signature.
+  // message. This field should be verified with the response_signature
+  // before unmarshalling.
   bytes serialized_bootstrap_data = 104;
 }
 
@@ -207,6 +217,9 @@ message ReportStatusRequest {
   }
   BootstrapStatus status = 1;
   string status_message = 2;
+  // Lists the current states of all control cards in the chassis.
+  // For a fixed form factor chassis, this should contain a single 
+  // state matching the chassis serial number.
   repeated ControlCardState states = 3;
 }