TUF Target Files Docker 镜像文档

一、镜像概述和主要用途

概述

TUF Target Files Docker 镜像是基于 The Update Framework (TUF) 规范构建的工具镜像，专注于 TUF 生态中 "target 文件" 的生命周期管理。Target 文件是 TUF 仓库中待分发的实际软件资产（如固件、安装包、配置文件等），其元数据（如哈希、大小、版本）需符合 TUF 安全规范并与 TUF 仓库集成。

主要用途

• 生成 target 文件的 TUF 元数据（包含文件哈希、大小、版本信息）
• 对 target 元数据进行签名（使用 TUF 角色私钥）
• 验证 target 文件完整性（通过元数据校验哈希）
• 同步 target 文件至 TUF 仓库（支持本地文件系统或远程仓库）

二、核心功能和特性

核心功能

1. Target 元数据管理

   • 自动生成 target 文件的元数据（targets.json 或版本化元数据）
   • 支持多版本 target 文件管理，维护版本历史记录

2. 安全签名与验证

   • 集成 TUF 签名逻辑，支持使用 targets 角色私钥对元数据签名
   • 验证已签名元数据的完整性和签名有效性

3. 仓库集成

   • 支持将 target 文件及其元数据同步至本地 TUF 仓库目录
   • 兼容 TUF 规范的远程仓库（如 AWS S3、FTP、HTTP 仓库）

4. 完整性校验

   • 计算 target 文件的 SHA-256/SHA-512 哈希值，确保文件未被篡改
   • 校验本地文件与元数据记录的哈希一致性

特性

• 合规性：严格遵循 TUF v1.0 规范，确保与 TUF 客户端/仓库工具链兼容
• 自动化支持：提供 CLI 命令行接口，可集成至 CI/CD 流水线
• 轻量级：基于 Alpine Linux，镜像体积小，启动速度快
• 灵活性：支持自定义签名算法、元数据格式（JSON/JSON Lines）和仓库路径

三、使用场景和适用范围

使用场景

1. 软件更新分发

   • 物联网（IoT）设备固件更新：生成固件文件的 TUF 元数据，确保设备安全下载验证
   • 桌面/移动应用更新：管理安装包（.exe、.apk 等）的版本化元数据
   • 企业内部软件分发：安全分发内部工具或配置文件

2. DevOps 流程集成

   • CI/CD 流水线：在构建阶段自动生成 target 元数据并签名，同步至 TUF 仓库
   • 版本发布管理：维护 target 文件的多版本元数据，支持回滚或灰度发布

3. 安全审计与验证

   • 校验第三方提供的 target 文件是否符合本地 TUF 元数据记录（防篡改）

适用范围

• 开发团队：管理软件资产的更新元数据
• DevOps/运维团队：集成至自动化部署流程
• 安全团队：确保软件分发符合 TUF 安全规范

四、使用方法

前提条件

• 已安装 Docker 环境（20.10+ 版本）
• 本地或远程 TUF 仓库目录（需包含 TUF 根元数据 root.json）
• TUF targets 角色私钥（用于签名元数据，需确保安全存储）

1. 基础使用（Docker Run）

通过 docker run 命令启动容器，执行 target 文件元数据生成与签名：

bash
docker run -it --rm \
  -v /path/to/local/tuf-repo:/tuf/repo \  # 挂载本地 TUF 仓库目录至容器内 /tuf/repo
  -v /path/to/target-files:/tuf/targets \  # 挂载待处理的 target 文件目录至 /tuf/targets
  -v /path/to/signing-keys:/tuf/keys \  # 挂载包含 TUF targets 私钥的目录至 /tuf/keys
  -e TARGET_NAME="firmware-v1.2.3.bin" \  # 指定 target 文件名（位于 /tuf/targets 下）
  -e SIGNING_KEY_PATH="/tuf/keys/targets-private.key" \  # 指定签名私钥路径
  -e REPO_PATH="/tuf/repo" \  # 指定 TUF 仓库路径（容器内路径）
  tuf-target-files:latest generate  # 执行元数据生成命令

命令说明

• generate：生成 target 文件的元数据并签名，输出至 $REPO_PATH/targets.json
• verify：验证 target 文件与元数据的哈希一致性（需指定 TARGET_NAME 和 REPO_PATH）
• sync：将 target 文件同步至 TUF 仓库（需额外指定 REMOTE_REPO_URL 环境变量）

2. Docker Compose 配置示例

适用于需要持久化 TUF 仓库和密钥的场景：

yaml
version: '3.8'
services:
  tuf-target-manager:
    image: tuf-target-files:latest
    volumes:
      - ./tuf-repo:/tuf/repo  # 本地 TUF 仓库（持久化）
      - ./target-files:/tuf/targets  # 本地 target 文件目录
      - ./keys:/tuf/keys  # 持久化存储 TUF 私钥
    environment:
      - TARGET_NAME="app-v2.0.0.tar.gz"
      - SIGNING_KEY_PATH="/tuf/keys/targets-private.key"
      - REPO_PATH="/tuf/repo"
      - HASH_ALG="sha256"  # 哈希算法（支持 sha256/sha512）
      - VERSION="1.2.3"  # target 文件版本号（元数据中记录）
    command: generate  # 默认执行元数据生成

五、配置说明

环境变量

挂载卷

命令参数

容器支持以下命令（通过 docker run 或 command 字段指定）：

• generate：生成 target 元数据并签名
• verify：验证 target 文件与元数据哈希一致性
• sync：将 target 文件同步至本地/远程 TUF 仓库

六、注意事项

1. 私钥安全：SIGNING_KEY_PATH 指向的私钥需严格保密，建议通过加密卷或密钥管理服务（如 Vault）挂载
2. 元数据版本：多次生成同一 target 文件时，需更新 VERSION 字段或手动管理元数据版本号
3. 兼容性：镜像生成的元数据兼容 TUF v1.0 规范，需确保 TUF 客户端（如 tuf-client、uptane）支持该版本
4. 权限：挂载的宿主机目录需赋予容器读写权限（可通过 --user $(id -u):$(id -g) 调整用户权限）