Add get-security-info command (#758)

JurajSadel · jessebraham · web-flow · commit 158764f82d85 · 2025-02-13T12:50:46.000Z
* Add get-security-info command

* changelog

* fix clippy

* reviews

* Update HIL for get_security_info

* update changelog

* reviews

* HIL

* reviews

* fmt

* revert

* refactor error handling

* rebase and update S2 response length check

* fix S2 when no-stub flag is used, address comments

* Hack around strange command responses, make security info work with and without stub

---------

Co-authored-by: Jesse Braham &lt;jesse@beta7.io&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - Split the baudrate for connecting and monitorinig in `flash` subcommand (#737)
 
+- `board-info` now prints `Security information`. (#758)
+
 ### Fixed
 
 - Update the app image SHA in the correct location for padded images (#715)
diff --git a/espflash/src/cli/mod.rs b/espflash/src/cli/mod.rs
@@ -373,6 +373,13 @@ pub fn board_info(args: &ConnectArgs, config: &Config) -> Result<()> {
     let mut flasher = connect(args, config, true, true)?;
     print_board_info(&mut flasher)?;
 
+    if flasher.chip() != Chip::Esp32 {
+        let security_info = flasher.get_security_info()?;
+        println!("{security_info}");
+    } else {
+        println!("Security features: None");
+    }
+
     Ok(())
 }
 
diff --git a/espflash/src/command.rs b/espflash/src/command.rs
@@ -191,6 +191,7 @@ pub enum Command<'a> {
     },
     RunUserCode,
     FlashDetect,
+    GetSecurityInfo,
 }
 
 impl Command<'_> {
@@ -219,6 +220,7 @@ impl Command<'_> {
             Command::ReadFlash { .. } => CommandType::ReadFlash,
             Command::RunUserCode { .. } => CommandType::RunUserCode,
             Command::FlashDetect => CommandType::FlashDetect,
+            Command::GetSecurityInfo => CommandType::GetSecurityInfo,
         }
     }
 
@@ -421,6 +423,9 @@ impl Command<'_> {
             Command::FlashDetect => {
                 write_basic(writer, &[], 0)?;
             }
+            Command::GetSecurityInfo => {
+                write_basic(writer, &[], 0)?;
+            }
         };
         Ok(())
     }
diff --git a/espflash/src/connection/mod.rs b/espflash/src/connection/mod.rs
@@ -441,12 +441,20 @@ impl Connection {
                             RomErrorKind::from(response.error),
                         )))
                     } else {
-                        Ok(response.value)
-                    }
-                }
-                _ => {
-                    continue;
+                        // Check if the response is a Vector and strip header (first 8 bytes)
+                        // https://github.com/espressif/esptool/blob/749d1ad/esptool/loader.py#L481
+                        let modified_value = match response.value {
+                            CommandResponseValue::Vector(mut vec) if vec.len() >= 8 => {
+                                vec = vec[8..][..response.return_length as usize].to_vec();
+                                CommandResponseValue::Vector(vec)
+                            }
+                            _ => response.value, // If not Vector, return as is
+                        };
+
+                        Ok(modified_value)
+                    };
                 }
+                _ => continue,
             }
         }
         Err(Error::Connection(ConnectionError::ConnectionFailed))
diff --git a/espflash/src/error.rs b/espflash/src/error.rs
@@ -2,7 +2,7 @@
 
 #[cfg(feature = "serialport")]
 use std::fmt::{Display, Formatter};
-use std::io;
+use std::{array::TryFromSliceError, io};
 
 use miette::Diagnostic;
 #[cfg(feature = "serialport")]
@@ -202,6 +202,9 @@ pub enum Error {
     #[diagnostic(code(espflash::dialoguer_error))]
     DialoguerError(#[from] dialoguer::Error),
 
+    #[error(transparent)]
+    TryFromSlice(#[from] TryFromSliceError),
+
     #[error("Internal Error")]
     InternalError,
 
@@ -210,6 +213,10 @@ pub enum Error {
 
     #[error("Failed to parse partition table")]
     Partition(#[from] esp_idf_part::Error),
+
+    #[error("Invalid response: {0}")]
+    #[diagnostic(code(espflash::invalid_response))]
+    InvalidResponse(String),
 }
 
 #[cfg(feature = "serialport")]
diff --git a/espflash/src/flasher/mod.rs b/espflash/src/flasher/mod.rs
@@ -6,7 +6,7 @@
 
 #[cfg(feature = "serialport")]
 use std::{borrow::Cow, io::Write, path::PathBuf, thread::sleep, time::Duration};
-use std::{fs, path::Path, str::FromStr};
+use std::{collections::HashMap, fmt, fs, path::Path, str::FromStr};
 
 use esp_idf_part::PartitionTable;
 #[cfg(feature = "serialport")]
@@ -47,6 +47,176 @@ use crate::{
 #[cfg(feature = "serialport")]
 pub(crate) mod stubs;
 
+/// Security Info Response containing
+#[derive(Debug)]
+pub struct SecurityInfo {
+    /// 32 bits flags
+    pub flags: u32,
+    /// 1 byte flash_crypt_cnt
+    pub flash_crypt_cnt: u8,
+    /// 7 bytes key purposes
+    pub key_purposes: [u8; 7],
+    /// 32-bit word chip id
+    pub chip_id: Option<u32>,
+    /// 32-bit word eco version
+    pub eco_version: Option<u32>,
+}
+
+impl SecurityInfo {
+    fn security_flag_map() -> HashMap<&'static str, u32> {
+        HashMap::from([
+            ("SECURE_BOOT_EN", 1 << 0),
+            ("SECURE_BOOT_AGGRESSIVE_REVOKE", 1 << 1),
+            ("SECURE_DOWNLOAD_ENABLE", 1 << 2),
+            ("SECURE_BOOT_KEY_REVOKE0", 1 << 3),
+            ("SECURE_BOOT_KEY_REVOKE1", 1 << 4),
+            ("SECURE_BOOT_KEY_REVOKE2", 1 << 5),
+            ("SOFT_DIS_JTAG", 1 << 6),
+            ("HARD_DIS_JTAG", 1 << 7),
+            ("DIS_USB", 1 << 8),
+            ("DIS_DOWNLOAD_DCACHE", 1 << 9),
+            ("DIS_DOWNLOAD_ICACHE", 1 << 10),
+        ])
+    }
+
+    fn get_security_flag_status(&self, flag_name: &str) -> bool {
+        if let Some(&flag) = Self::security_flag_map().get(flag_name) {
+            (self.flags & flag) != 0
+        } else {
+            false
+        }
+    }
+}
+
+impl TryFrom<&[u8]> for SecurityInfo {
+    type Error = crate::error::Error;
+
+    fn try_from(bytes: &[u8]) -> Result<Self, Self::Error> {
+        let esp32s2 = bytes.len() == 12;
+
+        if bytes.len() < 12 {
+            return Err(Error::InvalidResponse(format!(
+                "expected response of at least 12 bytes, received {} bytes",
+                bytes.len()
+            )));
+        }
+
+        // Parse response bytes
+        let flags = u32::from_le_bytes(bytes[0..4].try_into()?);
+        let flash_crypt_cnt = bytes[4];
+        let key_purposes: [u8; 7] = bytes[5..12].try_into()?;
+
+        let (chip_id, eco_version) = if esp32s2 {
+            (None, None) // ESP32-S2 doesn't have these values
+        } else {
+            if bytes.len() < 20 {
+                return Err(Error::InvalidResponse(format!(
+                    "expected response of at least 20 bytes, received {} bytes",
+                    bytes.len()
+                )));
+            }
+            let chip_id = u32::from_le_bytes(bytes[12..16].try_into()?);
+            let eco_version = u32::from_le_bytes(bytes[16..20].try_into()?);
+            (Some(chip_id), Some(eco_version))
+        };
+
+        Ok(SecurityInfo {
+            flags,
+            flash_crypt_cnt,
+            key_purposes,
+            chip_id,
+            eco_version,
+        })
+    }
+}
+
+impl fmt::Display for SecurityInfo {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let key_purposes_str = self
+            .key_purposes
+            .iter()
+            .map(|b| format!("{}", b))
+            .collect::<Vec<_>>()
+            .join(", ");
+
+        writeln!(f, "\nSecurity Information:")?;
+        writeln!(f, "=====================")?;
+        writeln!(f, "Flags: {:#010x} ({:b})", self.flags, self.flags)?;
+        writeln!(f, "Key Purposes: [{}]", key_purposes_str)?;
+
+        // Only print Chip ID if it's Some(value)
+        if let Some(chip_id) = self.chip_id {
+            writeln!(f, "Chip ID: {}", chip_id)?;
+        }
+
+        // Only print API Version if it's Some(value)
+        if let Some(api_version) = self.eco_version {
+            writeln!(f, "API Version: {}", api_version)?;
+        }
+
+        // Secure Boot
+        if self.get_security_flag_status("SECURE_BOOT_EN") {
+            writeln!(f, "Secure Boot: Enabled")?;
+            if self.get_security_flag_status("SECURE_BOOT_AGGRESSIVE_REVOKE") {
+                writeln!(f, "Secure Boot Aggressive key revocation: Enabled")?;
+            }
+
+            let revoked_keys: Vec<_> = [
+                "SECURE_BOOT_KEY_REVOKE0",
+                "SECURE_BOOT_KEY_REVOKE1",
+                "SECURE_BOOT_KEY_REVOKE2",
+            ]
+            .iter()
+            .enumerate()
+            .filter(|(_, &key)| self.get_security_flag_status(key))
+            .map(|(i, _)| format!("Secure Boot Key{} is Revoked", i))
+            .collect();
+
+            if !revoked_keys.is_empty() {
+                writeln!(
+                    f,
+                    "Secure Boot Key Revocation Status:\n  {}",
+                    revoked_keys.join("\n  ")
+                )?;
+            }
+        } else {
+            writeln!(f, "Secure Boot: Disabled")?;
+        }
+
+        // Flash Encryption
+        if self.flash_crypt_cnt.count_ones() % 2 != 0 {
+            writeln!(f, "Flash Encryption: Enabled")?;
+        } else {
+            writeln!(f, "Flash Encryption: Disabled")?;
+        }
+
+        let crypt_cnt_str = "SPI Boot Crypt Count (SPI_BOOT_CRYPT_CNT)";
+        writeln!(f, "{}: 0x{:x}", crypt_cnt_str, self.flash_crypt_cnt)?;
+
+        // Cache Disabling
+        if self.get_security_flag_status("DIS_DOWNLOAD_DCACHE") {
+            writeln!(f, "Dcache in UART download mode: Disabled")?;
+        }
+        if self.get_security_flag_status("DIS_DOWNLOAD_ICACHE") {
+            writeln!(f, "Icache in UART download mode: Disabled")?;
+        }
+
+        // JTAG Status
+        if self.get_security_flag_status("HARD_DIS_JTAG") {
+            writeln!(f, "JTAG: Permanently Disabled")?;
+        } else if self.get_security_flag_status("SOFT_DIS_JTAG") {
+            writeln!(f, "JTAG: Software Access Disabled")?;
+        }
+
+        // USB Access
+        if self.get_security_flag_status("DIS_USB") {
+            writeln!(f, "USB Access: Disabled")?;
+        }
+
+        Ok(())
+    }
+}
+
 /// Supported flash frequencies
 ///
 /// Note that not all frequencies are supported by each target device.
@@ -1038,6 +1208,29 @@ impl Flasher {
             })
     }
 
+    /// Get security info
+    pub fn get_security_info(&mut self) -> Result<SecurityInfo, Error> {
+        self.connection
+            .with_timeout(CommandType::GetSecurityInfo.timeout(), |connection| {
+                let response = connection.command(crate::command::Command::GetSecurityInfo)?;
+                // Extract raw bytes and convert them into `SecurityInfo`
+                if let crate::connection::CommandResponseValue::Vector(data) = response {
+                    // HACK: Not quite sure why there seem to be 4 extra bytes at the end of the
+                    //       response when the stub is not being used...
+                    let end = if self.use_stub {
+                        data.len()
+                    } else {
+                        data.len() - 4
+                    };
+                    SecurityInfo::try_from(&data[..end])
+                } else {
+                    Err(Error::InvalidResponse(
+                        "response was not a vector of bytes".into(),
+                    ))
+                }
+            })
+    }
+
     pub fn change_baud(&mut self, speed: u32) -> Result<(), Error> {
         debug!("Change baud to: {}", speed);
 
diff --git a/espflash/tests/scripts/board-info.sh b/espflash/tests/scripts/board-info.sh
@@ -1,7 +1,23 @@
 #!/usr/bin/env bash
 
+# Run the command and capture output and exit code
 result=$(espflash board-info)
+exit_code=$?
 echo "$result"
-if [[ $? -ne 0 || ! "$result" =~ "esp32" ]]; then
-    exit 1
+
+# Extract chip type
+chip_type=$(awk -F': *' '/Chip type:/ {print $2}' <<< "$result" | awk '{print $1}')
+
+if [[ "$chip_type" == "esp32" ]]; then
+    # ESP32 doesn't support get_security_info
+    [[ $exit_code -eq 0 && "$result" =~ "Security features: None" ]] || {
+        echo "Expected Security features: None"
+        exit 1
+    }
+else
+    # Non-ESP32 should contain required info
+    [[ $exit_code -eq 0 && "$result" =~ "Security Information:" && "$result" =~ "Flags" ]] || {
+        echo "Expected 'Security Information:' and 'Flags' in output but did not find them"
+        exit 1
+    }
 fi

Original file line number	Diff line number	Diff line change
`@@ -191,6 +191,7 @@ pub enum Command<'a> {`
`191`	`191`	`},`
`192`	`192`	`RunUserCode,`
`193`	`193`	`FlashDetect,`
	`194`	`+ GetSecurityInfo,`
`194`	`195`	`}`
`195`	`196`
`196`	`197`	`impl Command<'_> {`
`@@ -219,6 +220,7 @@ impl Command<'_> {`
`219`	`220`	`Command::ReadFlash { .. } => CommandType::ReadFlash,`
`220`	`221`	`Command::RunUserCode { .. } => CommandType::RunUserCode,`
`221`	`222`	`Command::FlashDetect => CommandType::FlashDetect,`
	`223`	`+ Command::GetSecurityInfo => CommandType::GetSecurityInfo,`
`222`	`224`	`}`
`223`	`225`	`}`
`224`	`226`
`@@ -421,6 +423,9 @@ impl Command<'_> {`
`421`	`423`	`Command::FlashDetect => {`
`422`	`424`	`write_basic(writer, &[], 0)?;`
`423`	`425`	`}`
	`426`	`+ Command::GetSecurityInfo => {`
	`427`	`+ write_basic(writer, &[], 0)?;`
	`428`	`+ }`
`424`	`429`	`};`
`425`	`430`	`Ok(())`
`426`	`431`	`}`