内容信任的委托

Docker 内容信任 (DCT) 中的委托允许您控制谁可以和不能签名镜像标签。委托将拥有一对私钥和公钥委托密钥。委托可以包含多对密钥和贡献者，以便 a) 允许多个用户成为委托的一部分，以及 b) 支持密钥轮换。

Docker 内容信任中最重要的是委派 targets/releases。这被视为可信镜像标签的权威来源，如果没有贡献者的密钥在此委派下，他们将无法签署标签。

幸运的是，当使用 $ docker trust 命令时，我们将自动初始化仓库，管理仓库密钥，并通过 docker trust signer add 将协作者的密钥添加到 targets/releases 委派中。

配置 Docker 客户端

默认情况下，$ docker trust 命令期望公证服务器 URL 与镜像标签中指定的注册表 URL 相同（遵循与 $ docker push 类似的逻辑）。当使用 Docker Hub 或 DTR 时，公证服务器 URL 与注册表 URL 相同。然而，对于自托管环境或第三方注册表，您需要为公证服务器指定一个替代 URL。这可以通过以下方式实现：

$ export DOCKER_CONTENT_TRUST_SERVER=https://<URL>:<PORT>

如果在自托管环境中未导出此变量，您可能会看到如下错误：

$ docker trust signer add --key cert.pem jeff registry.example.com/admin/demo
Adding signer "jeff" to registry.example.com/admin/demo...
<...>
Error: trust data missing for remote repository registry.example.com/admin/demo or remote repository not found: timestamp key trust data unavailable.  Has a notary repository been initialized?

$ docker trust inspect registry.example.com/admin/demo --pretty
WARN[0000] Error while downloading remote metadata, using cached timestamp - this might not be the latest version available remotely
<...>

如果您已为您的公证服务器启用了身份验证，或者正在使用 DTR，您需要先登录，然后才能将数据推送到公证服务器。

$ docker login registry.example.com/user/repo
Username: admin
Password:

Login Succeeded

$ docker trust signer add --key cert.pem jeff registry.example.com/user/repo
Adding signer "jeff" to registry.example.com/user/repo...
Initializing signed repository for registry.example.com/user/repo...
Successfully initialized "registry.example.com/user/repo"
Successfully added signer: jeff to registry.example.com/user/repo

如果您不登录，您将看到：

$ docker trust signer add --key cert.pem jeff registry.example.com/user/repo
Adding signer "jeff" to registry.example.com/user/repo...
Initializing signed repository for registry.example.com/user/repo...
you are not authorized to perform this operation: server returned 401.

Failed to add signer to: registry.example.com/user/repo

配置 Notary 客户端

DCT 的一些更高级的功能需要 Notary CLI。要安装和配置 Notary CLI：

下载客户端并确保它在您的路径中可用。
在 ~/.notary/config.json 处创建一个包含以下内容的配置文件：

{
  "trust_dir" : "~/.docker/trust",
  "remote_server": {
    "url": "https://registry.example.com",
    "root_ca": "../.docker/ca.pem"
  }
}

新创建的配置文件包含有关本地 Docker 信任数据位置和公证服务器 URL 的信息。

有关如何在 Docker Content Trust 用例之外使用 notary 的详细信息，请参阅 Notary CLI 文档这里

创建委托密钥

添加第一个贡献者的前提条件是一对委托密钥。这些密钥可以使用 $ docker trust 本地生成，也可以由证书颁发机构生成。

使用 Docker Trust 生成密钥

Docker 信任具有用于委托密钥对的内置生成器， $ docker trust generate <name>。运行此命令将自动将委托私钥加载到本地 Docker 信任存储中。

$ docker trust key generate jeff

Generating key for jeff...
Enter passphrase for new jeff key with ID 9deed25: 
Repeat passphrase for new jeff key with ID 9deed25: 
Successfully generated and loaded private key. Corresponding public key available: /home/ubuntu/Documents/mytrustdir/jeff.pub

手动生成密钥

如果您需要手动生成私钥（RSA 或 ECDSA）以及包含公钥的 x509 证书，您可以使用本地工具如 openssl 或 cfssl，并结合本地或公司范围的证书颁发机构。

以下是生成 2048 位 RSA 部分密钥的示例（所有 RSA 密钥必须至少为 2048 位）：

$ openssl genrsa -out delegation.key 2048

Generating RSA private key, 2048 bit long modulus
....................................................+++
............+++
e is 65537 (0x10001)

他们应该将 delegation.key 保密，因为它用于签名标签。

然后他们需要生成一个包含公钥的 x509 证书，这正是您需要从他们那里获取的内容。以下是生成 CSR（证书签名请求）的命令：

$ openssl req -new -sha256 -key delegation.key -out delegation.csr

然后他们可以将其发送给您信任的任何证书颁发机构（CA）来签署证书，或者他们可以自行签署证书（在此示例中，创建一个有效期为1年的证书）：

$ openssl x509 -req -sha256 -days 365 -in delegation.csr -signkey delegation.key -out delegation.crt

然后他们需要给你 delegation.crt，无论是自签名还是由 CA 签名。

最后，您需要将私钥添加到本地 Docker 信任存储中。

$ docker trust key load delegation.key --name jeff

Loading key from "delegation.key"...
Enter passphrase for new jeff key with ID 8ae710e: 
Repeat passphrase for new jeff key with ID 8ae710e: 
Successfully imported key from delegation.key

查看本地委托密钥

要列出已导入到本地 Docker 信任存储中的密钥，我们可以使用 Notary CLI。

$ notary key list

ROLE       GUN                          KEY ID                                                              LOCATION
----       ---                          ------                                                              --------
root                                    f6c6a4b00fefd8751f86194c7d87a3bede444540eb3378c4a11ce10852ab1f96    /home/ubuntu/.docker/trust/private
jeff                                    9deed251daa1aa6f9d5f9b752847647cf8d705da0763aa5467650d0987ed5306    /home/ubuntu/.docker/trust/private

在 Notary 服务器中管理委派

当第一次使用 $ docker trust 将委托添加到 Notary Server 时，我们会自动为该仓库初始化信任数据。这包括创建 notary 目标和快照密钥，并将快照密钥轮换为由 notary 服务器管理。有关这些密钥的更多信息，请点击这里

在启动仓库时，您需要本地 Notary Canonical Root Key 的密钥和密码短语。如果您之前从未启动过仓库，因此没有 Notary 根密钥，$ docker trust 将为您创建一个。

重要
请务必保护和备份您的 Notary Canonical Root Key。

正在初始化仓库

要将第一个密钥上传到委托，同时启动仓库，您可以使用 $ docker trust signer add 命令。这将把贡献者的公钥添加到 targets/releases 委托，并创建第二个 targets/<name> 委托。

对于 DCT，第二个委托的名称（在下面的示例中为 jeff）旨在帮助您跟踪密钥的所有者。在 Notary 的高级用例中，额外的委托用于层次结构。

$ docker trust signer add --key cert.pem jeff registry.example.com/admin/demo

Adding signer "jeff" to registry.example.com/admin/demo...
Initializing signed repository for registry.example.com/admin/demo...
Enter passphrase for root key with ID f6c6a4b: 
Enter passphrase for new repository key with ID b0014f8: 
Repeat passphrase for new repository key with ID b0014f8: 
Successfully initialized "registry.example.com/admin/demo"
Successfully added signer: jeff to registry.example.com/admin/demo

您可以使用 $ docker trust inspect 命令查看每个仓库已推送到 Notary 服务器的密钥。

$ docker trust inspect --pretty registry.example.com/admin/demo

No signatures for registry.example.com/admin/demo


List of signers and their keys for registry.example.com/admin/demo

SIGNER              KEYS
jeff                1091060d7bfd

Administrative keys for registry.example.com/admin/demo

  Repository Key:	b0014f8e4863df2d028095b74efcb05d872c3591de0af06652944e310d96598d
  Root Key:	64d147e59e44870311dd2d80b9f7840039115ef3dfa5008127d769a5f657a5d7

您也可以使用 Notary CLI 来列出委托和密钥。在这里您可以清楚地看到密钥被附加到了 targets/releases 和 targets/jeff。

$ notary delegation list registry.example.com/admin/demo

ROLE                PATHS             KEY IDS                                                             THRESHOLD
----                -----             -------                                                             ---------
targets/jeff        "" <all paths>    1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1    1
                                          
targets/releases    "" <all paths>    1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1    1

添加其他签名者

Docker Trust 允许您为每个仓库配置多个委托，允许您管理委托的生命周期。当使用 $ docker trust 添加额外的委托时，协作者的密钥会再次添加到 targets/release 角色中。

请注意，您需要仓库密钥的密码短语；这是在您首次初始化仓库时配置的。

$ docker trust signer add --key ben.pub ben registry.example.com/admin/demo

Adding signer "ben" to registry.example.com/admin/demo...
Enter passphrase for repository key with ID b0014f8: 
Successfully added signer: ben to registry.example.com/admin/demo

检查以证明现在有 2 个委托（签名者）。

$ docker trust inspect --pretty registry.example.com/admin/demo

No signatures for registry.example.com/admin/demo

List of signers and their keys for registry.example.com/admin/demo

SIGNER              KEYS
ben                 afa404703b25
jeff                1091060d7bfd

Administrative keys for registry.example.com/admin/demo

  Repository Key:	b0014f8e4863df2d028095b74efcb05d872c3591de0af06652944e310d96598d
  Root Key:	64d147e59e44870311dd2d80b9f7840039115ef3dfa5008127d769a5f657a5d7

向现有委派添加密钥

为了支持密钥轮换和密钥过期/停用等操作，您可以为每个委托发布多个贡献者密钥。这里唯一的先决条件是确保使用相同的委托名称，在本例中为 jeff。Docker 信任将自动处理将此新密钥添加到 targets/releases。

注意
您需要仓库密钥的密码短语；这是在您首次初始化仓库时配置的。

$ docker trust signer add --key cert2.pem jeff registry.example.com/admin/demo

Adding signer "jeff" to registry.example.com/admin/demo...
Enter passphrase for repository key with ID b0014f8: 
Successfully added signer: jeff to registry.example.com/admin/demo

检查以证明委托方（签名者）现在包含多个密钥ID。

$ docker trust inspect --pretty registry.example.com/admin/demo

No signatures for registry.example.com/admin/demo


List of signers and their keys for registry.example.com/admin/demo

SIGNER              KEYS
jeff                1091060d7bfd, 5570b88df073

Administrative keys for registry.example.com/admin/demo

  Repository Key:	b0014f8e4863df2d028095b74efcb05d872c3591de0af06652944e310d96598d
  Root Key:	64d147e59e44870311dd2d80b9f7840039115ef3dfa5008127d769a5f657a5d7

移除委托

如果您需要移除一个委托，包括附加到 targets/releases 角色的贡献者密钥，您可以使用 $ docker trust signer remove 命令。

注意
由已移除的委托签名的标签需要由活动的委托重新签名

$ docker trust signer remove ben registry.example.com/admin/demo
Removing signer "ben" from registry.example.com/admin/demo...
Enter passphrase for repository key with ID b0014f8: 
Successfully removed ben from registry.example.com/admin/demo

故障排除

如果你在 targets/releases 中看到没有可用密钥的错误，你需要在重新签署镜像之前使用 docker trust signer add 添加额外的委派。
WARN[0000] role targets/releases has fewer keys than its threshold of 1; it will not be usable until keys are added to it
如果您已经添加了额外的授权，并且在 targest/releases 中看到错误消息显示没有有效的签名，您将需要使用 Notary CLI 重新签署 targets/releases 授权文件。
WARN[0000] Error getting targets/releases: valid signatures did not meet threshold for targets/releases
重新签署委托文件是通过 $ notary witness 命令完成的
$ notary witness registry.example.com/admin/demo targets/releases --publish
有关 $ notary witness 命令的更多信息，可以在此处找到

从委托中移除贡献者的密钥

作为委托轮换密钥的一部分，您可能希望移除单个密钥但保留委托。这可以通过 Notary CLI 完成。

请记住，您需要从 targets/releases 角色和该签名者特定的角色 targets/<name> 中移除密钥。

我们需要从 Notary 服务器获取 Key ID

$ notary delegation list registry.example.com/admin/demo

ROLE                PATHS             KEY IDS                                                             THRESHOLD
----                -----             -------                                                             ---------
targets/jeff        "" <all paths>    8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9    1
                                      1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1    
targets/releases    "" <all paths>    8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9    1
                                      1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1

从 targets/releases 委托中移除

$ notary delegation remove registry.example.com/admin/demo targets/releases 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 --publish

Auto-publishing changes to registry.example.com/admin/demo
Enter username: admin
Enter password: 
Enter passphrase for targets key with ID b0014f8: 
Successfully published changes for repository registry.example.com/admin/demo

从 targets/<name> 委托中移除

$ notary delegation remove registry.example.com/admin/demo targets/jeff 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 --publish

Removal of delegation role targets/jeff with keys [5570b88df0736c468493247a07e235e35cf3641270c944d0e9e8899922fc6f99], to repository "registry.example.com/admin/demo" staged for next publish.

Auto-publishing changes to registry.example.com/admin/demo
Enter username: admin    
Enter password: 
Enter passphrase for targets key with ID b0014f8: 
Successfully published changes for repository registry.example.com/admin/demo

检查剩余的委托列表

$ notary delegation list registry.example.com/admin/demo

ROLE                PATHS             KEY IDS                                                             THRESHOLD
----                -----             -------                                                             ---------
targets/jeff        "" <all paths>    8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9    1    
targets/releases    "" <all paths>    8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9    1

移除本地委托私钥

作为轮换委托密钥的一部分，您可能需要从本地 Docker 信任存储中删除本地委托密钥。这是通过 Notary CLI 完成的，使用 $ notary key remove 命令。

我们需要从本地 Docker 信任存储中获取密钥 ID

$ notary key list

ROLE       GUN                          KEY ID                                                              LOCATION
----       ---                          ------                                                              --------
root                                    f6c6a4b00fefd8751f86194c7d87a3bede444540eb3378c4a11ce10852ab1f96    /home/ubuntu/.docker/trust/private
admin                                   8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9    /home/ubuntu/.docker/trust/private
jeff                                    1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1    /home/ubuntu/.docker/trust/private
targets    ...example.com/admin/demo    c819f2eda8fba2810ec6a7f95f051c90276c87fddfc3039058856fad061c009d    /home/ubuntu/.docker/trust/private

从本地 Docker 信任存储中删除密钥

$ notary key remove 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1

Are you sure you want to remove 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 (role jeff) from /home/ubuntu/.docker/trust/private?  (yes/no)  y

Deleted 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 (role jeff) from /home/ubuntu/.docker/trust/private.

从仓库中删除所有信任数据

您可以使用 Notary CLI 从仓库中移除所有信任数据，包括仓库、目标、快照以及所有委托密钥。

这通常是容器注册表在删除特定仓库之前所必需的。

$ notary delete registry.example.com/admin/demo --remote

Deleting trust data for repository registry.example.com/admin/demo
Enter username: admin
Enter password: 
Successfully deleted local and remote trust data for repository registry.example.com/admin/demo

$ docker trust inspect --pretty registry.example.com/admin/demo

No signatures or cannot access registry.example.com/admin/demo