Attendibilità dei contenuti in Registro Azure ContainerContent trust in Azure Container Registry

Registro Azure Container implementa il modello di attendibilità del contenuto di Docker, abilitando il push e il pull delle immagini firmate.Azure Container Registry implements Docker's content trust model, enabling pushing and pulling of signed images. Questo articolo illustra come abilitare l'attendibilità del contenuto nei registri contenitori.This article gets you started enabling content trust in your container registries.

Nota

L'attendibilità del contenuto è una funzionalità dello SKU Premium di Registro Azure Container.Content trust is a feature of the Premium SKU of Azure Container Registry.

Funzionamento dell'attendibilità dei contenutiHow content trust works

Per ogni sistema distribuito progettato con particolare attenzione alla sicurezza, è importante verificare sia l'origine che l'integrità dei dati in ingresso nel sistema.Important to any distributed system designed with security in mind is verifying both the source and the integrity of data entering the system. I consumer dei dati devono poter verificare l'editore (origine) dei dati, nonché assicurarsi che i dati non siano stati modificati dopo la pubblicazione (integrità).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).

L'attendibilità dei contenuti consente a un editore di immagini di firmare le immagini di cui viene eseguito il push nel registro.As an image publisher, content trust allows you to sign the images you push to your registry. I consumer delle immagini (persone o sistemi che eseguono il pull delle immagini dal registro) possono configurare i client per eseguire il pull solo delle immagini firmate.Consumers of your images (people or systems pulling images from your registry) can configure their clients to pull only signed images. Quando il consumer di un'immagine esegue il pull di un'immagine firmata, il client Docker verifica l'integrità dell'immagine.When an image consumer pulls a signed image, their Docker client verifies the integrity of the image. In questo modello, i consumer hanno la certezza che le immagini firmate siano state effettivamente pubblicate dall'editore indicato e che non siano state modificate dopo la pubblicazione.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.

Immagini attendibiliTrusted images

L'attendibilità dei contenuti funziona con i tag in un repository.Content trust works with the tags in a repository. I repository di immagini possono contenere immagini con tag sia firmati che non firmati.Image repositories can contain images with both signed and unsigned tags. Ad esempio, si potrebbero firmare solo le immagini myimage:stable e myimage:latest, ma non le immagini myimage:dev.For example, you might sign only the myimage:stable and myimage:latest images, but not myimage:dev.

Chiavi di firmaSigning keys

L'attendibilità dei contenuti viene gestita tramite l'uso di un set di chiavi di firma crittografiche.Content trust is managed through the use of a set of cryptographic signing keys. Queste chiavi sono associate a un repository specifico in un registro.These keys are associated with a specific repository in a registry. Ci sono diversi tipi di chiavi di firma che i client Docker e il registro usano per gestire l'attendibilità per i tag in un repository.There are several types of signing keys that Docker clients and your registry use in managing trust for the tags in a repository. Quando si abilita l'attendibilità dei contenuti e la si integra nella pipeline di pubblicazione e utilizzo dei contenitori, è necessario gestire queste chiavi con attenzione.When you enable content trust and integrate it into your container publishing and consumption pipeline, you must manage these keys carefully. Per altre informazioni, vedere Gestione delle chiavi più avanti in questo articolo e Gestire le chiavi per l'attendibilità dei contenuti nella documentazione di Docker.For more information, see Key management later in this article and Manage keys for content trust in the Docker documentation.

Suggerimento

Quella fornita è una panoramica molto generale del modello di attendibilità dei contenuti Docker.This was a very high-level overview of Docker's content trust model. Per un'analisi approfondita dell'attendibilità dei contenuti, vedere Attendibilità dei contenuti in Docker.For an in-depth discussion of content trust, see Content trust in Docker.

Abilitare l'attendibilità dei contenuti nel registroEnable registry content trust

Il primo passaggio consiste nell'abilitare l'attendibilità dei contenuti a livello di registro.Your first step is to enable content trust at the registry level. Una volta abilita l'attendibilità dei contenuti, i client (utenti o servizi) possono eseguire il push delle immagini firmate nel registro.Once you enable content trust, clients (users or services) can push signed images to your registry. L'abilitazione dell'attendibilità dei contenuti nel registro non limita l'utilizzo del registro ai soli consumer per cui è abilitata l'attendibilità dei contenuti.Enabling content trust on your registry does not restrict registry usage only to consumers with content trust enabled. I consumer per cui non è abilitata l'attendibilità dei contenuti possono continuare a usare normalmente il registro.Consumers without content trust enabled can continue to use your registry as normal. I consumer nei cui client è abilitata l'attendibilità dei contenuti, tuttavia, potranno visualizzare solo le immagini firmate nel registro.Consumers who have enabled content trust in their clients, however, will be able to see only signed images in your registry.

Per abilitare l'attendibilità dei contenuti per il registro, passare al registro nel portale di Azure.To enable content trust for your registry, first navigate to the registry in the Azure portal. In Criteri selezionare Attendibilità contenuto > Abilitata > Salva.Under Policies, select Content Trust > Enabled > Save. È anche possibile usare il comando AZ ACR config content-Trust Update nell'interfaccia della riga di comando di Azure.You can also use the az acr config content-trust update command in the Azure CLI.

Abilitazione dell'attendibilità dei contenuti per un registro nel portale di Azure

Abilitare l'attendibilità dei contenuti nel clientEnable client content trust

Per usare immagini attendibili, sia gli editori delle immagini che i loro consumer devono abilitare l'attendibilità dei contenuti per i client Docker.To work with trusted images, both image publishers and consumers need to enable content trust for their Docker clients. Un editore può firmare le immagini di cui esegue il push in un registro abilitato per l'attendibilità dei contenuti.As a publisher, you can sign the images you push to a content trust-enabled registry. Per un consumer, l'abilitazione dell'attendibilità dei contenuti limita la visualizzazione solo alle immagini firmate in un registro.As a consumer, enabling content trust limits your view of a registry to signed images only. L'attendibilità dei contenuti è disabilitata per impostazione predefinita nei client Docker, ma è possibile abilitarla per una sessione di shell o un comando.Content trust is disabled by default in Docker clients, but you can enable it per shell session or per command.

Per abilitare l'attendibilità dei contenuti per una sessione di shell, impostare la variabile di ambiente DOCKER_CONTENT_TRUST su 1.To enable content trust for a shell session, set the DOCKER_CONTENT_TRUST environment variable to 1. Ad esempio, nella shell Bash:For example, in the Bash shell:

# Enable content trust for shell session
export DOCKER_CONTENT_TRUST=1

Se invece si vuole abilitare o disabilitare l'attendibilità dei contenuti per un singolo comando, diversi comandi Docker supportano l'argomento --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. Per abilitare l'attendibilità dei contenuti per un singolo 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 è stata abilitata l'attendibilità dei contenuti per la sessione di shell e la si vuole disabilitare per un singolo 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 .

Concedere autorizzazioni di firma delle immaginiGrant image signing permissions

Solo gli utenti o i sistemi a cui è stata concessa l'autorizzazione possono eseguire il push di immagini attendibili nel registro.Only the users or systems you've granted permission can push trusted images to your registry. Per concedere l'autorizzazione per il push di immagini attendibili a un utente (o a un sistema che usa un'entità servizio), concedere alle relative identità di Azure Active Directory il ruolo 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. Questo ruolo è in aggiunta al ruolo AcrPush (o equivalente) richiesto per il push delle immagini nel registro.This is in addition to the AcrPush (or equivalent) role required for pushing images to the registry. Per informazioni dettagliate, vedere Ruoli e autorizzazioni di Registro Azure Container.For details, see Azure Container Registry roles and permissions.

Nota

Non è possibile concedere l'autorizzazione push di un'immagine attendibile all' account amministratore di un registro contenitori di Azure.You can't grant trusted image push permission to the admin account of an Azure container registry.

I dettagli per la concessione del ruolo AcrImageSigner nel portale di Azure e nell'interfaccia della riga di comando di Azure sono illustrati di seguito.Details for granting the AcrImageSigner role in the Azure portal and the Azure CLI follow.

portale di AzureAzure portal

Passare al registro nel portale di Azure e quindi selezionare Controllo di accesso (IAM) > Aggiungi assegnazione di ruolo.Navigate to your registry in the Azure portal, then select Access control (IAM) > Add role assignment. In Aggiungi assegnazione di ruolo selezionare AcrImageSigner in Ruolo, quindi in Seleziona selezionare uno o più utenti o entità servizio e quindi fare clic su Salva.Under Add role assignment, select AcrImageSigner under Role, then Select one or more users or service principals, then Save.

In questo esempio sono state assegnate due entità al ruolo AcrImageSigner: un'entità servizio denominata "service-principal" e un utente denominato "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."

Abilitazione dell'attendibilità dei contenuti per un registro nel portale di Azure

Interfaccia della riga di comando di AzureAzure CLI

Per concedere le autorizzazioni di firma a un utente con l'interfaccia della riga di comando di Azure, assegnare il ruolo AcrImageSigner all'utente, impostando come ambito il registro.To grant signing permissions to a user with the Azure CLI, assign the AcrImageSigner role to the user, scoped to your registry. Il formato del comando è:The format of the command is:

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

Per concedere, ad esempio, il ruolo a se stessi, è possibile eseguire i comandi seguenti in una sessione dell'interfaccia della riga di comando di Azure autenticata.For example, to grant yourself the role, you can run the following commands in an authenticated Azure CLI session. Modificare il valore di REGISTRY in base al nome di Registro Azure Container.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

È anche possibile concedere a un'entità servizio i diritti per eseguire il push di immagini attendibili nel registro.You can also grant a service principal the rights to push trusted images to your registry. L'uso di un'entità servizio è utile per i sistemi di compilazione e altri sistemi automatici che devono eseguire il push di immagini attendibili nel registro.Using a service principal is useful for build systems and other unattended systems that need to push trusted images to your registry. Il formato è simile a quello per la concessione di un'autorizzazione utente, ma è necessario specificare un ID di entità servizio per il valore --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>

Il valore di <service principal ID> può corrispondere a appId o objectId dell'entità servizio oppure a uno dei relativi valori servicePrincipalNames.The <service principal ID> can be the service principal's appId, objectId, or one of its servicePrincipalNames. Per altre informazioni sull'uso di entità servizio e Registro Azure Container, vedere Autenticazione al Registro Azure Container con entità servizio.For more information about working with service principals and Azure Container Registry, see Azure Container Registry authentication with service principals.

Importante

Dopo eventuali modifiche ai ruoli, eseguire az acr login per aggiornare il token di identità locale per l'interfaccia della riga di comando di Azure per rendere effettivi i nuovi ruoli.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. Per informazioni sulla verifica dei ruoli per un'identità, vedere gestire l'accesso alle risorse di Azure con RBAC e l'interfaccia della riga di comando di Azure e risolvere i problemi di RBAC per le risorse di AzureFor information about verifying roles for an identity, see Manage access to Azure resources using RBAC and Azure CLI and Troubleshoot RBAC for Azure resources.

Eseguire il push di un'immagine attendibilePush a trusted image

Per eseguire il push di un tag di un'immagine attendibile nel registro contenitori, abilitare l'attendibilità dei contenuti ed eseguire il push dell'immagine con docker push.To push a trusted image tag to your container registry, enable content trust and push the image with docker push. La prima volta che si esegue il push di un tag firmato, viene chiesto di creare una passphrase sia per una chiave di firma radice che per una chiave di firma del repository.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. Entrambe le chiavi di firma, del repository e radice, vengono generate e archiviate in locale nel computer.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

Dopo la prima esecuzione di docker push con l'attendibilità dei contenuti abilitata, il client Docker usa la stessa chiave radice per i push successivi.After your first docker push with content trust enabled, the Docker client uses the same root key for subsequent pushes. Per ogni push successivo nello stesso repository, viene chiesta solo la chiave del repository.On each subsequent push to the same repository, you're asked only for the repository key. Ogni volta che si esegue il push di un'immagine attendibile in un nuovo repository, viene chiesto di fornire una passphrase per una nuova chiave del repository.Each time you push a trusted image to a new repository, you're asked to supply a passphrase for a new repository key.

Eseguire il pull di un'immagine attendibilePull a trusted image

Per eseguire il pull di un'immagine attendibile, abilitare l'attendibilità dei contenuti ed eseguire normalmente il comando docker pull.To pull a trusted image, enable content trust and run the docker pull command as normal. Per eseguire il pull delle immagini attendibili, il ruolo AcrPull è sufficiente per i normali utenti.To pull trusted images, the AcrPull role is enough for normal users. Non sono necessari ruoli aggiuntivi, ad esempio un ruolo AcrImageSigner.No additional roles like an AcrImageSigner role are required. I consumer per cui è abilitata l'attendibilità dei contenuti possono eseguire il pull solo di immagini con tag firmati.Consumers with content trust enabled can pull only images with signed tags. Ecco un esempio di pull di un tag firmato: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 un client per cui è abilitata l'attendibilità dei contenuti cerca di eseguire il pull di un tag non firmato, l'operazione ha esito negativo: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

Dietro le quinteBehind the scenes

Quando si esegue docker pull, il client Docker usa la stessa libreria dell'interfaccia della riga di comando Notary per richiedere il mapping del digest da tag a SHA-256 per il tag di cui si esegue il 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. Dopo aver verificato le firme nei dati attendibili, il client comunica al motore Docker di eseguire un "pull in base al digest".After validating the signatures on the trust data, the client instructs Docker Engine to do a "pull by digest." Durante il pull, il motore usa il checksum SHA-256 come indirizzo dei contenuti per richiedere e convalidare il manifesto dell'immagine da Registro Azure Container.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.

Gestione della chiaveKey management

Come indicato nell'output di docker push quando si esegue il push della prima immagine attendibile, la chiave radice è la più sensibile.As stated in the docker push output when you push your first trusted image, the root key is the most sensitive. Assicurarsi di eseguire il backup della chiave radice e di archiviarla in una posizione sicura.Be sure to back up your root key and store it in a secure location. Per impostazione predefinita, il client Docker archivia le chiavi di firma nella directory seguente:By default, the Docker client stores signing keys in the following directory:

~/.docker/trust/private

Eseguire il backup delle chiavi radice e del repository comprimendole in un archivio e archiviandole in una posizione sicura.Back up your root and repository keys by compressing them in an archive and storing it in a secure location. Ad esempio, in Bash:For example, in Bash:

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

Insieme alle chiavi radice e del repository generate in locale ne vengono generate e archiviate anche altre da Registro Azure Container quando si esegue il push di un'immagine attendibile.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. Per informazioni dettagliate sulle diverse chiavi nell'implementazione dell'attendibilità dei contenuti di Docker, incluse indicazioni aggiuntive sulla gestione, vedere Gestire le chiavi per l'attendibilità dei contenuti nella documentazione di 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.

Chiave radice persaLost root key

Se si perde l'accesso alla chiave radice, si perde l'accesso ai tag firmati in tutti i repository in cui i tag sono stati firmati con tale chiave.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. Registro Azure Container non è in grado di ripristinare l'accesso ai tag delle immagini firmati con una chiave radice persa.Azure Container Registry cannot restore access to image tags signed with a lost root key. Per rimuovere tutti i dati di attendibilità (firme) per il registro, disabilitare e quindi abilitare di nuovo l'attendibilità dei contenuti per il registro.To remove all trust data (signatures) for your registry, first disable, then re-enable content trust for the registry.

Avviso

Disabilitando e quindi abilitando di nuovo l'attendibilità dei contenuti nel registro vengono eliminati tutti i dati di attendibilità per tutti i tag firmati in ogni repository nel registro.Disabling and re-enabling content trust in your registry deletes all trust data for all signed tags in every repository in your registry. Questa azione è irreversibile e Registro Azure Container non può ripristinare i dati di attendibilità eliminati.This action is irreversible--Azure Container Registry cannot recover deleted trust data. La disabilitazione dell'attendibilità dei contenuti non elimina le immagini stesse.Disabling content trust does not delete the images themselves.

Per disabilitare l'attendibilità dei contenuti per il registro, passare al registro nel portale di Azure.To disable content trust for your registry, navigate to the registry in the Azure portal. In Criteri selezionare Attendibilità contenuto > Disabilitata > Salva.Under Policies, select Content Trust > Disabled > Save. Verrà visualizzato un avviso relativo alla perdita di tutte le firme nel registro.You're warned of the loss of all signatures in the registry. Selezionare OK per eliminare in modo permanente tutte le firme nel registro.Select OK to permanently delete all signatures in your registry.

Disabilitazione dell'attendibilità dei contenuti per un registro nel portale di Azure

Passaggi successiviNext steps

  • Per altre informazioni sull'attendibilità del contenuto, vedere Attendibilità dei contenuti in Docker.See Content trust in Docker for additional information about content trust. Sebbene in questo articolo siano stati illustrati diversi punti importanti, l'attendibilità dei contenuti è un argomento vasto e viene descritta in modo più dettagliato nella documentazione di 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.

  • Per un esempio relativo all'uso dell'attendibilità dei contenuti quando si compila e si esegue il push di un'immagine Docker, vedere la documentazione di Azure Pipelines.See the Azure Pipelines documentation for an example of using content trust when you build and push a Docker image.