RFC: Superblock Key Labels for Bcachefs

[shift]

Target: bcachefs (Kernel) & bcachefs-tools (Userspace)

Status: Request For Comments

Category: On-Disk Format Change (Backward Compatible)

Abstract

This RFC proposes adding an optional "Key Labels" field to the bcachefs superblock. This feature allows assigning human-readable strings to encryption key slots, enabling safer key rotation workflows, better identification of keys (e.g., "TPM", "Recovery", "YubiKey"), and automated management without relying on fragile slot indices.

Problem Statement

Currently, bcachefs stores encryption keys in the BCH_SB_FIELD_crypt struct. While this handles the cryptography perfectly, it lacks metadata for management. Users interacting with encrypted filesystems face several risks:

1. Ambiguous Identification: Keys are identified only by their slot index. In multi-key setups (e.g., Slot 0: User Password, Slot 1: TPM), it is impossible to distinguish them programmatically or visually without external bookkeeping.
2. Dangerous Rotation: Rotating a machine-generated key (e.g., after a BIOS update invalidates a TPM seal) requires deleting the old key. Without labels, the user must guess which slot index corresponds to the "stale" key, creating a risk of accidental lockout (deleting the recovery password).
3. Lack of Intent: There is no on-disk way to flag a key as "Backup", "Ephemeral", or "Admin", which hinders the development of higher-level management tools.

Proposed Solution

I propose adding a new, optional Type-Length-Value (TLV) field to the superblock: BCH_SB_FIELD_key_labels.

This field acts as a "Sidecar" lookup table. It maps a key_index (referencing the existing crypt field) to a fixed-width string. Since it is a new TLV type, existing kernels and tools will simply ignore it, preserving read compatibility.

On-Disk Data Structure

I propose a 64-byte aligned structure for efficiency and simplicity.

File: include/bcachefs_format.h

/* 1. New Field ID */  
enum bch_sb_field_type {  
    BCH_SB_FIELD_key_labels = 28, // Next available ID  
    BCH_SB_FIELD_MAX,  
};

/* 2. Label Entry (64 bytes) */  
struct bch_sb_key_label {  
    __u8    key_index;      // Maps to BCH_SB_FIELD_crypt  
    __u8    pad[7];         // Alignment padding (Reserved for future flags)  
    __u8    label[56];      // Null-terminated UTF-8 string  
};

/* 3. Field Container */  
struct bch_sb_field_key_labels {  
    struct bch_sb_field field;  
    struct bch_sb_key_label entries[];  
};

Rationale for 64 bytes:

• Alignment: Fits exactly into a standard cache line (64 bytes).
• Capacity: 56 bytes is sufficient for typical labels (UUIDs, "TPM_PCR0_7_2025", "YubiKey_Backup").
• Padding: 7 bytes are reserved for future flags (e.g., is_recovery, expires_at) without breaking format.

Implementation Plan

Phase 1: Header & Userspace (bcachefs-tools)

The primary implementation logic resides in userspace.

1. Update bcachefs_format.h with the new struct.
2. Modify cmd_encrypt.rs to support a --label flag in add-key.
3. Update show-super to print labels alongside key slots.
4. Implement remove-key --label <STRING> to safer deletion.

Phase 2: Kernel Module

The kernel module primarily needs to be aware of the new field type to validate the superblock, though it does not strictly need to use the labels for mounting.

1. Sync headers.
2. Add validator to ensure key_index points to a valid slot in crypt.

Use Case Example: TPM Key Rotation

A user has an encrypted root filesystem unlocked via TPM. They update their BIOS, invalidating the TPM seal.

Current Workflow (Risky):

1. User guesses that Slot 1 is the old TPM key.
2. bcachefs remove-key 1 (Hope it wasn't the backup password).
3. bcachefs add-key (New TPM key gets Slot 1... maybe).

Proposed Workflow (Safe):

1. bcachefs add-key --label "TPM_New" (Adds new key).
2. bcachefs remove-key --label "TPM_Old" (Explicitly removes the stale key).
3. bcachefs show-super confirms:
   • Slot 0: "Recovery_Password"
   • Slot 2: "TPM_New"

Compatibility

• Backward Compatibility: Old tools/kernels ignore BCH_SB_FIELD_key_labels. The filesystem mounts normally.
• Forward Compatibility: New tools on old filesystems see no labels (graceful degradation).
• Overhead: The field is optional and only consumes space if labels are defined.

Security Considerations

• Metadata Leakage: Labels are stored in the superblock. While the superblock is not encrypted, labels like "Backup_Key" or "TPM_Slot" leak minimal information about the security posture, which is generally considered acceptable for physical access scenarios (similar to LUKS header metadata). Users should be advised not to store sensitive data (like passwords) in the label itself.

[koverstreet]

Cool... I've been wanting this

No comments on the technical details yet, it's late - but please do join the IRC channel, we'll go over it and there's other people there I'll want input from