Secure Boot 和 Flash 加密分别解决什么？先用虚拟 eFuse 理解流程

export LAB_PROJECT="/absolute/path/esp32-secure-boot-encryption-lab"
export LAB_PRIVATE="/absolute/private/path/r08-models"
export LAB_QEMU="/absolute/path/qemu-system-xtensa"
umask 077
python "$LAB_PROJECT/tools/make_private_keys.py" --new-vault "$LAB_PRIVATE"

# ---- tools/private_config.py ----
# SPDX-License-Identifier: MIT
"""Generate QEMU-only security defaults outside the downloadable project.

This does not build, flash, burn fuses, or execute a device. Never use the
security-enabled outputs to flash a physical board as part of this lesson.
"""
import argparse
from pathlib import Path


def generate(mode, output, signing_key, project):
    output = output.resolve()
    if output.is_relative_to(project.resolve()) or output.exists():
        raise ValueError('Choose a new private output file outside the source project')
    secure_boot = mode in ('signed', 'combined')
    encryption = mode in ('encrypted', 'combined')
    lines = ['# PRIVATE QEMU-ONLY OVERLAY. NOT A PHYSICAL FLASHING CONFIGURATION.',
             '# CONFIG_EFUSE_VIRTUAL is not set']
    if secure_boot:
        if signing_key is None or not signing_key.resolve().is_file():
            raise ValueError('Secure boot requires an existing private RSA-3072 signing key')
        key = str(signing_key.resolve())
        if signing_key.resolve().is_relative_to(project.resolve()) or any(c in key for c in '\n\r"\\'):
            raise ValueError('Signing key must be outside the project, with an unambiguous path')
        lines += ['CONFIG_SECURE_BOOT=y', 'CONFIG_SECURE_BOOT_V2_ENABLED=y',
                  'CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES=y',
                  'CONFIG_SECURE_BOOT_FLASH_BOOTLOADER_DEFAULT=y',
                  f'CONFIG_SECURE_BOOT_SIGNING_KEY="{key}"']
    else:
        lines += ['# CONFIG_SECURE_BOOT is not set']
    if encryption:
        lines += ['CONFIG_SECURE_FLASH_ENC_ENABLED=y',
                  'CONFIG_SECURE_FLASH_ENCRYPTION_AES128=y',
                  'CONFIG_SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT=y']
    else:
        lines += ['# CONFIG_SECURE_FLASH_ENC_ENABLED is not set']
    with output.open('x') as handle:
        handle.write('\n'.join(lines) + '\n')
    output.chmod(0o600)
    return output


if __name__ == '__main__':
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument('--mode', required=True, choices=['safe', 'signed', 'encrypted', 'combined'])
    parser.add_argument('--private-output', required=True, type=Path)
    parser.add_argument('--signing-key', type=Path)
    args = parser.parse_args()
    try:
        output = generate(args.mode, args.private_output, args.signing_key,
                          Path(__file__).resolve().parents[1])
    except (ValueError, OSError) as error:
        parser.exit(2, str(error) + '\n')
    print(f'Private {args.mode} QEMU overlay written. No hardware operation executed.')

// ---- main/main.c ----
/* SPDX-License-Identifier: MIT */
/* Read-only application: security-changing paths belong to the selected SDK
 * bootloader. The lab driver runs security variants only in file-backed QEMU. */
#include <stdio.h>
#include <inttypes.h>
#include "esp_app_desc.h"
#include "esp_flash_encrypt.h"
#include "esp_ota_ops.h"
#include "esp_secure_boot.h"
#include "esp_timer.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"

void app_main(void)
{
    const esp_app_desc_t *app = esp_app_get_description();
    const esp_partition_t *running = esp_ota_get_running_partition();
    printf("R08_APP_REACHED,secure_boot=%d,flash_encryption=%d,partition=%s,offset=0x%08"PRIx32",mono_us=%"PRId64"\n",
           esp_secure_boot_enabled(), esp_flash_encryption_enabled(),
           running ? running->label : "UNKNOWN", running ? running->address : 0,
           esp_timer_get_time());
    printf("R08_APP_ID,project=%s,version=%s,elf_sha256=", app->project_name, app->version);
    for (unsigned i = 0; i < sizeof(app->app_elf_sha256); ++i) {
        printf("%02x", app->app_elf_sha256[i]);
    }
    puts("\nR08_APPLICATION_PERFORMS_NO_FUSE_WRITES");
    fflush(stdout);
    for (;;) {
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

# ---- tools/rebuild_private_app.py ----
# SPDX-License-Identifier: MIT
"""Rebuild only the application ciphertext of an owned file-backed S3 model.

This is a controlled emulator-file recovery, not physical provisioning. A QEMU
eFuse file exposes its emulated keys to its owner; it provides no secret-storage
boundary. No serial port or physical eFuse/flash command is accepted.

The original SDK first-boot in-place encryption failure remains a failed case.
This tool does not repair an unknown firmware, a real chip, or a lost real key.
"""
import argparse
import hashlib
import json
from pathlib import Path
import shutil
import subprocess
import sys


def digest(path):
    return hashlib.sha256(path.read_bytes()).hexdigest()


def rebuild(model, build, output, project):
    import esptool
    import espefuse.efuse.esp32s3.mem_definition as definitions
    if esptool.__version__ != '4.12.0':
        raise ValueError('Use the fixed esptool/espefuse/espsecure4.12.0 environment')
    definition_path = Path(definitions.__file__)
    if digest(definition_path) != '67c591e12d3ac06bc9ff3672e49f7826451fc873029f47b76fa4fd963c838d6e':
        raise ValueError('Fixed S3 block-layout definition differs')
    model, build, output = model.resolve(), build.resolve(), output.resolve()
    if any(path.is_relative_to(project.resolve()) for path in (model, output)) or output.exists():
        raise ValueError('Use an existing private model and a new private output outside the source project')
    config = json.loads((build / 'config/sdkconfig.json').read_text())
    description = json.loads((build / 'project_description.json').read_text())
    if description.get('project_name') != 'r08_security_lab' or config.get('IDF_TARGET') != 'esp32s3' or not config.get('SECURE_FLASH_ENC_ENABLED'):
        raise ValueError('Expected the fixed flash-encryption-enabled R08 S3 build')
    flash_path, efuse_path = model / 'flash.bin', model / 'efuse.bin'
    if flash_path.stat().st_size != 0x800000 or efuse_path.stat().st_size != 1024:
        raise ValueError("Unexpected model size; only this lesson QEMU backing-file format is supported")
    app_path = build / 'r08_security_lab.bin'
    app = app_path.read_bytes()
    if not 128 <= len(app) <= 0x200000 or len(app) % 16:
        raise ValueError('Unexpected fixed-partition application size/alignment')
    before = {path.name: digest(path) for path in (flash_path, efuse_path)}
    flash, efuse = flash_path.read_bytes(), efuse_path.read_bytes()
    output.mkdir(mode=0o700)
    operations = output / 'private-host-operations'
    operations.mkdir(mode=0o700)
    prefix = operations / 'known-app-prefix.bin'
    prefix.write_bytes(app[:128])
    commands, matches = [], []

    def run(arguments, name):
        command = [sys.executable, '-m', 'espsecure'] + arguments
        result = subprocess.run(command, capture_output=True, text=True)
        log = operations / (name + '.log')
        log.write_text(result.stdout + result.stderr)
        commands.append({'command': command, 'exitCode': result.returncode,
                         'log': str(log), 'logSHA256': digest(log)})
        if result.returncode:
            raise RuntimeError('Offline operation failed; private original log retained')

    # These are six known file-layout slots and four byte-order interpretations,
    # not a search over cryptographic keys. Keys already exist in the owned
    # emulator file. Match the known app prefix to reject a wrong slot/order.
    for block in definitions.EfuseDefineBlocks.BLOCKS:
        if block[2] not in range(4, 10):
            continue
        offset = sum(item[7] * 4 for item in definitions.EfuseDefineBlocks.BLOCKS if item[2] < block[2])
        raw = efuse[offset:offset + 32]
        if not any(raw):
            continue
        variants = {'raw': raw, 'reversed': raw[::-1],
                    'word-bytes-reversed': b''.join(raw[n:n + 4][::-1] for n in range(0, 32, 4)),
                    'word-order-reversed': b''.join(raw[n:n + 4] for n in range(28, -1, -4))}
        for order, key in variants.items():
            name = str(block[2]) + '-' + order
            keyfile = operations / (name + '.key')
            keyfile.write_bytes(key)
            keyfile.chmod(0o600)
            cipher = operations / (name + '-prefix.bin')
            run(['encrypt_flash_data', '--aes_xts', '--keyfile', str(keyfile), '--address', '0x20000',
                 '--output', str(cipher), str(prefix)], name)
            if cipher.read_bytes() == flash[0x20000:0x20080]:
                matches.append({'block': block[2], 'fileOffset': offset, 'byteOrder': order, 'keyfile': keyfile})
    if len(matches) != 1:
        raise ValueError('No unique known-prefix match; preserve this model and stop')
    match = matches[0]
    cipher, roundtrip = operations / 'complete-app-cipher.bin', operations / 'complete-app-roundtrip.bin'
    run(['encrypt_flash_data', '--aes_xts', '--keyfile', str(match['keyfile']), '--address', '0x20000',
         '--output', str(cipher), str(app_path)], 'encrypt-app')
    run(['decrypt_flash_data', '--aes_xts', '--keyfile', str(match['keyfile']), '--address', '0x20000',
         '--output', str(roundtrip), str(cipher)], 'decrypt-app')
    if roundtrip.read_bytes() != app or cipher.stat().st_size != len(app):
        raise ValueError('Complete known application failed exact offline round trip')
    updated = bytearray(flash)
    updated[0x20000:0x20000 + len(app)] = cipher.read_bytes()
    if updated[:0x20000] != flash[:0x20000] or updated[0x20000 + len(app):] != flash[0x20000 + len(app):]:
        raise ValueError('Unexpected change outside the fixed app interval')
    (output / 'flash.bin').write_bytes(updated)
    shutil.copyfile(efuse_path, output / 'efuse.bin')
    if before != {path.name: digest(path) for path in (flash_path, efuse_path)}:
        raise RuntimeError('Original model changed unexpectedly')
    record = {'sourceModel': str(model), 'sourceOriginalUnchanged': before,
              'fixedLayoutSourceSHA256': digest(definition_path), 'uniqueMatchingCandidate': 1,
              'selectedBlock': match['block'], 'selectedFileOffset': match['fileOffset'],
              'selectedByteOrder': match['byteOrder'], 'knownAppSHA256': digest(app_path), 'knownAppBytes': len(app),
              'exactOfflineRoundtrip': True, 'outsideAppFlashBytesUnchanged': True,
              'efuseBytesUnchanged': digest(output / 'efuse.bin') == digest(efuse_path),
              'newFlashSHA256': digest(output / 'flash.bin'), 'commands': commands,
              'scope': 'Owned emulator-file recovery only; original first-boot in-place path remains failed. No QEMU boot verdict until a separate run. No physical chip/key recovery.'}
    (output / 'offline-recovery.json').write_text(json.dumps(record, indent=2) + '\n')
    for path in output.rglob('*'):
        if path.is_file():
            path.chmod(0o600)
    return record


if __name__ == '__main__':
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument('--enrolled-model', required=True, type=Path)
    parser.add_argument('--build', required=True, type=Path)
    parser.add_argument('--private-output', required=True, type=Path)
    args = parser.parse_args()
    try:
        rebuild(args.enrolled_model, args.build, args.private_output, Path(__file__).resolve().parents[1])
    except (ValueError, RuntimeError, OSError) as error:
        parser.exit(2, str(error) + '\n')
    print('Private application ciphertext rebuilt; original files preserved. This is not a first-boot or physical security pass.')

python "$LAB_PROJECT/tools/offline_xts.py" --vault "$LAB_PRIVATE" \
  --private-output "$LAB_PRIVATE/offline-xts-case"

python "$LAB_PROJECT/tests_tools.py"
# 后续重新运行时，每次使用尚不存在的新日志目录。