KDC 部署使用说明书

KunPeng Data Controller (KDC) — 基于鲲鹏 VirtCCA 的可信数据空间系统

本文档面向零基础用户，涵盖从环境准备到项目运行的全部步骤。请严格按照顺序依次执行每一条命令。

---

目录

1. 项目概述
2. 环境要求
3. 安装系统依赖
4. 安装 Rust 工具链
5. 编译项目
6. 项目安装
7. 生成 TLS 证书
8. 部署配置文件
9. 启动服务

---

1. 项目概述

KDC 系统由以下组件构成：

组件	说明	产物
kdc_agent	服务端，提供可信属性服务，管理可信插件的生命周期	kdc_agent（二进制）、libkdc_agent.so（共享库）
kdc_proxy	客户端，提供 C 语言 FFI 接口，供业务程序调用	libkdc_proxy.so（共享库）

通信流程：业务程序 → kdc_proxy (FFI) → [TLS] → kdc_agent → 插件(hisec_trustattribute)

---

2. 环境要求

项目	要求
操作系统	openEuler 24.03
磁盘空间	编译时至少 2GB 可用空间
内存	编译时至少 2GB 可用内存
网络	编译时需要网络连接（下载 Rust 依赖和 crates.io 索引）
权限	编译阶段：普通用户即可；部署阶段：需要 root 权限

---

3. 安装系统依赖

3.1 openEuler / CentOS / RHEL 系列

sudo dnf install -y gcc gcc-c++ git make openssl openssl-devel perl cmake pkg-config

说明：

• gcc 和 gcc-c++：C/C++ 编译器，编译 OpenSSL 和 hisec_trustattribute C 插件需要
• openssl 和 openssl-devel：加密库及头文件，Rust 的 openssl-sys crate 编译时需要
• perl 和 cmake：OpenSSL 编译依赖
• pkg-config：帮助编译器定位系统库的路径

3.2 验证系统依赖安装成功

gcc --version
openssl version
pkg-config --modversion openssl

预期输出示例（版本号可能不同，但命令不应报错）：

gcc (GCC) 12.3.1
OpenSSL 3.0.12
3.0.12

---

4. 安装 Rust 工具链

4.1 安装 rustup（Rust 版本管理器）

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

4.2 加载 Rust 环境变量

source "$HOME/.cargo/env"

或者将其写入 ~/.bashrc 使其永久生效：

echo 'source "$HOME/.cargo/env"' >> ~/.bashrc

4.3 验证 Rust 安装

rustc --version
cargo --version

注意：本项目使用rust 1.90.0稳定版本。如果版本过低，执行：

rustup default 1.90.0

---

5. 编译项目

执行以下命令：

cd KDC
bash scripts/build_rpm.sh

编译产物位于 output 目录下。

---

6. 项目安装

使用步骤5中得到的rpm包进行安装。

sudo rpm -ivh kdcagent-0.0.1-1.aarch64.rpm
sudo rpm -ivh kdcproxy-0.0.1-1.aarch64.rpm

各 RPM 包安装内容如下：

RPM 包	安装路径	说明
kdcagent	/usr/bin/kdc_agent	Agent 主程序
	/usr/lib64/libkdc_agent.so	Agent 共享库
	/etc/kdc_agent/agent_conf.json	配置文件
	/usr/lib/systemd/system/kdcagent.service	systemd 服务单元
kdcproxy	/usr/lib64/libkdc_proxy.so	Proxy 共享库

说明：

• 安装后自动创建 /etc/kdc_agent/ 目录（权限 750）。
• post-install 脚本会自动创建 /etc/kdc_agent/certs/ 目录（权限 750），用于存放证书文件。此目录不受 RPM 管理，卸载时不会自动删除。
• 二进制和库文件权限为 550，配置文件权限为 644。

---

7. 生成 TLS 证书

KDC Agent 使用单向 TLS 认证，需要 CA 证书和服务端证书。客户端（kdc_proxy）通过 CA 证书验证服务端证书，服务端不验证客户端证书。

证书格式要求：kdc_proxy 底层使用 rustls 进行 TLS 通信，要求所有证书（CA 证书、服务端证书、客户端证书）必须为 X.509 V3 格式。正规 CA 签发的证书均满足此要求。可通过以下命令检查证书版本：openssl x509 -in <证书路径> -text -noout | head -3，输出中 Version: 3 (0x2) 即为 V3 证书。 创建证书目录并将证书放置在此路径下：

sudo mkdir -p /etc/kdc_agent/certs
sudo mkdir -p /etc/kdc_proxy/certs

---

8. 部署配置文件

配置文件路径是/etc/kdc_agent/agent_conf.json，下面是一个示例，请根据实际环境修改：

{
    "ip": "192.168.122.45",
    "port": 26068,
    "caPath": "/etc/kdc_agent/certs/ca.crt",
    "certPath": "/etc/kdc_agent/certs/server.crt",
    "privatePath": "/etc/kdc_agent/certs/server.key",
    "crlPath": "/etc/kdc_agent/certs/ca.crl",
    "raPublicKeyPath": "/etc/kdc_agent/certs/ra.pem",
    "logPath": "/var/log/kdcagent.log",
    "dataPath": "/var/lib/kdc_agent/data",
    "logMaxSize": 10,
    "logBackupCount": 5,
    "minLogLevel": "info",
    "plugins": [
        {
            "name": "hisec_trustattribute",
            "path": "/usr/lib64/libhisec_trustattribute.so",
            "param": {
                "key1": "value1",
                "key2": "value2"
            }
        }
    ]
}

配置项说明：

• ip：必选，Agent 监听地址。必须是合法 IPv4 地址（x.x.x.x，每个 octet 0-255）。
• port：必选，Agent 监听端口，默认 26068。必须为1-65535之间的合法端口。
• caPath：必选，CA 证书路径。必须是非空绝对路径（以 / 开头），不含控制字符。
• certPath：必选，服务端证书路径。必须是非空绝对路径。
• privatePath：必选，服务端私钥路径。必须是非空绝对路径。
• crlPath：可选，CRL 文件路径。服务端已改为单向TLS认证，不再验证客户端证书，此字段为可选字段。若有该字段，可设为空字符串 ""（非空时必须是绝对路径）。
• logPath：必选，日志文件路径。必须是非空绝对路径。
• dataPath：必选，kdc_agent运行时数据目录。必须是非空绝对路径。
• raPublicKeyPath：必选，RA Agent PEM格式公钥文件路径，用于远程证明token报告验证时使用。
• logMaxSize：可选，单个日志文件最大大小（单位：MB），默认 10。非空必须 > 0。
• logBackupCount：可选，最多保留的历史日志文件数量，默认 5。必须 > 0。
• minLogLevel：可选，日志最低可见级别，可选。取值："debug" / "info" / "warn" / "error"（不区分大小写），默认 "info"。
• plugins：可选，插件列表，每个插件必须指定 name（插件名称）、path（.so 文件绝对路径）。缺失 name 或 path 的条目会被跳过（记录 warn 日志）；重复 name 仅加载首次出现的条目。空插件列表合法（启动时打印 warn 日志提示无插件加载）。
• plugins[].param：插件自定义参数（JSON 对象），可选。

---

9. 启动服务

sudo systemctl start kdcagent

---