DragonOS/docs/kernel/syscall/sys_capget_capset.md

sys_capget / sys_capset 设计说明

本文简要介绍 DragonOS 中 sys_capget 和 sys_capset 的设计与实现要点，覆盖版本协商、用户态数据结构、能力位集规则、以及调用流程。

来源代码：

• kernel/src/process/syscall/sys_cap_get_set.rs
• kernel/src/process/cred.rs

概述

• DragonOS 对齐 Linux 的 capability 接口，支持用户态通过 capget/capset 读取或设置进程的能力集。
• 能力集包括：
  • cap_effective (pE)：当前进程实际生效的能力
  • cap_permitted (pP)：进程被赋予的能力上限
  • cap_inheritable (pI)：可被子进程继承的能力
  • cap_bset：bounding set，限制可获得能力的上界（仅用于规则约束，不在本接口直接读写）
  • cap_ambient：ambient set（不由 capset 修改）
• 能力位宽：DragonOS 使用 64 位存储，但当前仅支持低 41 位（CAP_FULL_SET = (1<<41)-1），高位截断。

用户态数据结构与版本

与 Linux 的用户态结构对齐：

// header: cap_user_header_t
struct CapUserHeader {
    uint32_t version; // 版本号
    int32_t  pid;     // 目标进程: 0=当前进程，其他=指定pid
};

// data: cap_user_data_t 数组元素
struct CapUserData {
    uint32_t effective;
    uint32_t permitted;
    uint32_t inheritable;
}

• 版本常量：
  • _LINUX_CAPABILITY_VERSION_1 = 0x19980330
  • _LINUX_CAPABILITY_VERSION_2 = 0x20071026（已废弃）
  • _LINUX_CAPABILITY_VERSION_3 = 0x20080522
• DragonOS 内核支持版本：_KERNEL_CAPABILITY_VERSION = v3
• 每版本拷贝的 u32 数量：
  • v1: 1 组（仅低 32 位）
  • v2/v3: 2 组（低 32 位 + 高 32 位）

聚合/拆分规则：

• capset: 从用户传入的 CapUserData[0..tocopy) 聚合为 u64（高位截断到 41 位）
• capget: 根据请求版本返回 1 组或 2 组 u32（高位通过右移 32 获得）

版本协商与探测行为

• capget:
  • 若版本未知：写回 header.version 为内核支持版本（v3），并返回：
    • 若 data==NULL：返回 0（用于探测）
    • 若 data!=NULL：返回 EINVAL
  • 若版本合法：返回请求版本对应数量的 u32 组（v1:1组；v2/v3:2组），data==NULL 时也返回 0。
• capset:
  • 若版本未知：直接返回 EINVAL（不承担探测职责），与 Linux 更一致。
  • data 不能为空（NULL 返回 EFAULT）。

目标进程选择与 pid 语义

• capget:
  • pid < 0：EINVAL
  • pid == 0：使用当前进程
  • pid != 0：查找目标任务（找不到返回 ESRCH）
• capset:
  • pid < 0：EPERM（不允许负 pid 目标）
  • pid == 0 或 pid == 当前进程 pid：允许
  • pid != 当前进程 pid：EPERM（仅允许修改自身）

能力集规则（capset）

设：

• pE_old = 旧 effective
• pP_old = 旧 permitted
• pI_old = 旧 inheritable
• bset = bounding set
• pE_new, pP_new, pI_new 由用户数据聚合得出（已按 41 位掩码截断）

约束：

1. pE_new ⊆ pP_new
   若存在 pE_new 中的位不在 pP_new：EPERM

2. pP_new ⊆ pP_old（不允许提升 permitted）
   若 pP_new 中存在不属于 pP_old 的位：EPERM

3. pI_new 限幅（对齐 Linux 的 CAP_SETPCAP 与 bset 约束）

   • 如果当前进程具有 CAP_SETPCAP_BIT（在 pE_old 生效集合中）： pI_new ⊆ (pI_old ∪ pP_old) ∩ bset
     若超出：EPERM
   • 如果不具有： pI_new ⊆ (pI_old ∪ pP_old) 且 pI_new ⊆ (pI_old ∪ bset)
     任一超出：EPERM

注意：

• ambient 能力不由 capset 修改，保持不变。
• 通过克隆旧 cred，更新 pE/pP/pI 后，原子替换到 PCB（pcb.set_cred）。

流程图

capget 主要流程：

[读取 header(version,pid)]
        |
   [版本合法?]
      /     \
    否       是
    |         |
[写回 header.version=v3]     [pid 选择]
        |                     |-- pid<0 -> EINVAL
   [data==NULL?]              |-- pid==0 -> 当前进程 cred
      /     \                 |-- pid!=0 -> 查找目标任务
    是       否               |              |- 未找到 -> ESRCH
    |         |               |              |- 找到 -> 目标 cred
  返回 0     EINVAL           |
                              [拆分 e/p/i 为低/高 32 位]
                              [data==NULL?]
                                /       \
                              是         否
                               |          |
                             返回 0     写回用户缓冲区，返回 0

capset 主要流程：

[读取 header(version,pid)]
        |
   [版本合法?]
      /     \
    否       是
    |         |
  EINVAL   [data==NULL?]
              /      \
            是        否
             |         |
           EFAULT    [pid 检查]
                      |- pid<0 -> EPERM
                      |- pid!=self -> EPERM
                      |- pid==self -> [读取用户数据并聚合 pE/pP/pI]
                                      [规则1: pE_new ⊆ pP_new?]  否 -> EPERM
                                      [规则2: pP_new ⊆ pP_old?] 否 -> EPERM
                                      [规则3: pI_new 受 CAP_SETPCAP/bset 限制?] 否 -> EPERM
                                      [克隆 cred 更新 pE/pP/pI]
                                      [pcb.set_cred 原子替换]
                                      返回 0

能力位宽与掩码

聚合时对 e/p/i 应用掩码：

• mask = CAPFlags::CAP_FULL_SET.bits() = (1<<41)-1
• 高位被截断，保证跨版本兼容性与当前实现的一致性。

设计取舍与对齐

• capget 对未知版本支持“探测”语义：写回支持版本并在 data==NULL 时返回 0。
• capset 不承担探测：未知版本直接 EINVAL，更贴近 Linux 行为。
• pid 约束更严格：capset 仅允许修改当前进程，避免跨进程权限修改。
• 规则遵循 Linux 能力模型：不允许提升 permitted；effective 必须受限于 permitted；inheritable 受 CAP_SETPCAP 与 bset 限制。

未来工作

• 完善 ambient 能力与 bounding set 的更多接口（当前不在 capset 中修改 ambient）。
• 引入更完整的能力位定义与权限检查接口。
• 文档与测试用例对齐更多边界条件（如用户命名空间影响）。