software design

2026-01-25 23:48:46 +01:00
parent 2a2fba3473
commit c631110349
305 changed files with 40333 additions and 0 deletions
--- a/system_arch_final/[SEC]
+++ b/system_arch_final/[SEC]
@@ -0,0 +1,281 @@
+# Security & Safety Features
+
+**Feature Group ID:** FG-SEC  
+**Version:** 2.0  
+**Date:** 2025-01-19  
+**Scope:** Sensor Hub (Sub-Hub only)  
+**Target Platform:** ESP32-S3–based Sensor Hub, ESP-IDF v5.4
+
+## 1 Feature Overview
+
+The **Security & Safety Features** ensure that the Sensor Hub operates only with trusted firmware, protects sensitive data at rest, and guarantees confidentiality and integrity of all communications. These features are foundational and cross-cutting, supporting all other functional features (DAQ, DQC, COM, DIAG, DATA, OTA).
+
+This feature set is designed to:
+
+*   Prevent execution of unauthorized or malicious firmware
+*   Protect firmware, configuration, and machine constants stored in memory
+*   Secure all communications with cryptographic mechanisms
+*   Provide deterministic and auditable behavior in case of security violations
+
+**Technology Stack:**
+- **Secure Boot:** Secure Boot V2 (hardware-enforced)
+- **Flash Encryption:** AES-256 (hardware-accelerated)
+- **Communication Security:** Mutual TLS (mTLS) with X.509 certificates
+- **Anti-Rollback:** eFuse-based version protection
+
+## 2 Scope and Assumptions
+
+**In Scope**
+
+*   Sensor Hub (ESP32-S3–based)
+*   Boot process security
+*   Flash and external storage protection
+*   Communication security with Main Hub and peer Sensor Hubs
+*   Device identity and authentication
+
+**Out of Scope**
+
+*   Cloud server security policies
+*   User identity management
+*   Physical tamper detection hardware (optional future feature)
+
+## 3 Sub-Feature Breakdown
+
+### 3.1 F-SEC-01: Secure Boot
+
+#### Description
+
+Secure Boot ensures that only authenticated and authorized firmware images are executed on the Sensor Hub using **Secure Boot V2**. During system startup, the bootloader verifies the cryptographic signature of the firmware image before handing over execution.
+
+If verification fails, the system enters **BOOT_FAILURE** state and prevents normal operation.
+
+#### Implementation
+
+**Secure Boot V2 Configuration:**
+- **Signature Algorithm:** RSA-3072 or ECDSA-P256
+- **Verification:** Hardware-enforced (ROM bootloader)
+- **Key Storage:** Root-of-trust key in eFuse (one-time programmable)
+- **Enforcement:** Every boot (cold or warm)
+
+#### Responsibilities
+
+*   Firmware authenticity verification
+*   Root-of-trust enforcement
+*   Prevention of downgrade or rollback attacks (via eFuse anti-rollback)
+
+#### Constraints
+
+*   Must complete before any application code execution
+*   Must be enforced on every boot (cold or warm)
+*   Root-of-trust key is one-time programmable (eFuse)
+
+### 3.2 F-SEC-02: Secure Flash Storage
+
+#### Description
+
+Secure Flash Storage protects sensitive data stored in internal flash and external storage (e.g., SD card) from unauthorized access or modification using **Flash Encryption**.
+
+**Encryption Method:** AES-256 (hardware-accelerated)
+
+Sensitive data includes:
+
+*   Firmware images
+*   Machine constants
+*   Calibration data
+*   Cryptographic material
+*   Persistent diagnostics and logs
+
+#### Implementation
+
+**Flash Encryption Configuration:**
+- **Algorithm:** AES-256
+- **Mode:** Release mode (recommended for production)
+- **Key Derivation:** Hardware-based (eFuse)
+- **Transparency:** Automatic decryption on read (transparent to application)
+
+**External Storage Encryption:**
+- **SD Card:** Optional encryption for sensitive files (SWR-SEC-006)
+- **Encryption Method:** AES-256 (software-based for SD card)
+
+#### Responsibilities
+
+*   Encrypted storage of sensitive regions
+*   Access control enforcement
+*   Prevention of unauthorized read/write operations
+
+#### Constraints
+
+*   Encryption must not compromise system boot reliability
+*   Storage access must be mediated through controlled software components (e.g., DP component)
+
+### 3.3 F-SEC-03: Encrypted Communication
+
+#### Description
+
+Encrypted Communication ensures that all data exchanged between the Sensor Hub and other entities (Main Hub, peer Sensor Hubs) is protected against eavesdropping, tampering, and impersonation using **Mutual TLS (mTLS)**.
+
+This includes:
+
+*   Sensor data transmission
+*   Diagnostics reporting
+*   OTA negotiation and data transfer
+*   Configuration and machine constant updates
+
+#### Implementation
+
+**Device Identity & Authentication:**
+- **Identity:** Device-unique X.509 certificate
+- **Private Key:** Stored securely in eFuse or encrypted flash
+- **Authentication:** Mutual TLS (mTLS) for all broker communications
+- **Provisioning:** Handled via secure factory or onboarding mode
+
+**Key Lifecycle Management:**
+
+| Phase | Mechanism |
+|-------|-----------|
+| **Manufacturing** | Injection of unique device certificate and private key |
+| **Operation** | Use of TLS session keys for encrypted communication |
+| **Rotation** | Certificate rotation managed on broker/server side |
+| **Revocation** | Certificate Revocation Lists (CRL) or broker-side denylists |
+
+**Key Insight:**  
+The ESP32-S3 is optimized to handle a single device certificate efficiently. It is recommended to avoid managing large certificate chains on the device itself to conserve resources.
+
+**Certificate Constraints:**
+- **Maximum Certificate Size:** <2KB
+- **Certificate Format:** X.509 v3
+- **Key Algorithm:** RSA-2048 or ECDSA-P256
+
+#### Responsibilities
+
+*   Confidentiality of transmitted data
+*   Integrity and authenticity verification
+*   Secure session establishment
+
+#### Constraints
+
+*   Must be compatible with ESP32-S3 cryptographic capabilities
+*   Must support reconnection and key renewal mechanisms
+*   Certificate size must be optimized for ESP32-S3
+
+### 3.4 F-SEC-04: Security Violation Handling [NEW]
+
+#### Description
+
+The system detects and reports security violations with appropriate responses.
+
+**Security Violation Types:**
+- Secure boot failures
+- Authentication failures
+- Message tampering
+- Unauthorized access attempts
+- Certificate validation failures
+
+**Response Actions:**
+- Secure boot failure → BOOT_FAILURE state
+- Authentication failure → FATAL diagnostic event, connection rejection
+- Message tampering → ERROR diagnostic event (escalates to FATAL if persistent)
+- Unauthorized access → FATAL diagnostic event, access denial
+
+## 4 Functional Flow Overview
+
+### Secure Boot Flow
+
+```mermaid
+sequenceDiagram
+    participant Power as Power On
+    participant ROM as ROM Bootloader
+    participant SecureBoot as Secure Boot V2
+    participant App as Application
+    
+    Power->>ROM: System Reset
+    ROM->>SecureBoot: Load Firmware
+    SecureBoot->>SecureBoot: Verify Signature
+    alt Signature Valid
+        SecureBoot->>App: Jump to Application
+    else Signature Invalid
+        SecureBoot->>SecureBoot: Enter BOOT_FAILURE State
+    end
+```
+
+### Secure Communication Flow (mTLS)
+
+```mermaid
+sequenceDiagram
+    participant SH as Sensor Hub
+    participant Broker as Main Hub Broker
+    
+    SH->>Broker: TLS Client Hello + Certificate
+    Broker->>SH: TLS Server Hello + Certificate
+    SH->>SH: Verify Server Certificate
+    Broker->>Broker: Verify Client Certificate
+    alt Both Valid
+        SH->>Broker: TLS Session Established
+        SH->>Broker: Encrypted Data Exchange
+    else Invalid Certificate
+        SH->>SH: Reject Connection, Log FATAL
+    end
+```
+
+## 5 System SHALL Requirements (Formal)
+
+### Secure Boot Requirements
+
+*   **SR-SEC-001**: The system shall verify the authenticity of the firmware image before execution during every boot cycle using Secure Boot V2.
+*   **SR-SEC-002**: The system shall prevent execution of firmware images that fail cryptographic verification.
+*   **SR-SEC-003**: The system shall enter BOOT_FAILURE state upon secure boot verification failure.
+*   **SR-SEC-004**: The system shall protect the root-of-trust against modification (eFuse protection).
+
+### Secure Flash Storage Requirements
+
+*   **SR-SEC-005**: The system shall protect sensitive data stored in internal flash memory from unauthorized access using Flash Encryption (AES-256).
+*   **SR-SEC-006**: The system shall support encryption of sensitive data stored in external storage devices (SD card).
+*   **SR-SEC-007**: The system shall restrict access to cryptographic keys to authorized system components only.
+*   **SR-SEC-008**: The system shall ensure data integrity for stored configuration and machine constant files.
+
+### Encrypted Communication Requirements
+
+*   **SR-SEC-009**: The system shall encrypt all communication with the Main Hub using TLS 1.2 with mutual authentication (mTLS).
+*   **SR-SEC-010**: The system shall ensure integrity and authenticity of all received and transmitted messages.
+*   **SR-SEC-011**: The system shall use secure communication channels for OTA firmware updates.
+*   **SR-SEC-012**: The system shall detect and report communication security violations.
+
+### Security Violation Handling Requirements [NEW]
+
+*   **SR-SEC-013**: The system shall report security violations as FATAL diagnostic events.
+*   **SR-SEC-014**: The system shall implement eFuse-based anti-rollback to prevent downgrade attacks.
+*   **SR-SEC-015**: The system shall protect cryptographic keys during power loss and system resets.
+
+## 6 Traceability Matrix (Feature → System Requirements)
+
+| Feature ID | Related System Requirements |
+|------------|----------------------------|
+| F-SEC-01 | SR-SEC-001, SR-SEC-002, SR-SEC-003, SR-SEC-004 |
+| F-SEC-02 | SR-SEC-005, SR-SEC-006, SR-SEC-007, SR-SEC-008 |
+| F-SEC-03 | SR-SEC-009, SR-SEC-010, SR-SEC-011, SR-SEC-012 |
+| F-SEC-04 | SR-SEC-013, SR-SEC-014, SR-SEC-015 |
+
+## 7 Design & Implementation Notes (Non-Normative)
+
+*   **Secure Boot V2:** Mandatory for production deployment. Key management and signing infrastructure must be documented.
+*   **Flash Encryption:** Release mode recommended for production. Development mode available for debugging.
+*   **Key Provisioning:** Should occur during manufacturing or secure onboarding. HSM or secure signing server required.
+*   **Certificate Lifecycle:** Certificate rotation and revocation must be managed on broker/server side.
+*   **eFuse Anti-Rollback:** Version numbering strategy must be carefully defined (eFuse is one-time programmable).
+*   **Security Failures:** Should integrate with the Diagnostics & Health Monitoring feature set.
+*   **Security Features:** Must be active before any sensor data acquisition or communication begins (CFC-SEC-01).
+
+## 8 Dependencies
+
+*   **OTA Features** (for secure firmware updates)
+*   **Communication Features** (transport layer for mTLS)
+*   **Diagnostics Features** (security fault reporting)
+*   **Persistence & DP Component** (secure storage abstraction)
+*   **System Management** (BOOT_FAILURE state handling)
+
+## 9 Industrial Standards Compliance
+
+*   **Secure Boot V2:** Industry standard for production-ready industrial embedded systems
+*   **Flash Encryption:** Hardware-accelerated AES-256 (industry standard)
+*   **mTLS:** Industry standard for device authentication
+*   **X.509 Certificates:** Standard certificate format (RFC 5280)