Azure Container Registry 中的內容信任Content trust in Azure Container Registry

Azure Container Registry 會實作 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 Container Registry 進階 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:devFor 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 CLI 中的az acr config content-trust update命令。You can also use the az acr config content-trust update command in the Azure CLI.

在 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 用戶端中依預設會停用內容信任,但您可以依據殼層工作階段或命令加以啟用。Content trust is disabled by default in Docker clients, but you can enable it per shell session or per command.

若要啟用殼層工作階段的內容信任,請將 DOCKER_CONTENT_TRUST 環境變數設定為 1To enable content trust for a shell session, set the DOCKER_CONTENT_TRUST environment variable to 1. 例如,在 Bash 殼層中: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 .

如果您已啟用殼層工作階段的內容信任,而想要針對單一命令加以停用: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 Container Registry 角色和權限For details, see Azure Container Registry roles and permissions.

注意

您無法將受信任的映射推播許可權授與 Azure container registry 的系統管理員帳戶You can't grant trusted image push permission to the admin account of an Azure container registry.

下文會詳細說明如何在 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 User" 的使用者。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 Container Registry 名稱。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 值。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,或其 servicePrincipalNames 之一。The <service principal ID> can be the service principal's appId, objectId, or one of its servicePrincipalNames. 如需使用服務主體與 Azure Container Registry 的詳細資訊,請參閱使用服務主體進行 Azure Container Registry 驗證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. 如需驗證身分識別角色的詳細資訊,請參閱使用 rbac 來管理 azure 資源的存取權和 Azure CLI針對 AZURE 資源的 RBAC 進行疑難排解For information about verifying roles for an identity, see Manage access to Azure resources using RBAC and Azure CLI and Troubleshoot RBAC for Azure resources.

推送信任的映像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 中相同的程式庫,針對您要提取的標記要求標記與 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 Container Registry 的映像資訊清單。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

將根金鑰和存放庫金鑰壓縮在封存檔中,並儲存於安全的位置,加以備份。Back up your root and repository keys by compressing them in an archive and storing it in a secure location. 例如,在 Bash 中:For example, in Bash:

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

除了在本機產生的根金鑰和存放庫金鑰以外,當您推送信任的映像時,Azure Container Registry 還會產生並儲存數個其他的金鑰。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 Container Registry 無法對以遺失的根金鑰簽署的映像標記進行存取權還原。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 Container Registry 無法復原已刪除的信任資料。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.

  • 在建置和推送 Docker 映像時如需使用內容信任的範例,請參閱 Azure Pipelines 文件。See the Azure Pipelines documentation for an example of using content trust when you build and push a Docker image.