Confiança de conteúdo no Registro de Contêiner do AzureContent trust in Azure Container Registry

O Registro de Contêiner do Azure implementa o modelo de relação de confiança do conteúdo do Docker, permitindo push e pull de imagens assinadas.Azure Container Registry implements Docker's content trust model, enabling pushing and pulling of signed images. Este artigo mostra como habilitar a relação de confiança do conteúdo em seus registros de contêiner.This article gets you started enabling content trust in your container registries.

Observação

A relação de confiança é um recurso do SKU Premium do Registro de Contêiner do Azure.Content trust is a feature of the Premium SKU of Azure Container Registry.

Como a confiança de conteúdo funcionaHow content trust works

Um fator importante para todos os sistemas distribuídos que foram criados tendo a segurança como foco, é verificar a origem e a integridade dos dados que entram no sistema.Important to any distributed system designed with security in mind is verifying both the source and the integrity of data entering the system. É essencial que os consumidores dos dados consigam verificar o editor (fonte) dos dados e garantir que ele não tenha sido modificado após a publicação (integridade).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).

Por ser um editor de imagens, a confiança de conteúdo permite que você assine as imagens que serão enviadas ao registro.As an image publisher, content trust allows you to sign the images you push to your registry. Os consumidores de suas imagens (pessoas ou sistemas que efetuam pull das imagens de seu registro) podem configurar seus clientes para enviar apenas imagens assinadas.Consumers of your images (people or systems pulling images from your registry) can configure their clients to pull only signed images. Quando um consumidor de imagens efetua pull de uma imagem assinada, seu cliente do Docker verifica a integridade da imagem.When an image consumer pulls a signed image, their Docker client verifies the integrity of the image. Nesse modelo, os consumidores têm a garantia de que as imagens assinadas em seu registro foram de fato publicadas por você e que não foram modificadas desde sua publicação.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.

Imagens confiáveisTrusted images

A confiança de conteúdo funciona com as marcas em um repositório.Content trust works with the tags in a repository. Os repositórios de imagens podem conter imagens com marcas assinadas e não assinadas.Image repositories can contain images with both signed and unsigned tags. Por exemplo, você pode assinar as imagens myimage:stable e myimage:latest apenas, mas não pode assinar myimage:dev.For example, you might sign only the myimage:stable and myimage:latest images, but not myimage:dev.

Chaves de assinaturaSigning keys

A confiança de conteúdo é gerenciada usando um conjunto de chaves de assinatura criptográficas.Content trust is managed through the use of a set of cryptographic signing keys. Essas chaves são associadas a um repositório específico em um registro.These keys are associated with a specific repository in a registry. Existem vários tipos de chaves de assinatura que os clientes do Docker e seu registro usam para gerenciar a confiança das marcas em um repositório.There are several types of signing keys that Docker clients and your registry use in managing trust for the tags in a repository. Ao ativar a confiança de conteúdo e integrá-la ao pipeline de publicação e consumo de contêiner, você deve gerenciar essas chaves com cuidado.When you enable content trust and integrate it into your container publishing and consumption pipeline, you must manage these keys carefully. Para mais informações, confira Gerenciamento de chaves mais adiante neste artigo e Gerenciar chaves para a confiança de conteúdo na documentação do Docker.For more information, see Key management later in this article and Manage keys for content trust in the Docker documentation.

Dica

Essa foi uma visão geral de alto nível do modelo de confiança de conteúdo do Docker.This was a very high-level overview of Docker's content trust model. Para ver uma discussão detalhada sobre a confiança de conteúdo, confira Confiança de conteúdo no Docker.For an in-depth discussion of content trust, see Content trust in Docker.

Habilitar a confiança de conteúdo do registroEnable registry content trust

A primeira etapa é habilitar a confiança de conteúdo no nível do registro.Your first step is to enable content trust at the registry level. Depois de habilitar a confiança de conteúdo, os clientes (usuários ou serviços) poderão enviar imagens assinadas para o registro.Once you enable content trust, clients (users or services) can push signed images to your registry. A ativação da confiança de conteúdo em seu registro não restringirá o uso do registro apenas a consumidores que têm a confiança de conteúdo ativada.Enabling content trust on your registry does not restrict registry usage only to consumers with content trust enabled. Os consumidores que não têm a confiança de conteúdo ativada poderão continuar a usar o registro normalmente.Consumers without content trust enabled can continue to use your registry as normal. No entanto, os consumidores que ativaram a confiança de conteúdo em seus clientes verão apenas imagens assinadas em seu registro.Consumers who have enabled content trust in their clients, however, will be able to see only signed images in your registry.

Para habilitar a confiança de conteúdo para o registro, primeiro, navegue até o registro no portal do Azure.To enable content trust for your registry, first navigate to the registry in the Azure portal. Em Políticas, selecione Confiança de Conteúdo > Habilitada > Salvar.Under Policies, select Content Trust > Enabled > Save. Você também pode usar o comando AZ ACR config Content-Trust Update na CLI do Azure.You can also use the az acr config content-trust update command in the Azure CLI.

Habilitar a confiança de conteúdo para um registro no portal do Azure

Habilitar a confiança de conteúdo do clienteEnable client content trust

Para trabalhar com imagens confiáveis, os editores e consumidores de imagens precisam ativar a confiança de conteúdo para seus clientes do Docker.To work with trusted images, both image publishers and consumers need to enable content trust for their Docker clients. Como editor, você pode assinar as imagens que envia ao registro habilitado para a confiança de conteúdo.As a publisher, you can sign the images you push to a content trust-enabled registry. Como consumidor, a ativação da confiança de conteúdo limita sua exibição de um registro apenas a imagens assinadas.As a consumer, enabling content trust limits your view of a registry to signed images only. A confiança de conteúdo é desabilitada por padrão nos clientes do Docker, mas você pode ativá-la por sessão de shell ou por comando.Content trust is disabled by default in Docker clients, but you can enable it per shell session or per command.

Para habilitar a confiança de conteúdo para uma sessão do shell, defina a variável de ambiente DOCKER_CONTENT_TRUST como 1.To enable content trust for a shell session, set the DOCKER_CONTENT_TRUST environment variable to 1. Por exemplo, no shell Bash:For example, in the Bash shell:

# Enable content trust for shell session
export DOCKER_CONTENT_TRUST=1

Se, em vez disso, você quiser ativar ou desativar a confiança de conteúdo para um único comando, vários comandos do Docker suportam o argumento --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. Para habilitar a confiança de conteúdo de um único comando: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 .

Se você tiver habilitado a confiança de conteúdo para a sessão do shell e quiser desabilitá-la para um único comando: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 .

Conceder permissões de assinatura de imagensGrant image signing permissions

Somente os usuários ou sistemas com permissão podem enviar imagens confiáveis para seu registro.Only the users or systems you've granted permission can push trusted images to your registry. Para conceder permissão de envio de imagens confiáveis a um usuário (ou a um sistema usando uma entidade de serviço), conceda às identidades do Azure Active Directory a função 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. Isso é um acréscimo à função AcrPush (ou equivalente) necessária para enviar imagens por push para o registro.This is in addition to the AcrPush (or equivalent) role required for pushing images to the registry. Para obter detalhes, confira Funções e permissões do Registro de Contêiner do Azure.For details, see Azure Container Registry roles and permissions.

Observação

Você não pode conceder permissão de push de imagem confiável para a conta de administrador de um registro de contêiner do Azure.You can't grant trusted image push permission to the admin account of an Azure container registry.

Detalhes para a concessão da função AcrImageSigner no portal do Azure e na CLI do Azure são os seguintes.Details for granting the AcrImageSigner role in the Azure portal and the Azure CLI follow.

Portal do AzureAzure portal

Navegue até seu registro no portal do Azure e escolha Controle de Acesso (IAM) > Adicionar atribuição de função.Navigate to your registry in the Azure portal, then select Access control (IAM) > Add role assignment. Em Adicionar atribuição de função, escolha AcrImageSigner em Função e Selecionar um ou mais usuários ou entidades de serviço e, em seguida, Salvar.Under Add role assignment, select AcrImageSigner under Role, then Select one or more users or service principals, then Save.

Neste exemplo, duas entidades receberam a função AcrImageSigner: uma entidade de serviço chamada "service-principal" e um usuário chamado "Usuário do Azure".In this example, two entities have been assigned the AcrImageSigner role: a service principal named "service-principal," and a user named "Azure User."

Habilitar a confiança de conteúdo para um registro no portal do Azure

CLI do AzureAzure CLI

Para conceder permissões de assinatura a um usuário com a CLI do Azure, atribua a função AcrImageSigner ao usuário no escopo do registro.To grant signing permissions to a user with the Azure CLI, assign the AcrImageSigner role to the user, scoped to your registry. O formato do comando é:The format of the command is:

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

Por exemplo, para conceder a você mesmo a função, execute os seguintes comandos em uma sessão autenticada da CLI do Azure.For example, to grant yourself the role, you can run the following commands in an authenticated Azure CLI session. Modifique o valor REGISTRY para refletir o nome do registro de contêiner do 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

Você também pode conceder a uma entidade de serviço os direitos de envio de imagens confiáveis para o registro.You can also grant a service principal the rights to push trusted images to your registry. O uso de uma entidade de serviço é útil para sistemas de compilação e outros sistemas autônomos que precisam enviar imagens confiáveis para seu registro.Using a service principal is useful for build systems and other unattended systems that need to push trusted images to your registry. O formato é semelhante a conceder uma permissão de usuário, mas especifica a ID de uma entidade de serviço com o valor --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>

A <service principal ID> pode ser a appId, objectId da entidade de serviço ou um de seus servicePrincipalNames.The <service principal ID> can be the service principal's appId, objectId, or one of its servicePrincipalNames. Para mais informações sobre como trabalhar com entidades de serviço e o Registro de Contêiner do Azure, confira Autenticação do Registro de Contêiner do Azure com entidades de serviço.For more information about working with service principals and Azure Container Registry, see Azure Container Registry authentication with service principals.

Importante

Depois de quaisquer alterações de função, execute az acr login para atualizar o token de identidade local para a CLI do Azure para que as novas funções entrem em vigor.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. Para obter informações sobre como verificar funções para uma identidade, consulte gerenciar o acesso aos recursos do Azure usando RBAC e CLI do Azure e solucionar problemas de RBAC para recursos do Azure.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.

Enviar uma imagem confiável por pushPush a trusted image

Para enviar uma marca de imagem confiável por push ao registro de contêiner, ative a confiança de conteúdo e envie a imagem com docker push.To push a trusted image tag to your container registry, enable content trust and push the image with docker push. Ao enviar uma marca assinada pela primeira vez, você é solicitado a criar uma frase secreta para uma chave de assinatura raiz e uma chave de assinatura do repositório.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. As chaves raiz e de repositório são geradas e armazenadas localmente em seu computador.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

Após o primeiro docker push com a confiança de conteúdo ativada, o cliente do Docker usará a mesma chave raiz para os envios subsequentes.After your first docker push with content trust enabled, the Docker client uses the same root key for subsequent pushes. A cada envio subsequente para o mesmo repositório, você será solicitado a fornecer apenas a chave do repositório.On each subsequent push to the same repository, you're asked only for the repository key. Todas as vezes que você envia uma imagem confiável a um novo repositório, você é solicitado a fornecer uma frase secreta para uma nova chave de repositório.Each time you push a trusted image to a new repository, you're asked to supply a passphrase for a new repository key.

Efetuar pull de uma imagem confiávelPull a trusted image

Para efetuar pull de uma imagem confiável, habilite a confiança de conteúdo e execute o comando docker pull normalmente.To pull a trusted image, enable content trust and run the docker pull command as normal. Para efetuar pull de imagens confiáveis, a função AcrPull é suficiente para usuários normais.To pull trusted images, the AcrPull role is enough for normal users. Não há necessidade de funções adicionais como a função AcrImageSigner.No additional roles like an AcrImageSigner role are required. Os consumidores que têm a confiança de conteúdo habilitada só podem efetuar pull de imagens com marcas assinadas.Consumers with content trust enabled can pull only images with signed tags. Veja um exemplo da realização de um pull de uma marca assinada: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

Se um cliente que tenha a confiança de conteúdo habilitada tentar efetuar pull de uma marca não assinada, a operação falhará: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

Nos bastidoresBehind the scenes

Quando você executa o docker pull, o cliente do Docker usa a mesma biblioteca da CLI do Notary para solicitar o mapeamento resumido de marca para SHA-256 para a marca que você está efetuando pull.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. Após validar as assinaturas nos dados de confiança, o cliente instrui o Docker Engine a "efetuar um pull por resumo".After validating the signatures on the trust data, the client instructs Docker Engine to do a "pull by digest." Durante a realização do pull, o mecanismo usa a soma de verificação de SHA-256 como um endereço de conteúdo para solicitar e validar o manifesto da imagem do registro do contêiner do 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.

Gerenciamento de chavesKey management

Conforme declarado na saída docker push, ao enviar sua primeira imagem confiável, a chave raiz será a mais confidencial.As stated in the docker push output when you push your first trusted image, the root key is the most sensitive. Lembre-se de fazer backup da chave raiz e armazená-la em um local seguro.Be sure to back up your root key and store it in a secure location. Por padrão, o cliente do Docker armazena as chaves de assinatura no seguinte diretório:By default, the Docker client stores signing keys in the following directory:

~/.docker/trust/private

Faça backup de suas chaves raiz e de repositório compactando-as em um arquivo morto e armazenando-o em um local seguro.Back up your root and repository keys by compressing them in an archive and storing it in a secure location. Por exemplo, no Bash:For example, in Bash:

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

Juntamente com as chaves raiz e de repositório geradas localmente, várias outras são geradas e armazenadas pelo Registro de Contêiner do Azure quando você envia uma imagem confiável.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. Para ter acesso a uma discussão detalhada sobre as várias chaves na implementação da confiança de conteúdo do Docker, incluindo orientação adicional de gerenciamento, confira Gerenciar chaves para a confiança de conteúdo na documentação do 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.

Chave raiz perdidaLost root key

Se perder o acesso à sua chave raiz, você perderá o acesso às marcas assinadas em todos os repositórios cujas marcas foram assinadas com essa chave.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. O Registro de Contêiner do Azure não consegue restaurar o acesso às marcas de imagem assinada com uma chave raiz perdida.Azure Container Registry cannot restore access to image tags signed with a lost root key. Para remover todos os dados de confiança (assinaturas) do registro, primeiro, desabilite e habilite novamente a confiança de conteúdo do registro.To remove all trust data (signatures) for your registry, first disable, then re-enable content trust for the registry.

Aviso

O ato de desabilitar e reabilitar o conteúdo de confiança no registro excluirá todos os dados de confiança de todas as marcas assinadas em todos os repositórios do registro.Disabling and re-enabling content trust in your registry deletes all trust data for all signed tags in every repository in your registry. Essa ação é irreversível. O Registro de Contêiner do Azure não consegue recuperar dados de confiança excluídos.This action is irreversible--Azure Container Registry cannot recover deleted trust data. Desabilitar a confiança de conteúdo não excluirá as próprias imagens.Disabling content trust does not delete the images themselves.

Para desabilitar a confiança de conteúdo do registro, primeiro, navegue até o registro no portal do Azure.To disable content trust for your registry, navigate to the registry in the Azure portal. Em Políticas, selecione Confiança de Conteúdo > Desabilitada > Salvar.Under Policies, select Content Trust > Disabled > Save. Você já foi alertado sobre a perda de todas as assinaturas no registro.You're warned of the loss of all signatures in the registry. Escolha OK para excluir permanentemente todas as assinaturas do registro.Select OK to permanently delete all signatures in your registry.

Desabilitar a confiança de conteúdo de um registro no portal do Azure

Próximas etapasNext steps

  • Confira Confiança de conteúdo no Docker para ver mais informações sobre a confiança de conteúdo.See Content trust in Docker for additional information about content trust. Apesar de vários pontos importantes terem sido abordados neste artigo, a confiança de conteúdo é um tópico amplo e será abordado com mais detalhes na documentação do 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.

  • Consulte a documentação do Azure Pipelines para obter um exemplo de como usar a confiança de conteúdo ao criar e efetuar push de uma imagem do Docker.See the Azure Pipelines documentation for an example of using content trust when you build and push a Docker image.