您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

Azure 容器注册表中的内容信任Content trust in Azure Container Registry

Azure 容器注册表实现了 Docker 的内容信任模型,支持推送和拉取已签名的映像。Azure Container Registry implements Docker's content trust model, enabling pushing and pulling of signed images. 本文可帮助你开始在容器注册表中启用内容信任。This article gets you started enabling content trust in your container registries.

备注

内容信任是 Azure 容器注册表高级 SKU 的一项功能。Content trust is a feature of the Premium SKU of Azure Container Registry.

内容信任工作原理How content trust works

对于在设计时需考虑安全性的任何分布式系统来说,重要的是验证进入系统的数据的源和完整性。 Important to any distributed system designed with security in mind is verifying both the source and the integrity of data entering the system. 数据的使用者需要能够验证数据的发布者(源),并确保数据在发布后未修改过(完整性)。Consumers of the data need to be able to verify both the publisher (source) of the data, as well as ensure it's not been modified after it was published (integrity).

作为映像发布者,你可以通过内容信任对发布到注册表的映像进行签名As an image publisher, content trust allows you to sign the images you push to your registry. 映像的使用者(从注册表拉取映像的人或系统)可以将其客户端配置为 仅拉取签名的映像。Consumers of your images (people or systems pulling images from your registry) can configure their clients to pull only signed images. 当映像使用者拉取签名的映像时,其 Docker 客户端会验证映像的完整性。When an image consumer pulls a signed image, their Docker client verifies the integrity of the image. 在此模型中,可以向使用者确保你注册表中的签名映像确实是你发布的,且自发布后未作修改。In this model, consumers are assured that the signed images in your registry were indeed published by you, and that they've not been modified since being published.

受信任的映像Trusted images

内容信任使用存储库中的标记Content trust works with the tags in a repository. 映像存储库包含的映像可以带签名的和未签名的标记。Image repositories can contain images with both signed and unsigned tags. 例如,可以只对 myimage:stablemyimage:latest 映像签名,而不对 myimage:dev 映像签名。For example, you might sign only the myimage:stable and myimage:latest images, but not myimage:dev.

签名密钥Signing keys

内容信任通过一组加密签名密钥来管理。Content trust is managed through the use of a set of cryptographic signing keys. 这些密钥与注册表中的特定存储库相关联。These keys are associated with a specific repository in a registry. Docker 客户端和你的注册表使用多种类型的签名密钥来管理存储库中标记的信任。There are several types of signing keys that Docker clients and your registry use in managing trust for the tags in a repository. 启用内容信任并将其集成到容器发布和使用管道中时,必须小心管理这些密钥。When you enable content trust and integrate it into your container publishing and consumption pipeline, you must manage these keys carefully. 有关详细信息,请参阅本文后面的密钥管理以及 Docker 文档中的管理内容信任的密钥For more information, see Key management later in this article and Manage keys for content trust in the Docker documentation.

提示

这是对 Docker 的内容信任模型的简要概述。This was a very high-level overview of Docker's content trust model. 若要深入探讨内容信任,请参阅 Docker 中的内容信任For an in-depth discussion of content trust, see Content trust in Docker.

启用注册表内容信任Enable registry content trust

第一步是在注册表级别启用内容信任。Your first step is to enable content trust at the registry level. 启用内容信任以后,客户端(用户或服务)即可将签名的映像推送到注册表。Once you enable content trust, clients (users or services) can push signed images to your registry. 在注册表上启用内容信任并不意味着只能由启用了内容信任的使用者来使用注册表。Enabling content trust on your registry does not restrict registry usage only to consumers with content trust enabled. 未启用内容信任的使用者可以照常继续使用注册表。Consumers without content trust enabled can continue to use your registry as normal. 不过,在其客户端中启用了内容信任的使用者在其注册表中只能看到签名的映像。 Consumers who have enabled content trust in their clients, however, will be able to see only signed images in your registry.

若要为注册表启用内容信任,请先在 Azure 门户中导航到注册表。To enable content trust for your registry, first navigate to the registry in the Azure portal. 在“策略” 下选择“内容信任” > “启用” > “保存”。Under Policies, select Content Trust > Enabled > Save.

在 Azure 门户中为注册表启用内容信任

启用客户端内容信任Enable client content trust

若要使用受信任的映像,映像发布者和使用者均需为其 Docker 客户端启用内容信任。To work with trusted images, both image publishers and consumers need to enable content trust for their Docker clients. 作为发布者,你可以为推送到启用了内容信任的注册表的映像签名。As a publisher, you can sign the images you push to a content trust-enabled registry. 作为使用者,你在启用内容信任限制后只能查看注册表的签名映像。As a consumer, enabling content trust limits your view of a registry to signed images only. 内容信任在 Docker 客户端中默认禁用,但可以按 shell 会话或按命令启用。Content trust is disabled by default in Docker clients, but you can enable it per shell session or per command.

若要为 shell 会话启用内容信任,请将 DOCKER_CONTENT_TRUST 环境变量设置为 1To enable content trust for a shell session, set the DOCKER_CONTENT_TRUST environment variable to 1. 例如,在 Bash shell 中,请执行以下代码:For example, in the Bash shell:

# Enable content trust for shell session
export DOCKER_CONTENT_TRUST=1

若要为单个命令启用或禁用内容信任,可以使用多个 Docker 命令支持的 --disable-content-trust 参数。If instead you'd like to enable or disable content trust for a single command, several Docker commands support the --disable-content-trust argument. 若要为单个命令启用内容信任,请执行以下代码:To enable content trust for a single command:

# Enable content trust for single command
docker build --disable-content-trust=false -t myacr.azurecr.io/myimage:v1 .

如果已经为 shell 会话启用了内容信任,希望对单个命令禁用它,请执行以下代码:If you've enabled content trust for your shell session and want to disable it for a single command:

# Disable content trust for single command
docker build --disable-content-trust -t myacr.azurecr.io/myimage:v1 .

授予映像签名权限Grant image signing permissions

只有已获得授权的用户或系统能够向注册表推送受信任的映像。Only the users or systems you've granted permission can push trusted images to your registry. 若要向用户(或使用服务主体的系统)授予受信任映像的推送权限,请为其 Azure Active Directory 标识授予 AcrImageSigner 角色。To grant trusted image push permission to a user (or a system using a service principal), grant their Azure Active Directory identities the AcrImageSigner role. 这是在 AcrPush(或等效)角色(此角色是将映像推送到注册表所必需的)基础上添加的角色。This is in addition to the AcrPush (or equivalent) role required for pushing images to the registry. 有关详细信息,请参阅 Azure 容器注册表角色和权限For details, see Azure Container Registry roles and permissions.

下面是在 Azure 门户和 Azure CLI 中授予 AcrImageSigner 角色的详细信息。Details for granting the AcrImageSigner role in the Azure portal and the Azure CLI follow.

Azure 门户Azure portal

导航到 Azure 门户中的注册表,然后选择“访问控制(IAM)” > “添加角色分配”。Navigate to your registry in the Azure portal, then select Access control (IAM) > Add role assignment. 在“添加角色分配”下的“角色”下选择“AcrImageSigner”, 然后选择一个或多个用户或服务主体,然后单击“保存”。 Under Add role assignment, select AcrImageSigner under Role, then Select one or more users or service principals, then Save.

在此示例中,为以下两个实体分配了 AcrImageSigner 角色:名为“service-principal”的服务主体,以及名为“Azure 用户”的用户。In this example, two entities have been assigned the AcrImageSigner role: a service principal named "service-principal," and a user named "Azure User."

在 Azure 门户中为注册表启用内容信任

Azure CLIAzure CLI

若要通过 Azure CLI 向用户授予签名权限,请为用户分配局限于注册表的 AcrImageSigner 角色。To grant signing permissions to a user with the Azure CLI, assign the AcrImageSigner role to the user, scoped to your registry. 该命令的格式如下:The format of the command is:

az role assignment create --scope <registry ID> --role AcrImageSigner --assignee <user name>

例如,若要将该角色授予自己,可以在经身份验证的 Azure CLI 会话中运行以下命令。For example, to grant yourself the role, you can run the following commands in an authenticated Azure CLI session. 修改 REGISTRY 值,使之反映 Azure 容器注册表的名称。Modify the REGISTRY value to reflect the name of your Azure container registry.

# Grant signing permissions to authenticated Azure CLI user
REGISTRY=myregistry
USER=$(az account show --query user.name --output tsv)
REGISTRY_ID=$(az acr show --name $REGISTRY --query id --output tsv)

az role assignment create --scope $REGISTRY_ID --role AcrImageSigner --assignee $USER

也可向服务主体授予将受信任的映像推送到注册表的权限。You can also grant a service principal the rights to push trusted images to your registry. 服务主体适用于需将受信任的映像推送到注册表的生成系统和其他无人参与系统。Using a service principal is useful for build systems and other unattended systems that need to push trusted images to your registry. 格式与授予用户权限类似,但需为 --assignee 值指定一个服务主体 ID。The format is similar to granting a user permission, but specify a service principal ID for the --assignee value.

az role assignment create --scope $REGISTRY_ID --role AcrImageSigner --assignee <service principal ID>

<service principal ID> 可以是服务主体的 appIdobjectId 或其 servicePrincipalName 之一。The <service principal ID> can be the service principal's appId, objectId, or one of its servicePrincipalNames. 若要详细了解如何使用服务主体和 Azure 容器注册表,请参阅使用服务主体的 Azure 容器注册表身份验证For more information about working with service principals and Azure Container Registry, see Azure Container Registry authentication with service principals.

在任何角色更改后,运行 az acr login 以刷新 Azure CLI 的本地标识令牌,以便新角色生效。After any role changes, run az acr login to refresh the local identity token for the Azure CLI so that the new roles can take effect.

推送受信任的映像Push a trusted image

若要将受信任的映像标记推送到容器注册表,请启用内容信任并使用 docker push 推送映像。To push a trusted image tag to your container registry, enable content trust and push the image with docker push. 首次推送签名的标记时,系统会要求你为根签名密钥和存储库签名密钥创建通行短语。The first time you push a signed tag, you're asked to create a passphrase for both a root signing key and a repository signing key. 根密钥和存储库密钥都是以本地方式在计算机上生成并存储的。Both the root and repository keys are generated and stored locally on your machine.

$ docker push myregistry.azurecr.io/myimage:v1
The push refers to repository [myregistry.azurecr.io/myimage]
ee83fc5847cb: Pushed
v1: digest: sha256:aca41a608e5eb015f1ec6755f490f3be26b48010b178e78c00eac21ffbe246f1 size: 524
Signing and pushing trust metadata
You are about to create a new root signing key passphrase. This passphrase
will be used to protect the most sensitive key in your signing system. Please
choose a long, complex passphrase and be careful to keep the password and the
key file itself secure and backed up. It is highly recommended that you use a
password manager to generate the passphrase and keep it safe. There will be no
way to recover this key. You can find the key in your config directory.
Enter passphrase for new root key with ID 4c6c56a:
Repeat passphrase for new root key with ID 4c6c56a:
Enter passphrase for new repository key with ID bcd6d98:
Repeat passphrase for new repository key with ID bcd6d98:
Finished initializing "myregistry.azurecr.io/myimage"
Successfully signed myregistry.azurecr.io/myimage:v1

首次在启用内容信任的情况下执行 docker push 后,Docker 客户端会使用同一根密钥进行后续推送。After your first docker push with content trust enabled, the Docker client uses the same root key for subsequent pushes. 每次将内容后续推送到同一存储库时,系统只要求提供存储库密钥。On each subsequent push to the same repository, you're asked only for the repository key. 每次将受信任的映像推送到新存储库时,系统会要求提供新存储库密钥的通行短语。Each time you push a trusted image to a new repository, you're asked to supply a passphrase for a new repository key.

拉取受信任的映像Pull a trusted image

若要拉取受信任的映像,请照常启用内容信任并运行 docker pull 命令。To pull a trusted image, enable content trust and run the docker pull command as normal. 若要拉取受信任的映像,AcrPull 角色对于普通用户来说已足够了。To pull trusted images, the AcrPull role is enough for normal users. 无需任何其他角色(如 AcrImageSigner 角色)。No additional roles like an AcrImageSigner role are required. 在启用内容信任的情况下,使用者只能拉取带签名标记的映像。Consumers with content trust enabled can pull only images with signed tags. 下面是拉取签名标记的示例:Here's an example of pulling a signed tag:

$ docker pull myregistry.azurecr.io/myimage:signed
Pull (1 of 1): myregistry.azurecr.io/myimage:signed@sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b
sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b: Pulling from myimage
8e3ba11ec2a2: Pull complete
Digest: sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b
Status: Downloaded newer image for myregistry.azurecr.io/myimage@sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b
Tagging myregistry.azurecr.io/myimage@sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b as myregistry.azurecr.io/myimage:signed

如果客户端在启用内容信任的情况下尝试拉取未签名的标记,则操作会失败:If a client with content trust enabled tries to pull an unsigned tag, the operation fails:

$ docker pull myregistry.azurecr.io/myimage:unsigned
No valid trust data for unsigned

幕后Behind the scenes

运行 docker pull 时,Docker 客户端使用与 Notary CLI 中的库相同的库为要拉取的标记请求 tag-to-SHA-256 摘要映射。When you run docker pull, the Docker client uses the same library as in the Notary CLI to request the tag-to-SHA-256 digest mapping for the tag you're pulling. 在验证信任数据上的签名以后,客户端会指示 Docker 引擎执行“按摘要进行的拉取”操作。After validating the signatures on the trust data, the client instructs Docker Engine to do a "pull by digest." 在拉取过程中,引擎使用 SHA-256 校验和作为内容地址,以便从 Azure 容器注册表请求映像清单并对其进行验证。During the pull, the Engine uses the SHA-256 checksum as a content address to request and validate the image manifest from the Azure container registry.

密钥管理Key management

如推送第一个受信任映像时的 docker push 输出中所述,根密钥是最敏感的。As stated in the docker push output when you push your first trusted image, the root key is the most sensitive. 请确保备份根密钥并将其存储在安全的位置。Be sure to back up your root key and store it in a secure location. 默认情况下,Docker 客户端将签名密钥存储在以下目录中:By default, the Docker client stores signing keys in the following directory:

~/.docker/trust/private

请备份根密钥和存储库密钥,方法是先在存档中将其压缩,然后将其安全地进行脱机存储(例如存储在 USB 存储设备上)。Back up your root and repository keys by compressing them in an archive and storing it securely offline (such as on a USB storage device). 例如,在 Bash 中执行以下代码:For example, in Bash:

umask 077; tar -zcvf docker_private_keys_backup.tar.gz ~/.docker/trust/private; umask 022

在推送受信任的映像时,除了本地生成的根密钥和存储库密钥,Azure 容器注册表还会生成并存储多个其他的密钥。Along with the locally generated root and repository keys, several others are generated and stored by Azure Container Registry when you push a trusted image. 若要详细讨论 Docker 的内容信任实施中的各种密钥,包括其他管理指南,请参阅 Docker 文档中的管理内容信任的密钥For a detailed discussion of the various keys in Docker's content trust implementation, including additional management guidance, see Manage keys for content trust in the Docker documentation.

丢失根密钥Lost root key

如果无法访问根密钥,则无法访问其标记使用该密钥签名的任何存储库中的签名标记。If you lose access to your root key, you lose access to the signed tags in any repository whose tags were signed with that key. 如果映像标记是使用已丢失根密钥签名的,则 Azure 容器注册表无法还原对此类标记的访问权限。Azure Container Registry cannot restore access to image tags signed with a lost root key. 若要删除注册表的所有信任数据(签名),请先禁用注册表的内容信任,然后再重新启用它。To remove all trust data (signatures) for your registry, first disable, then re-enable content trust for the registry.

警告

如果在禁用注册表中的内容信任后重新启用它,则会删除注册表的所有存储库中所有已签名标记的所有信任数据Disabling and re-enabling content trust in your registry deletes all trust data for all signed tags in every repository in your registry. 此操作不可逆--Azure 容器注册表不能恢复已删除的信任数据。This action is irreversible--Azure Container Registry cannot recover deleted trust data. 禁用内容信任不会删除映像本身。Disabling content trust does not delete the images themselves.

若要禁用注册表的内容信任,请在 Azure 门户中导航到注册表。To disable content trust for your registry, navigate to the registry in the Azure portal. 在“策略” 下选择“内容信任” > “禁用” > “保存”。Under Policies, select Content Trust > Disabled > Save. 系统会警告:你会丢失注册表中的所有签名。You're warned of the loss of all signatures in the registry. 选择“确定”即可永久删除注册表中的所有签名。 Select OK to permanently delete all signatures in your registry.

在 Azure 门户中禁用注册表的内容信任

后续步骤Next steps

有关内容信任的其他信息,请参阅 Docker 中的内容信任See Content trust in Docker for additional information about content trust. 虽然本文介绍了一些要点,但内容信任是一个范围广泛的主题,若要深入进行了解,请查看 Docker 文档。While several key points were touched on in this article, content trust is an extensive topic and is covered more in-depth in the Docker documentation.