Доверие к содержимому в Реестре контейнеров AzureContent 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".Content trust is a feature of the Premium service tier 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:stable и myimage: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. Подробные сведения см. в разделе Управление ключами этой статьи, а также на странице Manage keys for content trust (Управление ключами функции доверия к содержимому) документации 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. Более подробное описание см. в статье Content trust in Docker (Функция доверия к содержимому в 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. Можно также выполнить команду az acr config content-trust update в Azure CLI.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 значение 1.To 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

Если нужно включить или отключить доверие для одной команды, аргумент --disable-content-trust поддерживается несколькими командами Docker.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. Чтобы выдать такое разрешение пользователю (или системе через субъект-службу), назначьте ему роль AcrImageSigner в Azure Active DirectoryTo 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.

Важно!

Вы не можете предоставить надежное разрешение на принудительную отправку изображений следующим учетным записям администратора:You can't grant trusted image push permission to the following administrative accounts:

Далее описано, как назначить роль AcrImageSigner на портале Azure и в инфраструктуре Azure CLI.Details for granting the AcrImageSigner role in the Azure portal and the Azure CLI follow.

Портал AzureAzure 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 a non-administrative user 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
REGISTRY_ID=$(az acr show --name $REGISTRY --query id --output tsv)
az role assignment create --scope $REGISTRY_ID --role AcrImageSigner --assignee azureuser@contoso.com

Также можно выдать права на отправку образов в реестр субъекту-службе.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> можно указать appId или objectId субъекта-службы или одно из его имен servicePrincipalNames.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. Сведения о проверке ролей для удостоверения см. в статье Добавление и удаление назначений ролей Azure с помощью Azure CLI и Устранение неполадок в Azure RBAC.For information about verifying roles for an identity, see Add or remove Azure role assignments using Azure CLI and Troubleshoot Azure RBAC.

Отправка доверенного образа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. После первого выполнения принудительной отправки с подписанным тегом вам будет предложено создать парольную фразу как для корневого ключа подписывания, так и для ключа подписывания репозитория.After push with a signed tag completes the first time, 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 with an error similar to the following:

$ docker pull myregistry.azurecr.io/myimage:unsigned
Error: remote trust data does not exist

Сопутствующие ресурсы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 Engine "извлечь по хэшу".After validating the signatures on the trust data, the client instructs Docker Engine to do a "pull by digest." При извлечении Engine использует контрольную сумму 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.

Примечание

Реестр контейнеров Azure официально не поддерживает интерфейс командной строки Нотари, но совместим с API сервера Нотари, который входит в состав DOCKER Desktop.Azure Container Registry does not officially support the Notary CLI but is compatible with the Notary Server API, which is included with Docker Desktop. Сейчас рекомендуется Нотари версии 0.6.0 .Currently Notary version 0.6.0 is recommended.

Управление ключами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 при отправке доверенного образа.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 см. на странице Manage keys for content trust (Управление ключами функции доверия к содержимому) документации 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 и Делегирование доверия, см. в разделе " доверие содержимого в DOCKER ".See Content trust in Docker for additional information about content trust, including docker trust commands and trust delegations. В этой статье мы затронули лишь ключевые моменты обширной темы доверия к содержимому, которая более подробно рассматривается в документации 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.