attestation_agent开发流程和功能使用指南

1. 功能简介

attestation_agent是远程证明系统的客户端组件，提供以下功能：

网元证据收集（TPM PCR、启动信息、IMA 日志等）
远程证明周期性挑战响应
证明令牌管理
与证明服务的通信

2. 开发环境搭建

2.1 所需组件

Rust 1.82.0 或更高版本
libssl-dev（用于 OpenSSL）
libtss2-dev（用于 TPM 2.0 访问）
virtCCA_sdk（用于 virtCCA）
virtCCA_sdk-devel（用于 virtCCA）
pkg-config
itrustee_sdk（用于 itrustee）
libboundscheck（用于 itrustee）
cca_sdk（用于CCA）
cca_sdk-devel（用于CCA）

2.2 环境配置

安装所需组件

yum install -y build-essential pkg-config libssl-dev libtss2-dev virtCCA_sdk virtCCA_sdk-devel libboundscheck

安装 Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

配置 Rust 工具链

rustup default stable
rustup component add rustfmt clippy

安装 Itrustee 环境

iTrustee 集成是可选的。如果您的部署需要基于 iTrustee 的远程证明，请参考以下文档了解其介绍和部署指南： https://www.hikunpeng.com/document/detail/zh/kunpengcctrustzone/trustzone/fg/kunpengtrustzone_20_0002.html。

3. 目录结构

attestation_agent/
├── agent               # agent 主进程，提供服务入口
├── agent_restful       # RESTful API 实现，处理证据收集和令牌请求
├── attester           # 证据收集插件模块
│   └── tpm            # TPM 相关插件
│       ├── boot       # TPM 启动信息收集插件
│       ├── common     # TPM 插件共享代码
│       └── ima        # TPM IMA 日志收集插件
│   └── virtCCA        # virtCCA 插件
│   └── ascend_npu     # ascend npu 插件
│   └── itrustee       # itrustee 证据收集插件
│   └── cca            # CCA 证据收集插件
│   └── dice           # DICE 证据收集插件
├── challenge          # 挑战请求处理模块
├── config             # 配置管理模块，处理配置文件解析
└── utils              # 通用工具模块，包括网络、日志等

4. 开发流程指南

4.1 添加新插件流程

1 在插件接口中实现 AgentPlugin trait

  pub trait AgentPlugin {
    fn plugin_type(&self) -> &str;
    fn collect_evidence(&self, node_id: Option<&str>, nonce: Option<&[u8]>) 
        -> Result<serde_json::Value, PluginError>;
  }

2 创建插件配置结构

  #[derive(Debug, Clone, Deserialize)]
  pub struct MyPluginConfig {
      pub enabled: bool,
      pub parameters: HashMap<String, String>,
  }

3 实现插件逻辑

  pub struct MyPlugin {
      config: MyPluginConfig,
  }

  impl AgentPlugin for MyPlugin {
      fn plugin_type(&self) -> &str {
          "my_plugin_type"
      }
    
      fn collect_evidence(&self, node_id: Option<&str>, nonce: Option<&[u8]>) 
          -> Result<serde_json::Value, PluginError> {
          // Implement evidence collection logic
      }
  }

4.2 实现定时任务添加

    let scheduler_config = SchedulerConfig::new()

    let task = Box::new(move || {
        Box::pin(async move {
            info!("Scheduler task executed");
            Ok(())
        }) as Pin<Box<dyn Future<Output = Result<(), agent_utils::AgentError>> + Send>>
    });

    let mut schedulers = SchedulerBuilders::new();
    schedulers.add(scheduler_config, task);

4.3 添加 RESTful 接口路由

    // start server
    info!("Starting server at listen address: {}:{}", config.agent.listen_address, config.agent.listen_port);
    let rest_config = ServiceConfig::new()
        .with_port(config.agent.listen_port)
        .with_bind_address(&config.agent.listen_address);

    let service = RestService::configure(rest_config)?;

    service.register(
        Method::POST,
        "/global-trust-authority/agent/v1/xxx",
        |_: HttpRequest, body: Option<Value>| foo(body),
    )?;

    service.start_server().await?;

5. 功能使用指南

5.1 定时挑战任务

在 agent_config.yaml 的 scheduler 模块中配置挑战定时任务。可以根据需要修改设置，例如定时间隔。为防止服务器并发过载导致请求失败，提供了延迟错峰功能，可配置延迟时间。

    - name: "challenge"                  # 任务名称
    retry_enabled: true                # 启用重试
    cron_expression: "*/10 * * * * *"  # 每 10 秒执行一次
    initial_delay:                     # 随机初始延迟配置
      min_seconds: 1                   # 最小延迟 1 秒
      max_seconds: 60                  # 最大延迟 60 秒
    max_retries: 1

5.2 令牌管理

curl -X POST http://localhost:8080/global-trust-authority/agent/v1/tokens -d '{
    "attester_info": [
      {
        "attester_type": "tpm_boot",
        "policy_ids": ["policy1", "policy2"]
      }
    ],
    "challenge": true,
    "token_fmt": "ear",
    "attester_data": {"test_key": "test_value"}
}'

5.3 获取证据

curl -X POST http://localhost:8080/global-trust-authority/agent/v1/evidences \
  -H "Content-Type: application/json" \
  -d '{
    "attester_types": ["tpm", "tpm_boot", "tpm_ima"],
    "nonce_type": "verifier",
    "nonce": "eyJpYXQiOjE3NTY5ODAwNjMsInZhbHVlIjoiZjMrYVc0cm1vWHUxSjNjaGlJZWNkMkJUWWYrdS84WXU0Q2VTZWYwUmt4MXYzeHJhNHZNYkNrc1locC9UaTRVWW9wN1ZvMm5XNXlsMGs4VXNQNnZrTkE9PSIsInNpZ25hdHVyZSI6Im9Mc09WbTh2OHY3ZllUTW9SZHdySjBrbWl4blFmRXIwTVliNExDa2NyZUpveUFDZmFBdlpGdmJiYURHTFJjOW9ndWkycVhMbnUwWFgvZDhEc1hhK2xwQzg2dXhSeWZtYklSdVpza2xscHd5WVV4TXlEbmFZQS9SSlFGaEtEakJjYUp0Ri9sQnpZYWMzVVNzQmFkNE5tMVE1cnBEb3RscFpHbHd5akhhdGtxUENPVzZORG9wbU9pZWtzM3RNVXpJV0NyNVZPVGhhRnpZdUdIZUZJMHdhdVdMWHY4TnlwRnlIbnllay8zdWhjdEhIc2gyRExZZUVBZW1keWQ2VnVDWmNqNjBzSjNyenF5ME9LTUFIQVRuOWhhZjk0M0k3SllDUlkvTU0xQ08rWmk1MHNTUXV1UHllVUpuTERpMGxwQmdDZmwyeWgyQ2phcU9QdE15ckhTREJwRlNNaC8xVW5xdDBlaXFzcFRESDNtNm81TXd3dUFQWGJmRFZvaDArR2dPaUowaENLUnhLY3NXSXVHNythemNoS0U3U1kyakIxWWg0NjlpSTN2MUpQRWhobnVtdC9YWENhRXBYd29aVENLRUN6NjJMYnByOWp3SzZXVVZyS2t5L3hmbkdKTlR3NWxHNGFBS1hlOFdzSldtYnpXK0Yvd0JFa0E2amdHK1hWT1J6In0=",
     "token_fmt": "ear",
    "attester_data": {"test_key": "test_value"}
  }'

5.4 日志记录

// 配置日志
log::info!("Processing challenge: {:?}", challenge);
log::error!("Error occurred: {:?}", error);

6. 测试指南

6.1 测试指南（tests/）

  #[cfg(test)]
  mod tests {
    #[test]
    fn test_evidence_generation() { 
        // Test implementation
    }
  }

7. 部署指南

7.1 构建和运行

# 构建
cargo build -p attestation_agent

# 运行 agent
cargo run --bin attestation_agent  ./config/agent_config.yaml

7.2 配置指南

7.2.1 配置文件

agent_config.yaml 配置文件支持三种场景：

启动 attestation_agent 进程时指定文件路径
与 attestation_agent 进程同目录
/etc/attestation_agent/agent_config.yaml

7.2.2 相关配置说明

RUST_LOG：日志级别（trace、debug、info、warn、error）
Port：Agent 监听端口
Service Address：远程证明服务地址
TPM Device Access：通常是设备