Security Recovery Core Wiki

Complete documentation and reference guide

Table of Contents

Overview

Security Recovery Core (SRC) is a production-ready, hardware-assisted firmware recovery system designed to prevent permanent system bricking. It operates at the lowest level of the system, before BIOS/UEFI initialization, providing automatic firmware backup and recovery capabilities.

Quick Facts

Developer: SRC Project
Initial Release: January 15, 2024
Latest Version: 1.0.0
License: MIT License
Repository: GitHub
Written in: C, Python
Platform: Cross-platform (Linux, Windows, macOS)

What is Security Recovery Core?

Security Recovery Core is a firmware-level recovery system that provides protection against permanent system bricking. Unlike software-based recovery solutions, SRC operates at the hardware level, making it immune to operating system failures, malware attacks, and software corruption.

Key Characteristics

  • Hardware-Level Operation: Runs before BIOS/UEFI, completely independent of the operating system
  • Automatic Recovery: Detects boot failures and automatically recovers from USB device
  • Dual Backup System: Maintains exactly two rotating firmware backups
  • Cryptographic Security: All firmware images are cryptographically signed and verified
  • Cross-Platform: Works on Linux, Windows, and macOS systems
  • Data-Safe: Never modifies user data partitions, only firmware regions

Comparison to Similar Systems

Feature SRC Chromebook Recovery Dual-BIOS
Open Source ✓ Yes ✗ No Varies
Cross-Platform ✓ Yes ✗ Chrome OS only Platform-specific
USB Recovery ✓ Yes ✓ Yes ✗ No
Automatic Backup ✓ Yes ✗ No ✗ No
Cost Free Free (with device) Hardware cost

History

Development Timeline

  • January 1, 2024: Project launch. Initial architecture and design phase.
  • January 5, 2024: Interactive installation tutorial added. Beginner-friendly CLI installer implemented.
  • January 10, 2024: Platform abstraction layer completed. Generic platform implementation template added.
  • January 15, 2024: Version 1.0.0 released. First production-ready release with complete feature set.

Motivation

SRC was developed to address the growing problem of firmware bricking, particularly in embedded systems, servers, and custom hardware. The project aims to provide an open-source, cross-platform solution that can be easily integrated into various hardware platforms.

Architecture

SRC operates in a reserved region of SPI flash memory, typically 512KB at offset 0x100000. The system is organized into several key components:

System Layers

  1. Operating System / BIOS: Normal system operation layer
  2. Recovery Core Firmware: SRC monitoring and recovery layer
  3. Platform Hardware: EC/MCU, SPI flash, USB interfaces

State Machine

SRC uses a state machine to manage system states:

  • INIT: Initialization phase
  • CHECKING_BOOT: Monitoring boot process
  • BOOT_SUCCESS: Boot detected successfully
  • BOOT_FAILED: Boot failure detected
  • RECOVERING: USB recovery in progress
  • BACKUP_ACTIVE: System healthy, performing backups
  • DISABLED: Temporarily disabled
  • REMOVING: Uninstall process active

For detailed architecture information, see How It Works.

Components

Firmware Components

  • Recovery Core: Main recovery logic and state machine
  • SPI Flash Interface: Low-level SPI flash access
  • USB Mass Storage: USB device interface (FAT32)
  • Boot Detection: Multiple boot success detection methods
  • Cryptographic Module: Signature verification and hashing
  • Logging System: Tamper-resistant operation logging

CLI Tool

The security command-line tool provides user interface for:

  • Enabling/disabling recovery
  • Checking system status
  • Safely removing SRC
  • Interactive installation

USB Recovery Structure

/SECURITY_RECOVERY/
├── A.bin          # Latest firmware backup
├── B.bin          # Previous firmware backup
├── manifest.json  # Metadata (board ID, timestamps)
├── signature.sig  # Cryptographic signature
└── metadata.txt   # Human-readable backup info

Installation

Prerequisites

  • System with Embedded Controller (EC) or dedicated MCU
  • SPI flash access (typically 16MB)
  • USB Mass Storage support
  • GPIO or watchdog timer for boot detection
  • Root/Administrator access

Quick Installation

  1. Prepare USB device: sudo ./tools/create_usb_structure.sh /dev/sdb1
  2. Build firmware: cd firmware && make PLATFORM=arm
  3. Flash firmware: make flash
  4. Install CLI: cd ../cli && make install
  5. Enable protection: sudo security enable

For detailed installation instructions, see the Installation Guide.

Usage

Common Commands

Command Description
security enable Enable recovery core
security off <duration> Temporarily disable (e.g., security off 2h)
security status Display system status
security remove Safe removal with confirmations
security install Interactive installation tutorial

Duration Format

Time durations use the format: <number><unit>

  • s - seconds (e.g., 30s)
  • m - minutes (e.g., 10m)
  • h - hours (e.g., 2h)
  • d - days (e.g., 7d)

Security

Cryptographic Protection

  • Signing Algorithm: ECDSA-P256 or RSA-2048
  • Hash Function: SHA-256
  • Key Storage: Hardware-protected (TPM, secure element, or locked SPI region)

Threat Model

Protected Against:

  • Firmware corruption
  • Permanent bricking
  • Unauthorized disable
  • Malware-induced firmware modification

Not Protected Against:

  • Physical access attacks
  • Supply chain attacks
  • Advanced Persistent Threats (APTs)

For detailed security information, see the Security Documentation.

Supported Platforms

Hardware Platforms

  • ARM Cortex-M: Embedded systems, microcontrollers
  • RISC-V: Open-source ISA platforms
  • x86/x64: Generic embedded PCs
  • Custom Platforms: Via platform abstraction layer

Operating Systems

  • Linux: Full support (requires root access)
  • Windows: Full support (requires administrator privileges)
  • macOS: Support where firmware access allows (requires root)

Platform Porting

To port SRC to a new platform, implement the platform abstraction layer functions in firmware/platform/<PLATFORM>/. See firmware/platform/generic/platform.c for reference implementation.

Troubleshooting

Common Issues

  • USB Device Not Detected: Check USB format (FAT32), verify directory structure, try different USB port
  • SPI Flash Access Denied: Grant permissions (Linux: chmod 666 /dev/mtd0), run as administrator (Windows)
  • Firmware Build Fails: Verify toolchain installation, check platform support, review compiler errors
  • Recovery Core Not Starting: Verify firmware flashed correctly, check boot order, review initialization requirements

For detailed troubleshooting, see the Troubleshooting Guide.

Frequently Asked Questions

Does SRC modify my data?

No. SRC only modifies firmware regions in SPI flash memory. User data partitions are never touched.

Can malware disable SRC?

No. SRC runs at the hardware level, before the OS. Malware running in the operating system cannot disable or modify SRC.

What happens if USB is not connected?

Backups are skipped, but the system continues normally. Recovery requires USB device to be present.

Can I use SRC on servers?

Yes, if the server has EC/BMC access and SPI flash. SRC is designed for servers, embedded systems, and desktop PCs.

Is SRC compatible with Secure Boot?

SRC runs before Secure Boot, so they operate at different levels. They can coexist, but configuration may be required.

References

Documentation

Standards

External Links