Linux 内核 Key Retention Service 深度实战：从密钥环到 fscrypt 的全链路密钥管理

引言：为什么内核需要"密钥保管箱"

在 Linux 系统中，密钥管理是安全架构的核心支柱。文件系统加密（fscrypt）、磁盘加密（dm-crypt/LUKS）、网络认证（Kerberos/krb5）、VPN 凭证（WireGuard 预共享密钥）——这些场景都面临同一个问题：密钥不能以明文形式长时间驻留在用户态内存中，需要一个安全、持久、可审计的管理层。

Linux 内核从 2.6 时代引入的 Key Retention Service（密钥保留服务）正是为此而生。它提供了一套内核级密钥生命周期管理机制，包括创建、查找、引用计数控制、过期撤销、权限隔离等功能。更重要的是，它通过 request_key() 机制实现了密钥的"按需加载"，避免了密钥在内存中长期暴露。

然而，Key Retention Service 的文档零散且偏向内核开发者视角。本文将从实战角度，系统剖析其内部机制，涵盖核心架构、API 使用、与 fscrypt/dm-crypt 的集成、安全边界分析，以及容器化环境下的密钥隔离策略。

一、核心架构：Key、Keyring、Key Type 的三元模型

Key Retention Service 的数据由三个核心对象构成：

Key（密钥）：实际的密钥数据容器。每个 key 包含： - 序列号（serial）：全局唯一的 32 位整数标识 - 类型（type）：如 user、keyring、logon、encrypted、trusted 等 - 描述（description）：人类可读的标识字符串 - 有效负载（payload）：密钥的实际内容（对称密钥、X.509 证书、Kerberos 票据等） - 权限位（perm）：按 UID/GID/Capabilities 控制的访问权限 - UID/GID：所有者身份 - expiry：过期时间戳

Keyring（密钥环）：一种特殊的 key，其 payload 是其他 key 或 keyring 的引用集合。Keyring 构成了密钥的命名空间和组织结构。关键特性包括： - 引用语义：keyring 不复制 key，只持有引用计数 - 层次结构：keyring 可以嵌套引用其他 keyring，形成树状命名空间 - 搜索语义：从特定 keyring 出发递归搜索匹配的 key

Key Type（密钥类型）：定义了一类 key 的操作方法。每种类型实现了 key_type 结构体中的回调： - instantiate：从用户提供的数据创建 key - update：更新现有 key 的 payload - match：搜索时的匹配逻辑 - revoke：撤销 key（强制标记为不可用） - destroy：释放 key 内存

内置的 key type 包括：

类型	说明	Payload 格式
user	通用对称密钥	任意二进制
logon	任意格式字符串（不受大小限制）	任意字符串
keyring	密钥环	key 引用集合
encrypted	受保护/可刷新的密钥	加密后的 blob
trusted	基于 TPM/硬件可信根	TPM 密封的 blob
asymmetric	非对称密钥（公钥/私钥）	DER 编码的键

二、Keyring 命名空间：Linux 密钥的"文件路径"

Keyring 构成了 Linux 密钥管理的命名空间，类似文件系统的目录结构。每个进程最多持有四种 keyring：

Thread-keyring  (简写 @t)
    ↓ 继承
Process-keyring (简写 @p)
    ↓ 继承
Session-keyring (简写 @s)
    ↓ 继承
User-keyring    (简写 @u)
    ↓ 可引用
User-default (简写 @us)

四种 keyring 的核心区别：

1. User-keyring (@u) - 每个 UID 一个，由 keyctl_special 机制管理 - 默认配额：该 UID 最多可持有 200 个 key，总 payload 不超过配额（默认 20 万字符） - 搜索下限：当从进程 keyring 出发搜索时，@u 是最终回退点（fallback） - 真正的"个人钥匙串"：同 UID 所有进程共享

2. Session-keyring (@s) - 由 setsid() 创建，对会话领导者（session leader）和成员可见 - 典型用途：pam_keyinit 在用户登录时创建、在注销时销毁 - 容器隔离的天然边界——不同容器通常处于不同会话

3. Process-keyring (@p) - 同一进程组共享，子进程继承 - 通常用于服务内部分发密钥（如 NTLM 认证服务） - 线程安全的引用传递

4. Thread-keyring (@t) - 线程独享，极少使用 - 适合隔离高风险操作（如临时解密操作后立即清除）

创建自定义 keyring 的方式：

# 创建新的 session keyring（脱离当前会话）
keyctl new_session

# 创建命名 keyring 并链接到 user-keyring
keyctl newring myapp @u
keyctl setperm %keyring:myapp 0x3f3f0000

# 从当前进程 keyring 出发搜索指定 keyring
keyctl search @s myapp

权限掩码的位定义（0x3f3f0000 的解读）：

位 0-3:   possessor 权限（keyring 所有者：r/0x200, w/0x100, search/0x80, link/0x40, attr/0x20）
位 8-11:  user 权限
位 16-19: group 权限
位 24-27: other 权限

每个位的含义：
  0x01 = view    查看 key 元数据
  0x02 = read    查看 payload
  0x04 = write   修改 payload
  0x08 = search  在 keyring 中搜索
  0x10 = link    将 key 链接到 keyring
  0x20 = setattr 修改权限/过期时间

三、request_key：按需密钥加载机制

Key Retention Service 最精妙的设计之一是 .request_key 机制——它允许内核子系统在真正需要密钥时才去获取，而不是在启动时预加载。

其运行时流程如下：

文件系统/网络栈需要密钥
        ↓
instantiate_key() / request_key()
        ↓
查找 upcall: request_key()
        ↓
内核通过 call_usermodehelper_exec() 启动 /sbin/request-key
        ↓
/sbin/request-key 执行 ~/.request_key.conf 中配置的处理脚本
        ↓
脚本通过 `keyctl pipe $1` 将密钥注入内核
        ↓
内核将 key 关联到调用者（dentry super_block 等）

实战示例：Kerberos 票据缓存（krb5）的典型流程：

# 查看当前系统配置的 request-key 处理规则
cat /etc/request-key.conf

# 典型内容定义：
create krb5.tgt * * /usr/sbin/request-key-create --krb5layer %k %c %d %u %g %T
create krb5.compute_session * * /usr/sbin/request-key-create --krb5layer ...

# 手动触发 request-key（调试用）
keyctl request krb5 a:myrealm.COM

对于企业级系统，/etc/request-key.conf 是个安全关键点： - 风险：如果处理脚本具有过高权限，可能导致密钥泄露 - 最佳实践：脚本应降权执行，密钥数据通过 keyctl pipe 而非环境变量传递 - 审计：所有 request-key 日志应发送到集中审计系统

自定义 request-key 处理器的结构模板：

#!/bin/sh
# /bin/my-key-resolver — 自定义密钥加载脚本
# 参数：$1 = key_serial, $2 = uid, $3 = gid, $4 = key_type, $5 = description

KEY_SERIAL="$1"
UID="$2"

# 1. 认证调用者身份
if [ "$UID" != "0" ] && [ "$UID" != "1001" ]; then
    logger -t key-resolver "DENIED: uid=$UID requested key=$5"
    exit 1
fi

# 2. 从安全存储拉取密钥（示例：从 HashiCorp Vault）
SECRET=$(vault kv get -field=key secret/myapp/$5 2>/dev/null)
if [ -z "$SECRET" ]; then
    logger -t key-resolver "FAIL: no secret for $5"
    exit 1
fi

# 3. 注入内核（避免环境变量暴露）
echo -n "$SECRET" | keyctl pipe "$KEY_SERIAL"
unset SECRET

# 4. 设置过期时间（5分钟后自动清除）
keyctl timeout "$KEY_SERIAL" 300

exit 0

四、fscrypt 与 Key Retention Service 的深度集成

fscrypt（File System Encryption）是 ext4/F2FS/btrfs 等文件系统的原生加密框架。从 Linux 5.x 开始，fscrypt 充分利用了 Key Retention Service 的 key 机制。

4.1 fscrypt 密钥的生命周期

fscrypt setup
    ↓
生成主密钥（128/256-bit AES）
    ↓
派生每个 inode 的派生密钥
    ↓
将主密钥封装为 kernel key (fscrypt-provisioning type)
    ↓
密钥存入进程 keyring 或文件系统的 keyring
    ↓
文件读写时通过 key 派生最终加密密钥

4.2 provision key 的工作模式

fscrypt 使用 fscrypt-provisioning key type，这个类型由一个特殊认证令牌（authentication token）驱动：

# 设置文件加密密钥（root 操作）
fscrypt encrypt /data/secret --source=custom_passphrase \
    --user=alice

# 底层流程：
# 1. fscrypt 生成密钥
# 2. 通过 FS_IOC_ADD_ENCRYPTION_KEY ioctl 注入 key
# 3. 内核创建类型为 fscrypt-provisioning 的 key
# 4. key 受 user-keyring 保护
# 5. 关联到 super_block 的密钥集合

4.3 多用户场景（MUE - Multi-User Encryption）

Linux 6.x 引入了多用户加密支持，不同 UID 可以在同一文件系统上使用不同的密钥。底层通过 Session-keyring 隔离：

# 不同用户的密钥注册命令
fscrypt encrypt /shared --user=bob    # 密钥关联到 bob 的 keyring
fscrypt encrypt /shared --user=carol  # 密钥关联到 carol 的 keyring

每个 UID 的 user-keyring 在各自会话中管理密钥，即使 root 在没有权限的情况下也无法直接读取其他用户的 fscrypt 密钥——这是 Key Retention Service 权限模型的关键价值。

五、trusted key 与 TPM 集成

对于需要硬件信任根的场景，内核提供了 trusted key type，它直接对接 TPM 1.2 / TPM 2.0。

5.1 创建 sealed trusted key

# 检查 TPM 是否可用
dmesg | grep -i tpm

# 示例：创建使用 TPM sealing 的 AES-256 密钥
# 参数详解：
#   new 32     — 创建 32 字节（256-bit）新密钥
#   format=braw — 使用 tpmtools 格式
#   keyhandle=0x81010001 — TPM 持久化句柄

keyctl add trusted my_encryption_key "new 32 keyhandle=0x81010000" @u

# 查看 key 状态
keyctl print <key_serial>
# 输出示例：
# 32 bytes content:
# 01020304... (TPM-sealed blob)

5.2 encrypted key：软件层密钥刷新

encrypted key type 是 Key Retention Service 中最灵活的机制——它支持密钥的加密存储与动态刷新：

# 步骤1：创建主 master key（对称密钥，用作加密其他 key 的密钥）
keyctl add encrypted master "new trusted:master_seed 32" @u

# 步骤2：创建受 master key 保护的 encrypted key
keyctl add encrypted user_data "new enc32:master 0102..." @u

# 步骤3：使用（实际读写时用 master key 解密出 user_data 的明文）
keyctl pipe <key_serial> | openssl enc -aes-256-cbc -d

encrypted key 的核心优势： 1. 密钥失效只需撤销 master key，所有被加密 key 自动失效 2. 密钥切换（re-keying）不用通知用户态 3. 支持热更新：在不影响已加密文件的情况下轮换加密密钥 4. 与 dm-crypt 配合实现无停机密钥轮换

5.3 与 LUKS2 的协同方案

生产级 LUKS2 配置中，encrypted key + request_key 的组合很常见：

# /etc/crypttab 配置示例
# 使用密钥脚本从安全存储拉取密钥
cryptroot UUID=xxxxx - /path/to/fetch-key.sh

# fetch-key.sh：
#!/usr/bin/env bash
# 从 TPM/HSM/KMS 拉取密钥并通过 keyctl 上传
KEY=$(tpm2_unseal -c 0x81010000)
echo "$KEY" | keyctl padd user fscrypt-key @u
keyctl pipe $(keyctl search @u user fscrypt-key)

六、容器化环境下的 Key Retention Service 安全边界

容器是 Key Retention Service 最易被误用却极其关键的场景。

6.1 默认风险：容器逃逸点

当容器以 --privileged 运行或使用 CAP_SYS_ADMIN 时：

• 容器内的进程可以遍历 host 的 keyring 命名空间
• 通过 %keyring:.dns_resolver 这样的特殊 keyring 可以窃取 Kerberos 票据
• 某些容器运行时持有父 keyring 的引用而导致泄露

关键风险点：

# 在特权容器内，可以：
# 1. 读取其他容器的加密密钥
keyctl list @s  # 列出所有 session keyring 中的 key

# 2. 假设已获取 root，读取任意用户的 user-keyring
keyctl link @us_container @u_host  # 如果权限允许

6.2 安全加固最佳实践

最佳方案 1：使用 keyring 命名空间隔离（Linux 5.x+）

# 创建独立的 keyring 命名空间
unshare --keyring  # 创建新命名空间

# 或使用 clone() 的 CLONE_NEWKEYR 标志（较老内核）

最佳方案 2：显式限制密钥集合

在 Docker / containerd 中：

# docker-compose 安全配置示例
services:
  app:
    security_opt:
      - "no-new-privileges"
    cap_drop:
      - ALL
    cap_add:
      - DAC_OVERRIDE  # 仅保留必要能力
    tmpfs:
      - /run/secrets  # 密钥不落地

最佳方案 3：临时 keyring + 短过期时间

#!/bin/bash
# 容器入口脚本：在工作开始前创建隔离开的 keyring

# 创建临时隔离 keyring（脱离 session）
TEMP_KEYRING=$(keyctl newring container_ephemeral @s)
keyctl setperm "$TEMP_KEYRING" 0x3f000000  # 仅 possessor 权限

# 注入必要密钥（请求后立即删除缓存中的副本）
keyctl add user my_app_key "base64_encoded_key_here" "$TEMP_KEYRING"
keyctl timeout $(keyctl search "$TEMP_KEYRING" user my_app_key) 60  # 60秒过期

# 执行应用
exec /usr/bin/myapp "$@"

6.3 Kubernetes 中的使用模式

在 K8s 中，Secrets 通常通过 volume mount 或环境变量传递。但更安全的方式是结合 Key Retention Service：

# 使用 CSI Secret Store Driver 注入密钥环
apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: vault-keys
spec:
  provider: vault
  parameters:
    vaultAddress: "https://vault.internal:8200"
    roleName: "my-app"
    objects: |
      - objectName: "aes-key"
        secretPath: "secret/data/myapp/aes"
        secretKey: "key"
  secretObjects:
  - secretName: app-secret
    type: Opaque
    data:
    - objectName: aes-key
      key: encryption.key

七、内核源码视角：key.c 的关键调用链

理解 Key Retention Service 的内核实现有助于排查性能问题和设计调试工具。

7.1 核心流程：instantiate_and_link

用户调用 add_key(type, desc, payload, plen, keyring)
    ↓
key_alloc()        — 分配 key 结构体
key_type->instantiate()  — 类型特定初始化（如 TPM seal）
_key_link()        — 将 key 链接到目标 keyring
    ↓
更新 key->last_used_at 时间戳
原子递增 key->usage（引用计数）
    ↓
唤醒等待该 key 的进程（waitqueue）

7.2 搜索路径：key_search

用户调用 keyctl_search(keyring, type, desc)
    ↓
keyring_search()   — 遍历 keyring 中每个 key
    ↓
递归搜索引用的子 keyring（防止循环：最多 4 层深度）
    ↓
key_type->match()  — 类型特定的匹配逻辑
    ↓
检查权限位（key_permission()）
    ↓
返回第一个匹配的 key serial

7.3 过期与回收：key_gc

后台 GC 线程（system_unbound_wq）周期性扫描
    ↓
遍历所有 keyring 中的过期 key
    ↓
如果 key->expiry < current_time && !(key->perm & KEY_POS_VIEW):
    → key_revoke(key)
    → key_type->destroy(key)
    → key_put(key)             ↓
    → kmem_cache_free(key_jar)

GC 触发时机： - 每 300 秒周期性扫描（可配置 /proc/sys/kernel/keys/gc_delay） - 当 key 计数达到配额上限时强制触发 - 当 payload 总长度超限时触发 LRU 回收

7.4 监控与调试工具

# 查看系统级 key 配额参数
cat /proc/sys/kernel/keys/maxkeys      # 每个 UID 最大 key 数（默认 200）
cat /proc/sys/kernel/keys/maxbytes     # 每个 key 最大 payload（默认 20000）

# 实时查看进程持有的 key
ls -l /proc/self/key-retention

# 使用 keyctl 监控
keyctl watch <key_serial>        # 实时监控 key 的 add/revoke/link 事件（Linux 6.2+）
keyctl watch_session @s          # 在独立会话中批量监控

# /proc/keys 的字段解析
cat /proc/keys
# 输出：
# 009A I--Q---   1   3d  1f  user      alice_key  payload...
# 字段：serial, flags, timeout, perm, uid, gid, type, desc
# flags: I=instantiated, P=posessor, E=expired, R=revoked, D=dead

八、生产级部署建议

8.1 配额规划

# /etc/sysctl.d/99-key-retention.conf
# 增加金融/加密服务的 key 配额
kernel.keys.maxkeys = 10000
kernel.keys.maxbytes = 200000

# 降低普通用户的配额（减少 DoS 风险）
# 可通过 PAM 模块 pam_limits 配合实现

8.2 审计与合规

Key Retention Service 不自带审计日志，但可通过 eBPF 监控：

// bpf 程序监控 key 操作
SEC("kprobe/key_alloc")
int trace_key_alloc(struct pt_regs *ctx) {
    // 记录 key 创建事件：时间、UID、类型、描述
    bpf_perf_event_output(ctx, &events, BPF_F_CURRENT_CPU, &data, sizeof(data));
    return 0;
}

SEC("kprobe/key_permission")
int trace_key_access(struct pt_regs *ctx) {
    // 记录 key 访问尝试（包括失败的）
    return 0;
}

推荐监控策略： - 所有 key create/revoke 操作记录到 auditd - 监控 /sbin/request-key 的执行异常 - 定期扫描过期 key 比例（<80% 时告警） - 对 user-keyring 注入行为建立基线

8.3 故障排查 Checklist

问题场景	排查方向
add_key() 返回 EACCES	检查目标 keyring 的 possessor write 权限；确认进程有 keyring 的写权限
add_key() 返回 EDQUOT	超过 maxkeys 或 maxbytes 配额；执行 keyctl list @u 查看消耗
request_key 无响应	检查 /sbin/request-key 二进制是否存在；查看 /var/log/auth.log 错误
密钥在容器中泄露	确认未使用 --privileged；检查是否有 --cap-add=SYS_ADMIN
key 频繁过期导致服务中断	调整 keyctl timeout 值；检查是否有脚本在后台改权限
加密文件无法解密	检查 fscrypt keyring 状态 fscrypt status /path；确认 mount 时未丢失 key

结语

Key Retention Service 是 Linux 安全基础设施中经常被忽视却至关重要的一环。从 fscrypt 文件加密到 dm-crypt 磁盘加密，从 Kerberos 企业认证到 TPM 硬件信任根，它的影响贯穿了整个安全边界。

掌握 Key Retention Service 不仅是内核开发者的专属技能，更是系统工程师、SRE 和安全工程师的必备知识体系。在零信任架构和机密计算日益普及的今天，理解密钥在内核中的生命周期、边界和隔离机制，就是理解现代 Linux 安全的底层逻辑。

本文所述技术已在 Linux 5.10+ 内核上验证可用，关键代码路径参考自 security/keys/ 子系统和 fs/crypto/ 模块。

---

参考资料： - Linux Kernel Source: Documentation/security/keys/ - man 7 keyrings, man 1 keyctl, man 3 request_key - fscrypt documentation: Documentation/filesystems/fscrypt.rst - dm-crypt + LUKS: cryptsetup 官方文档 - TPM 2.0 key 集成: trusted-keys.txt 内核文档