wolfBoot/docs/encrypted_partitions.md

External Partition Encryption in wolfBoot

Overview

wolfBoot provides encryption capabilities for external partitions to enhance firmware update security. This feature:

• Encrypts entire UPDATE partition content
• Uses pre-shared symmetric keys
• Protects SWAP partition during updates
• Integrates with existing signing process

Key Features

• Transparent encryption layer
• Secure key storage options
• Multiple encryption algorithms
• Automated encryption/decryption
• Support for incremental updates

Architecture

Encryption Layer

Application Layer
      ↓
Encryption Layer (ChaCha20/AES)
      ↓
External Flash Interface
      ↓
Physical Storage

Operation Flow

1. Write Operations:

   • Encrypt data before writing
   • Store encrypted content in flash
   • Hide actual firmware content

2. Read Operations:

   • Read encrypted data
   • Decrypt automatically
   • Return plaintext to bootloader

3. Update Process:

   • Sign firmware normally
   • Encrypt signed package
   • Store encrypted in external memory
   • Decrypt during verification

Key Management

Storage Options

Default Storage

• Internal flash temporary storage
• Protected by read-out protection
• Single-use key mechanism
• Automatic key cleanup

Advanced Storage

• Hardware Security Module (HSM)
• Trusted Platform Module (TPM)
• Custom secure storage implementation

Runtime Key Management

Key Lifecycle

1. Key reception from backend
2. Secure storage setup
3. Single update usage
4. Automatic cleanup

API Reference

Encryption Control API

// Set encryption key and nonce
int wolfBoot_set_encrypt_key(
    const uint8_t *key,    // Encryption key
    const uint8_t *nonce   // Initialization vector
);

// Clear stored encryption key
int wolfBoot_erase_encrypt_key(void);

Usage Notes

• Keys are single-use only
• Application manages key reception
• Keys cleared after update
• No encryption in direct HAL access
• Supports pre-encrypted updates

Encryption Algorithms

Supported Algorithms

Algorithm	Key Size	IV/Nonce Size	Performance	Configuration
ChaCha20-256 (default)	32 bytes	12 bytes	Fast	ENCRYPT_WITH_CHACHA=1
AES-128 CTR	16 bytes	16 bytes	Good	ENCRYPT_WITH_AES128=1
AES-256 CTR	32 bytes	16 bytes	Good	ENCRYPT_WITH_AES256=1

Configuration Options

# Enable encryption support
make ENCRYPT=1

# Select specific algorithm
make ENCRYPT=1 ENCRYPT_WITH_CHACHA=1    # Default
make ENCRYPT=1 ENCRYPT_WITH_AES128=1    # AES-128
make ENCRYPT=1 ENCRYPT_WITH_AES256=1    # AES-256

Algorithm Details

ChaCha20-256

• Default algorithm
• 32-byte key requirement
• 12-byte random nonce
• Optimized for software implementation

AES Counter Mode

• AES-128 and AES-256 support
• 16/32-byte keys respectively
• 16-byte IV requirement
• Hardware acceleration where available

Implementation Examples

ChaCha20-256 Example

1. Prepare Encryption Key

# Create key file (32B key + 12B nonce)
# Example key: "0123456789abcdef0123456789abcdef"
# Example nonce: "0123456789ab"
echo -n "0123456789abcdef0123456789abcdef0123456789ab" > enc_key.der

2. Sign and Encrypt

# Generate encrypted firmware
./tools/keytools/sign \
    --encrypt enc_key.der \
    test-app/image.bin \
    wolfboot_signing_private_key.der \
    24

Output: test-app/image_v24_signed_and_encrypted.bin

AES-256 Example

1. Prepare Encryption Key

# Create key file (32B key + 16B IV)
# Example key: "0123456789abcdef0123456789abcdef"
# Example IV: "0123456789abcdef"
echo -n "0123456789abcdef0123456789abcdef0123456789abcdef" > enc_key.der

2. Sign and Encrypt

# Generate encrypted firmware
./tools/keytools/sign \
    --aes256 \
    --encrypt enc_key.der \
    test-app/image.bin \
    wolfboot_signing_private_key.der \
    24

Output: test-app/image_v24_signed_and_encrypted.bin

Special Update Cases

Delta Updates

• Compatible with encryption
• Same workflow as full updates
• Delta image encrypted after generation
• No special configuration needed

Self-Updates

RAM Configuration

Encryption algorithm must run from RAM for self-updates:

1. Linker Script Modifications

/* Flash Section */
.text : {
    *(EXCLUDE_FILE(*chacha.o).text*)
    *(EXCLUDE_FILE(*chacha.o).rodata*)
}

/* RAM Section */
.data : {
    KEEP(*(.ramcode))
    /* ChaCha20 RAM symbols */
    KEEP(*(.text.wc_Chacha*))
    KEEP(*(.text.rotlFixed*))
    KEEP(*(.rodata.sigma))
    KEEP(*(.rodata.tau))
}

2. Build Configuration

# Use RAM-optimized linker script
make TARGET=stm32l0 ENCRYPT=1

Platform Support

• Tested on STM32L0
• Uses hal/$(TARGET)_chacha_ram.ld
• ChaCha20 recommended

Application Integration

Update Process

1. Store Encrypted Update

// Store encrypted firmware directly
ext_flash_write(address, encrypted_data, size);

2. Trigger Update

// Set encryption key before update
wolfBoot_set_encrypt_key(key, nonce);

// Trigger update
wolfBoot_update_trigger();

Example Implementation

See STM32WB Example for complete implementation.

Related Documentation

• Firmware Updates
• HAL Interface
• API Reference