Add an "EPOC" tag to the caboose

Bump hubtools version for EPOC tag in caboose
Default epoch value is zero if not otherwise specified.
Allow command line --epoch for Bootleby which may have no proper app.toml(epoch)
Make sure that ImageHeader::epoch keeps in sync with the Caboose 'EPOC' tag.
Add read-version command to fetch version and epoch.

Author: lzrd

Cargo.lock

@@ -33,6 +33,9 @@ pub enum Command {
         #[clap(short, long)]
         version: String,
 
+        #[clap(short, long)]
+        epoch: Option<String>,
+
         #[clap(short, long)]
         force: bool,
 
@@ -44,6 +47,8 @@ pub enum Command {
         #[clap(short, long)]
         force: bool,
     },
+    /// Read version and epoch values from an image.
+    ReadVersion,
     /// Replaces the binary image within an archive with a different binary
     /// image, supplied on the command line as a raw (BIN) file.
     ///
@@ -93,6 +98,8 @@ pub enum Command {
         board: String,
         /// Git has for the hubris archive
         gitc: String,
+        /// Epoch for rollback protection
+        epoch: Option<u32>,
     },
 }
 
@@ -129,6 +136,7 @@ fn main() -> Result<()> {
         }
         Command::WriteCaboose {
             version,
+            epoch,
             force,
             no_defaults,
         } => {
@@ -143,9 +151,10 @@ fn main() -> Result<()> {
                 }
             }
             if no_defaults {
-                archive.write_version_to_caboose(&version)?;
+                archive.write_version_to_caboose(&version, epoch.as_ref())?;
             } else {
-                archive.write_default_caboose(Some(&version))?;
+                archive
+                    .write_default_caboose(Some(&version), epoch.as_ref())?;
             }
             archive.overwrite()?;
         }
@@ -159,6 +168,42 @@ fn main() -> Result<()> {
             archive.erase_caboose()?;
             archive.overwrite()?;
         }
+        Command::ReadVersion => {
+            // Some images are missing an ImageHeader (old bootleby images),
+            // or have no caboose, or have no caboose with an `EPOC` value.
+            // The default epoch value is zero.
+
+            let (version, caboose_epoch) =
+                if let Ok(caboose) = archive.read_caboose() {
+                    let version = match caboose.version() {
+                        Ok(vers) => {
+                            std::str::from_utf8(vers).unwrap_or("").to_string()
+                        }
+                        Err(_) => "".to_string(),
+                    };
+                    let epoch =
+                        std::str::from_utf8(caboose.epoch().unwrap_or(&[b'0']))
+                            .unwrap_or("0")
+                            .parse::<u32>()
+                            .unwrap_or(0u32);
+                    (version.clone(), epoch)
+                } else {
+                    // No caboose
+                    ("".to_string(), 0u32)
+                };
+            let header_epoch = archive.image.image_header_epoch().unwrap_or(0);
+
+            println!("Version: \"{}\"", version);
+            if header_epoch == caboose_epoch {
+                println!("Epoch: {}", header_epoch);
+            } else {
+                println!("Epoch: {}", 0u32);
+                bail!(format!(
+                    "Epoch mismatch: ImageHeader({}) != Caboose({})",
+                    header_epoch, caboose_epoch
+                ));
+            }
+        }
         Command::ReplaceImage { image } => {
             let contents = std::fs::read(&image).with_context(|| {
                 format!("reading image file {}", image.display())
@@ -202,8 +247,10 @@ fn main() -> Result<()> {
             board,
             name,
             gitc,
+            epoch,
         } => {
-            let archive = bootleby_to_archive(elf_file, board, name, gitc)?;
+            let archive =
+                bootleby_to_archive(elf_file, board, name, gitc, epoch)?;
 
             std::fs::write(&args.archive, archive)?;
 

hubedit/src/main.rs

@@ -1,6 +1,6 @@
 [package]
 name = "hubtools"
-version = "0.4.6"
+version = "0.4.7"
 edition = "2021"
 rust-version = "1.66"
 

hubtools/Cargo.toml

@@ -57,7 +57,7 @@ fn header_offset(elf: &object::read::File) -> Result<u64, Error> {
     Err(Error::MissingHeader)
 }
 
-fn add_image_header(path: PathBuf) -> Result<Vec<u8>, Error> {
+fn add_image_header(path: PathBuf, epoch: u32) -> Result<Vec<u8>, Error> {
     // We can't construct an ELF object from a mutable reference so we
     // work on the file path and return the bytes
     let mut f = std::fs::read(path).map_err(Error::FileReadError)?;
@@ -73,8 +73,9 @@ fn add_image_header(path: PathBuf) -> Result<Vec<u8>, Error> {
     drop(elf);
 
     let header = header::ImageHeader {
-        magic: 0x64_CE_D6_CA,
         total_image_len: len as u32,
+        epoch,
+        ..Default::default()
     };
 
     header
@@ -89,8 +90,11 @@ pub fn bootleby_to_archive(
     board: String,
     name: String,
     gitc: String,
+    epoc: Option<u32>,
 ) -> Result<Vec<u8>, Error> {
-    let f = add_image_header(path)?;
+    let image_header_epoch: u32 = epoc.unwrap_or(0u32);
+    let epoc = image_header_epoch.to_string();
+    let f = add_image_header(path, image_header_epoch)?;
 
     let img = RawHubrisImage::from_generic_elf(&f)?;
 
@@ -103,8 +107,9 @@ pub fn bootleby_to_archive(
         name = "{}"
         board = "{}"
         chip = "lpc55"
+        epoch = {}
         "#,
-        name, board
+        name, board, epoc
     );
 
     archive.add_file("elf/kernel", &f)?;

hubtools/src/bootleby.rs

@@ -48,6 +48,10 @@ impl Caboose {
         self.get_tag(tags::SIGN)
     }
 
+    pub fn epoch(&self) -> Result<&[u8], CabooseError> {
+        self.get_tag(tags::EPOC)
+    }
+
     fn get_tag(&self, tag: [u8; 4]) -> Result<&[u8], CabooseError> {
         use tlvc::TlvcReader;
         let mut reader = TlvcReader::begin(self.as_slice())
@@ -85,6 +89,7 @@ pub(crate) mod tags {
     pub(crate) const NAME: [u8; 4] = *b"NAME";
     pub(crate) const VERS: [u8; 4] = *b"VERS";
     pub(crate) const SIGN: [u8; 4] = *b"SIGN";
+    pub(crate) const EPOC: [u8; 4] = *b"EPOC";
 }
 
 #[derive(Debug, Default, Clone, PartialEq, Eq)]
@@ -94,6 +99,7 @@ pub struct CabooseBuilder {
     name: Option<String>,
     version: Option<String>,
     sign: Option<String>,
+    epoch: Option<String>,
 }
 
 impl CabooseBuilder {
@@ -122,6 +128,22 @@ impl CabooseBuilder {
         self
     }
 
+    pub fn epoch<S: Into<String>>(mut self, epoch: S) -> Self {
+        let epoch: String = epoch.into();
+        match epoch.len() {
+            0 => self.epoch = Some("0".to_string()),
+            _ => {
+                if let Ok(epoch) = epoch.parse::<u32>() {
+                    self.epoch = Some(format!("{epoch}").to_owned());
+                } else {
+                    // Any invalid value is treated as zero
+                    self.epoch = Some("0".to_string())
+                }
+            }
+        }
+        self
+    }
+
     pub fn build(self) -> Caboose {
         let mut pieces = Vec::new();
         for (tag, maybe_value) in [
@@ -130,6 +152,7 @@ impl CabooseBuilder {
             (tags::NAME, self.name),
             (tags::VERS, self.version),
             (tags::SIGN, self.sign),
+            (tags::EPOC, self.epoch),
         ] {
             let Some(value) = maybe_value else {
                 continue;
@@ -166,6 +189,10 @@ mod tests {
             caboose.version(),
             Err(CabooseError::MissingTag { tag: tags::VERS })
         );
+        assert_eq!(
+            caboose.epoch(),
+            Err(CabooseError::MissingTag { tag: tags::EPOC })
+        );
     }
 
     #[test]
@@ -184,6 +211,10 @@ mod tests {
             caboose.version(),
             Err(CabooseError::MissingTag { tag: tags::VERS })
         );
+        assert_eq!(
+            caboose.epoch(),
+            Err(CabooseError::MissingTag { tag: tags::EPOC })
+        );
     }
 
     #[test]
@@ -193,10 +224,38 @@ mod tests {
             .board("bar")
             .name("fizz")
             .version("buzz")
+            .epoch("")
             .build();
         assert_eq!(caboose.git_commit(), Ok("foo".as_bytes()));
         assert_eq!(caboose.board(), Ok("bar".as_bytes()));
         assert_eq!(caboose.name(), Ok("fizz".as_bytes()));
         assert_eq!(caboose.version(), Ok("buzz".as_bytes()));
+        assert_eq!(caboose.epoch(), Ok("0".as_bytes()));
+    }
+
+    #[test]
+    fn builder_can_make_caboose_with_non_zero_epoch() {
+        let caboose = CabooseBuilder::default().epoch("1234567890").build();
+        assert_eq!(caboose.epoch(), Ok("1234567890".as_bytes()));
+    }
+
+    #[test]
+    fn builder_will_normalize_empty_epoch() {
+        let caboose = CabooseBuilder::default().epoch("").build();
+        assert_eq!(caboose.epoch(), Ok("0".as_bytes()));
+    }
+
+    #[test]
+    fn builder_will_normalize_short_epoch() {
+        let caboose = CabooseBuilder::default().epoch("1234").build();
+        assert_eq!(caboose.epoch(), Ok("1234".as_bytes()));
+    }
+
+    #[test]
+    fn builder_will_convert_u64_epoch_to_zero() {
+        let caboose = CabooseBuilder::default()
+            .epoch("4294967296") // u32::MAX_VALUE + 1
+            .build();
+        assert_eq!(caboose.epoch(), Ok("0".as_bytes()));
     }
 }