1. 概述

1.1 沙箱机制定义

鸿蒙系统沙箱（Sandbox）是一种安全隔离机制，通过mount命名空间和控制组（cgroup）技术，为系统服务和应用创建独立的运行环境，限制其对系统资源的访问权限。
为什么要有沙箱这个概念：
为了把每个应用关进“小黑屋”，防止它偷窥、篡改、破坏别人或系统的数据与资源。

1. 数据隔离：应用 A 的文件、配置、数据库默认只能自己看，连应用 B 都碰不到，更别提系统。
2. 权限最小化：即使应用申请了敏感权限（如麦克风、通讯录），也只能在沙箱里“有限使用”，超出范围立即被内核拒绝。
3. 故障/攻击面最小化：应用崩溃或被植入恶意代码，最坏也只是把自己的沙箱玩坏，不会拖垮整个系统或其他应用。
   简单来说就是HAp与系统间接隔离，防止应用直接访问系统资源。造成系统损坏

2. 沙箱配置文件结构

写在前面： APP启动沙箱相关源码在base\startup\appspawn\modules\sandbox路劲下
相关的沙箱json文件：
base\startup\appspawn\appdata-sandbox-app.json
base\startup\appspawn\appdata-sandbox.json
base\startup\appspawn\appdata-sandbox64.json
=====================================================================
Init进程启动时沙箱相关配置文件：
base\startup\init\services\sandbox\system-sandbox.json
base\startup\init\services\sandbox\chipset-sandbox.json

2.1 配置文件类型

配置文件类型	适用架构	作用域	路径
system-sandbox.json	32位系统	系统组件	/system/etc/sandbox/
system-sandbox64.json	64位系统	系统组件	/system/etc/sandbox/
chipset-sandbox.json	32位系统	芯片组件	/system/etc/sandbox/
chipset-sandbox64.json	64位系统	芯片组件	/system/etc/sandbox/

2.2 配置语法规范

{
    "sandbox-root": "/mnt/sandbox/[system|chipset]",
    "mount-bind-paths": [...],
    "mount-bind-files": [...],
    "symbol-links": [...]
}

3. 配置参数详解

3.1 根目录配置

{
    "sandbox-root": "/mnt/sandbox/system"
}

• system: 系统服务沙箱根目录
• chipset: 芯片组件沙箱根目录

3.2 目录挂载配置（mount-bind-paths）

3.2.1 基本结构

{
    "mount-bind-paths": [{
        "src-path": "/system/lib",
        "sandbox-path": "/system/lib",
        "sandbox-flags": ["bind", "rec", "private"],
        "ignore": 1
    }]
}

3.2.2 参数说明

参数名	类型	必填	说明	示例
src-path	string	是	源目录路径	“/system/lib”
sandbox-path	string	是	沙箱内挂载路径	“/system/lib”
sandbox-flags	array	是	挂载标志	[“bind”, “rec”, “private”]
ignore	int	否	是否忽略挂载失败（1=忽略，0=检查）	1

3.2.3 挂载标志详解

• bind: 绑定挂载
• rec: 递归挂载子目录
• private: 私有挂载，不共享挂载事件

3.3 文件挂载配置（mount-bind-files）

3.3.1 基本结构

{
    "mount-bind-files": [{
        "src-path": "/etc/passwd",
        "sandbox-path": "/system/etc/passwd",
        "sandbox-flags": ["bind", "rec", "private"]
    }]
}

3.3.2 系统必需文件

文件路径	作用	适用沙箱
/etc/passwd	用户配置	chipset
/etc/group	用户组配置	chipset
/system/lib/ld-musl-*.so.1	动态链接器	chipset
/system/lib/libc.so	C标准库	chipset
/system/lib/libc++.so	C++标准库	chipset

3.4 符号链接配置（symbol-links）

3.4.1 基本结构

{
    "symbol-links": [{
        "target-name": "/system/lib",
        "link-name": "/lib"
    }]
}

3.4.2 标准符号链接

目标路径	链接名称	作用
/system/lib	/lib	兼容库路径
/system/bin	/bin	兼容可执行文件路径
/system/etc	/etc	兼容配置路径

4. 系统服务沙箱配置示例

4.1 system-sandbox.json（32位）

{
    "sandbox-root": "/mnt/sandbox/system",
    "mount-bind-paths": [
        {
            "src-path": "/system/bin",
            "sandbox-path": "/system/bin",
            "sandbox-flags": ["bind", "rec", "private"]
        },
        {
            "src-path": "/system/lib",
            "sandbox-path": "/system/lib",
            "sandbox-flags": ["bind", "rec", "private"]
        },
        {
            "src-path": "/vendor/lib/chipsetsdk",
            "sandbox-path": "/vendor/lib/chipsetsdk",
            "sandbox-flags": ["bind", "rec", "private"]
        },
        {
            "src-path": "/dev",
            "sandbox-path": "/dev",
            "sandbox-flags": ["bind", "rec", "private"]
        },
        {
            "src-path": "/data",
            "sandbox-path": "/data",
            "sandbox-flags": ["bind", "rec", "private"]
        }
    ],
    "mount-bind-files": [],
    "symbol-links": [
        {
            "target-name": "/system/lib",
            "link-name": "/lib"
        },
        {
            "target-name": "/system/bin",
            "link-name": "/bin"
        }
    ]
}

4.2 system-sandbox64.json（64位）

64位配置在32位基础上增加了64位特定路径：

• /system/lib64
• /vendor/lib64/chipsetsdk
• /vendor/lib64/chipset-sdk

5. 芯片组件沙箱配置示例

5.1 chipset-sandbox.json（32位）

{
    "sandbox-root": "/mnt/sandbox/chipset",
    "mount-bind-paths": [
        {
            "src-path": "/system/lib/chipset-pub-sdk",
            "sandbox-path": "/system/lib/chipset-pub-sdk",
            "sandbox-flags": ["bind", "rec", "private"]
        },
        {
            "src-path": "/system/lib/chipset-sdk",
            "sandbox-path": "/system/lib/chipset-sdk",
            "sandbox-flags": ["bind", "rec", "private"]
        },
        {
            "src-path": "/vendor",
            "sandbox-path": "/vendor",
            "sandbox-flags": ["bind", "rec", "private"]
        }
    ],
    "mount-bind-files": [
        {
            "src-path": "/etc/passwd",
            "sandbox-path": "/system/etc/passwd",
            "sandbox-flags": ["bind", "rec", "private"]
        },
        {
            "src-path": "/etc/group",
            "sandbox-path": "/system/etc/group",
            "sandbox-flags": ["bind", "rec", "private"]
        },
        {
            "src-path": "/system/lib/ld-musl-arm.so.1",
            "sandbox-path": "/system/lib/ld-musl-arm.so.1",
            "sandbox-flags": ["bind", "rec", "private"]
        }
    ],
    "symbol-links": [
        {
            "target-name": "/system/lib",
            "link-name": "/lib"
        }
    ]
}

6. 应用沙箱配置规则

6.1 应用沙箱配置文件

应用沙箱配置通过appspawn服务管理：

• 配置文件路径: /system/etc/appspawn/
• 配置文件类型: app-sandbox.json, product-sandbox.json

6.2 应用沙箱配置示例

{
    "common": {
        "top-sandbox-switch": "ON",
        "app-base": {
            "sandbox-root": "/mnt/sandbox/<PackageName>",
            "mount-paths": [
                {
                    "src-path": "/config",
                    "sandbox-path": "/config",
                    "sandbox-flags": ["bind", "rec"],
                    "check-action-status": "false"
                }
            ],
            "symbol-links": [
                {
                    "target-name": "/system/bin",
                    "link-name": "/bin",
                    "check-action-status": "false"
                }
            ]
        }
    }
}

7. innerapi_tags配置规则

7.1 标签类型及作用

标签类型	安装目录	访问权限	适用场景
chipsetsdk	/system/lib/chipset-sdk/	系统组件访问	系统服务
chipsetsdk	/vendor/lib/chipset-sdk/	芯片组件访问	芯片驱动
passthrough	/system/lib/chipset-pub-sdk/	系统访问芯片	系统调用芯片
chipsetsdk_indirect	间接依赖	间接访问	依赖库
passthrough_indirect	间接依赖	间接访问	依赖库

7.2 BUILD.gn配置示例

ohos_shared_library("example_service") {
    sources = [ "example_service.cpp" ]
    deps = [
        "//base/example:example_lib",
    ]
    innerapi_tags = [
        "chipsetsdk",
    ]
}

8. 调试与验证

8.1 沙箱状态检查

# 检查沙箱挂载状态
begetctl sandbox status

# 查看系统服务沙箱配置
cat /system/etc/sandbox/system-sandbox.json

# 查看芯片组件沙箱配置
cat /system/etc/sandbox/chipset-sandbox.json

8.2 日志分析

# 查看init日志
hilog | grep init

# 查看沙箱挂载错误
hilog | grep "mount.*failed"

# 查看库文件加载错误
hilog | grep "dlopen.*failed"

8.3 常见问题排查

8.3.1 库文件缺失

问题现象: 服务启动失败，日志显示.so文件加载失败
解决方案:

1. 确认so文件路径在沙箱配置中已挂载
2. 检查BUILD.gn中的innerapi_tags配置
3. 临时方案：在沙箱配置中增加mount-bind-files

8.3.2 权限不足

问题现象: 服务访问文件被拒绝
解决方案:

1. 检查文件是否在沙箱挂载范围内
2. 确认文件权限和SELinux策略
3. 调整沙箱配置或文件权限