docker/tuf-targets

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) 调整用户权限）