Confiança do conteúdo no Azure Container Registry

  • Artigo

O Registro de Contêiner do Azure implementa o modelo de confiança de conteúdo do Docker, permitindo o envio por push e a extração de imagens assinadas. Este artigo ajuda você a começar a habilitar a confiança de conteúdo em seus registros de contêiner.

Nota

A confiança de conteúdo é um recurso da camada de serviço Premium do Registro de Contêiner do Azure.

Limitações

  • Atualmente, o token com permissões com escopo de repositório não suporta docker push e pull de imagens assinadas.

Como funciona a confiança do conteúdo

Verificar a origem e a integridade dos dados que entram no sistema é importante para qualquer sistema distribuído desenhado tendo em conta a segurança. Os consumidores dos dados têm de poder verificar o publicador (origem) dos dados e garantir que os mesmos não foram modificados depois de terem sido publicados (integridade).

Enquanto publicador de imagens, a confiança do conteúdo permite-lhe assinar as imagens que envia para o seu registo. Os consumidores dessas imagens (pessoas ou sistemas que extraem as imagens do seu registo) podem configurar os clientes deles para extrair apenas as imagens assinadas. Quando um consumidor de imagens extrai uma imagem assinada, o cliente do Docker dele verifica a integridade da mesma. Neste modelo, os consumidores ficam com a garantia de que as imagens assinadas no seu registo foram realmente publicadas por si e que não foram modificadas desde a publicação.

Nota

O Azure Container Registry (ACR) não oferece suporte acr import à importação de imagens assinadas com o Docker Content Trust (DCT). Por design, as assinaturas não são visíveis após a importação, e o notário v2 armazena essas assinaturas como artefatos.

Imagens fiáveis

A confiança do conteúdo funciona com as etiquetas num repositório. Os repositórios de imagens podem conter imagens com etiquetas assinadas e não assinadas. Por exemplo, pode assinar apenas as imagens myimage:stable e myimage:latest, mas não myimage:dev.

Chaves de assinatura

A confiança do conteúdo é gerida com um conjunto de chaves de assinatura criptográficas. Essas chaves são associadas a um repositório específico num registo. Os clientes do Docker e o seu registo utilizam vários tipos de chaves de assinatura para a gestão da confiança das etiquetas num repositório. Quando ativa a confiança do conteúdo e a integra no pipeline de publicação e consumo do seu contentor, tem de gerir as chaves com cuidado. Para obter mais informações, veja Gestão de chaves, mais à frente no artigo, e Manage keys for content trust (Gerir chaves para a confiança do conteúdo), na documentação do Docker.

Gorjeta

Esta é uma descrição geral bastante genérica do modelo de confiança do conteúdo do Docker. Para uma discussão mais aprofundada da confiança do conteúdo, veja Content trust in Docker (Confiança do conteúdo no Docker).

Ativar a confiança do conteúdo do registo

O primeiro passo é ativar a confiança do conteúdo ao nível do registo. Depois de ativar a confiança do conteúdo, os clientes (utilizadores ou serviços) podem enviar imagens assinadas para o seu registo. A ativação da confiança do conteúdo no seu registo não limita a utilização do mesmo apenas aos consumidores que tenham a confiança ativada. Os consumidores que não a tenham ativada continuam a poder utilizar o seu registo como normalmente. Contudo, os consumidores que tenham ativado a confiança do conteúdo nos clientes deles conseguirão ver apenas as imagens assinadas no seu registo.

Para ativar a confiança do conteúdo no seu registo, navegue primeiro para o mesmo no portal do Azure. Em Políticas, selecione Confiança no Conteúdo Ativada para Salvar>>. Você também pode usar o comando az acr config content-trust update na CLI do Azure.

Screenshot shows enabling content trust for a registry in the Azure portal.

Ativar a confiança do conteúdo no cliente

Para trabalhar com as imagens fiáveis, tanto os publicadores de imagens, como os consumidores, têm de ativar a confiança do conteúdo nos respetivos clientes do Docker. Enquanto publicador, pode assinar as imagens que envia para um registo com a confiança do conteúdo ativada. Enquanto consumidor, a ativação da confiança limita a visualização dos registos apenas às imagens assinadas. A confiança do conteúdo está desativada por predefinição nos clientes do Docker, mas pode ativá-la por sessão da shell ou por comando.

Para ativar a confiança do conteúdo para uma sessão da shell, defina a variável de ambiente DOCKER_CONTENT_TRUST como 1. Por exemplo, na shell do Bash:

# Enable content trust for shell session
export DOCKER_CONTENT_TRUST=1

Se preferir ativar ou desativar a confiança do conteúdo para um comando individual, vários comandos do Docker suportam o argumento --disable-content-trust. Para ativar a confiança do conteúdo para um comando individual:

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

Se tiver ativado a confiança do conteúdo para a sessão da shell e quiser desativá-la para um comando individual:

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

Conceder permissões de assinatura de imagens

Só os utilizadores ou sistemas aos quais tenha concedido permissão podem enviar imagens fiáveis para o seu registo. Para conceder permissão por push de imagem confiável a um usuário (ou a um sistema usando uma entidade de serviço), conceda a função às AcrImageSigner identidades do Microsoft Entra. Isso é além da AcrPush função (ou equivalente) necessária para enviar imagens para o registro. Para obter detalhes, consulte Funções e permissões do Registro de Contêiner do Azure.

Importante

Não é possível conceder permissão de envio de imagem confiável para as seguintes contas administrativas:

Nota

A partir de julho de 2021, a função inclui tanto a AcrImageSigner ação quanto a Microsoft.ContainerRegistry/registries/sign/write ação de Microsoft.ContainerRegistry/registries/trustedCollections/write dados.

Pode ver abaixo os detalhes para conceder a função AcrImageSigner no portal do Azure e na CLI do Azure.

Portal do Azure

  1. Selecione Controlo de acesso (IAM) .

  2. Selecione Adicionar atribuição de função para abrir a página Adicionar>atribuição de função.

  3. Atribua a seguinte função. Neste exemplo, a função é atribuída a um usuário individual. Para obter os passos detalhados, veja o artigo Atribuir funções do Azure com o portal do Azure.

    Definição Valor
    Função AcrImageSigner
    Atribuir acesso a User
    Membros Guilherme

    Add role assignment page in Azure portal.

CLI do Azure

Para conceder permissões de assinatura a um utilizador com a CLI do Azure, atribua-lhe a função AcrImageSigner, com âmbito para o seu registo. O formato do comando é:

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

Por exemplo, para conceder a função a um usuário não administrativo, você pode executar os seguintes comandos em uma sessão autenticada da CLI do Azure. Modifique o valor REGISTRY, de modo a refletir o nome do seu registo de contentor do Azure.

# 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

Também pode conceder a um principal de serviço os direitos para enviar imagens fiáveis para o registo. A utilização de um principal de serviço é útil para sistemas de compilação e para outros sistemas autónomos que têm de enviar imagens fiáveis para o seu registo. O formato é semelhante a conceder permissão a um utilizador, mas é especificado um ID de principal de serviço no valor --assignee.

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

<service principal ID> pode ser appId ou objectId do principal de serviço ou um dos respetivos servicePrincipalNames. Para obter mais informações sobre como trabalhar com os principais de serviço e o Azure Container Registry, veja Azure Container Registry authentication with service principals (Autenticação do Azure Container Registry com principais de serviço).

Importante

Após qualquer alteração 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 possam entrar em vigor. Para obter informações sobre como verificar funções para uma identidade, consulte Adicionar ou remover atribuições de função do Azure usando a CLI do Azure e Solucionar problemas do RBAC do Azure.

Enviar uma imagem fiável

Para enviar uma etiqueta de imagem fiável para o registo de contentor, ative a confiança do conteúdo e envie a imagem com docker push. Depois que o push com uma tag assinada for concluído pela primeira vez, você será solicitado a criar uma senha para uma chave de assinatura raiz e uma chave de assinatura do repositório. Ambas as chaves são geradas e armazenadas localmente no seu computador.

$ 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 seu primeiro docker push com a confiança do conteúdo ativada, o cliente do Docker utiliza a mesma chave raiz para os envios subsequentes. Em cada envio subsequente para o mesmo repositório, só lhe é pedida a chave do repositório. Sempre que enviar uma imagem fiável para um repositório novo, é-lhe pedido que indique uma frase de acesso para uma chave de repositório nova.

Extrair uma imagem fiável

Para extrair uma imagem fiável, ative a confiança do conteúdo e execute o comando docker pull normalmente. Para extrair imagens confiáveis, a AcrPull função é suficiente para usuários normais. Não são necessárias funções adicionais, como uma AcrImageSigner função. Os consumidores que tenham a confiança do conteúdo ativada só podem extrair imagens com etiquetas assinadas. Eis um exemplo de extração de uma etiqueta assinada:

$ 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 com a confiança de conteúdo ativada tentar extrair uma marca não assinada, a operação falhará com um erro semelhante ao seguinte:

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

Nos bastidores

Quando executa docker pull, o cliente do Docker utiliza a mesma biblioteca do Notary CLI para pedir o mapeamento de resumo da etiqueta para SHA-256 relativo à etiqueta que está a extrair. Depois de validar as assinaturas nos dados de confiança, o cliente instrui o Docker Engine a fazer um "pull by digest". Durante a pull, o mecanismo usa a soma de verificação SHA-256 como um endereço de conteúdo para solicitar e validar o manifesto da imagem do registro de contêiner do Azure.

Nota

O Azure Container Registry não suporta oficialmente a CLI do Notary, mas é compatível com a API do Notary Server, que está incluída no Docker Desktop. Atualmente, recomenda-se a versão 0.6.0 do Notary.

Gestão de chaves

Conforme mencionado na saída docker push quando envia a primeira imagem fiável, a chave raiz é a mais sensível. Certifique-se de que cria uma cópia de segurança da mesma e que a armazena numa localização segura. Por predefinição, o cliente do Docker armazena as chaves de assinatura no seguinte diretório:

~/.docker/trust/private

Faça backup de suas chaves raiz e de repositório compactando-as em um arquivo e armazenando-as em um local seguro. Por exemplo, no Bash:

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

Juntamente com as chaves raiz e do repositório geradas localmente, o Azure Container Registry gera e armazena muitas outras quando envia uma imagem fiável. Para uma discussão detalhada das várias chaves na implementação da confiança do conteúdo do Docker, incluindo orientações de gestão adicionais, veja Manage keys for content trust (Gerir chaves para a confiança do conteúdo), na documentação do Docker.

Chave raiz perdida

Se perder o acesso à chave raiz, perde acesso às etiquetas assinadas em todos os repositórios cujas etiquetas tenham sido assinadas com essa chave. O Azure Container Registry não pode restaurar o acesso às etiquetas de imagens assinadas com chaves raiz que se tenham perdido. Para remover todos os dados fiáveis (assinaturas) do seu registo, desative e, depois, reative a confiança do conteúdo para o registo.

Aviso

A desativação e reativação da confiança do conteúdo no registo elimina todos os dados fiáveis de todas as etiquetas assinadas em todos os repositórios no seu registo. Esta ação é irreversível. O Azure Container Registry não consegue recuperar os dados fiáveis eliminados. A desativação da confiança do conteúdo não elimina as imagens.

Para desativar a confiança do conteúdo no seu registo, navegue para o mesmo no portal do Azure. Em Políticas, selecione Confiança no>Conteúdo Desabilitada>Salvar. Recebe um aviso de que todas as assinaturas no registo se vão perder. Selecione OK para eliminar permanentemente todas as assinaturas no seu registo.

Disabling content trust for a registry in the Azure portal

Próximos passos