Approbation de contenu dans Azure Container RegistryContent trust in Azure Container Registry

Azure Container Registry implémente le modèle d’approbation de contenu de Docker, lequel permet l’envoi (push) et le tirage (pull) d’images signées.Azure Container Registry implements Docker's content trust model, enabling pushing and pulling of signed images. Cet article vous permet de bien démarrer avec l’activation de l’approbation de contenu dans vos registres de conteneur.This article gets you started enabling content trust in your container registries.

Notes

L’approbation de contenu est une fonctionnalité de la référence SKU Premium d’Azure Container Registry.Content trust is a feature of the Premium SKU of Azure Container Registry.

Fonctionnement de l’approbation de contenuHow content trust works

Pour tout système distribué dont la conception est axée sur la sécurité, il est important de vérifier à la fois la source et l’intégrité des données qui pénètrent dans le système.Important to any distributed system designed with security in mind is verifying both the source and the integrity of data entering the system. Les consommateurs des données doivent être en mesure de vérifier l’éditeur (source) des données, et de s’assurer que ces données n’ont pas été modifiées après leur publication (intégrité).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).

En votre qualité d’éditeur d’images, l’approbation de contenu vous permet de signer les images que vous envoyez à votre registre par une transmission de type push.As an image publisher, content trust allows you to sign the images you push to your registry. Les consommateurs de vos images (personnes ou systèmes qui extraient des images de votre registre) peuvent configurer leurs clients pour qu’ils extraient (pull) uniquement des images signées.Consumers of your images (people or systems pulling images from your registry) can configure their clients to pull only signed images. Lorsqu’un consommateur d’images extrait une image signée, son client Docker vérifie l’intégrité de cette image.When an image consumer pulls a signed image, their Docker client verifies the integrity of the image. Ce modèle offre aux consommateurs l’assurance que les images signées dans votre registre ont été effectivement publiées par vos soins, et qu’elles n’ont pas été modifiées depuis leur publication.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.

Images approuvéesTrusted images

L’approbation de contenu fonctionne avec les balises d’un référentiel.Content trust works with the tags in a repository. Les référentiels d’images peuvent contenir des images présentant des balises aussi bien signées que non signées.Image repositories can contain images with both signed and unsigned tags. Par exemple, vous pouvez choisir de signer uniquement les images myimage:stable et myimage:latest, et non les images myimage:dev.For example, you might sign only the myimage:stable and myimage:latest images, but not myimage:dev.

Clés de signatureSigning keys

L’approbation de contenu est gérée par le biais d’un ensemble de clés de signatures de chiffrement.Content trust is managed through the use of a set of cryptographic signing keys. Ces clés sont associées à un référentiel spécifique dans un registre.These keys are associated with a specific repository in a registry. Les clients Docker et votre registre utilisent plusieurs types de clés de signature dans le cadre de la gestion de l’approbation relative aux balises d’un référentiel.There are several types of signing keys that Docker clients and your registry use in managing trust for the tags in a repository. Lorsque vous activez l’approbation de contenu et que vous l’intégrez à votre pipeline de publication et de consommation de conteneurs, vous devez gérer ces clés avec soin.When you enable content trust and integrate it into your container publishing and consumption pipeline, you must manage these keys carefully. Pour plus d’informations, consultez la section Gestion des clés dans la suite de cet article, ainsi que l’article Manage keys for content trust (Gérer les clés de l’approbation de contenu) dans la documentation Docker.For more information, see Key management later in this article and Manage keys for content trust in the Docker documentation.

Conseil

Il s’agissait là d’une vue d’ensemble très générale du modèle d’approbation de contenu de Docker.This was a very high-level overview of Docker's content trust model. Pour découvrir une présentation détaillée de l’approbation de contenu, consultez l’article Content trust in Docker (Approbation de contenu dans Docker).For an in-depth discussion of content trust, see Content trust in Docker.

Activer l’approbation de contenu sur le registreEnable registry content trust

La première étape consiste à activer l’approbation de contenu au niveau du registre.Your first step is to enable content trust at the registry level. Une fois que vous activez l’approbation de contenu, les clients (utilisateurs ou services) peuvent envoyer des images signées à votre registre.Once you enable content trust, clients (users or services) can push signed images to your registry. L’activation de l’approbation de contenu sur votre registre ne limite pas l’utilisation du registre uniquement aux consommateurs ayant activé l’approbation de contenu.Enabling content trust on your registry does not restrict registry usage only to consumers with content trust enabled. Les consommateurs pour lesquels l’approbation de contenu est désactivée peuvent continuer à utiliser votre registre normalement.Consumers without content trust enabled can continue to use your registry as normal. Toutefois, les consommateurs qui ont activé l’approbation de contenu dans leurs clients seront uniquement en mesure de visualiser les images signées dans votre registre.Consumers who have enabled content trust in their clients, however, will be able to see only signed images in your registry.

Pour activer l’approbation de contenu pour votre registre, commencez par accéder au registre dans le Portail Azure.To enable content trust for your registry, first navigate to the registry in the Azure portal. Sous Stratégies, sélectionnez Approbation de contenu > Activé > Enregistrer.Under Policies, select Content Trust > Enabled > Save.

Activation de l’approbation de contenu pour un registre dans le Portail Azure

Activer l’approbation de contenu dans les clientsEnable client content trust

Pour utiliser les images approuvées, les éditeurs et les consommateurs d’images doivent tous activer l’approbation de contenu pour leurs clients Docker.To work with trusted images, both image publishers and consumers need to enable content trust for their Docker clients. Si vous êtes un éditeur, vous pouvez signer les images que vous envoyez à un registre sur lequel l’activation de contenu est activée.As a publisher, you can sign the images you push to a content trust-enabled registry. Si vous êtes un consommateur et que vous avez activé l’approbation de contenu, vous ne verrez que les images signées d’un registre.As a consumer, enabling content trust limits your view of a registry to signed images only. L’approbation de contenu est désactivée par défaut dans les clients Docker, mais vous pouvez l’activer par session d’interpréteur de commandes ou par commande.Content trust is disabled by default in Docker clients, but you can enable it per shell session or per command.

Pour activer l’approbation de contenu pour une session d’interpréteur de commandes, définissez la variable d’environnement DOCKER_CONTENT_TRUST sur 1.To enable content trust for a shell session, set the DOCKER_CONTENT_TRUST environment variable to 1. Par exemple, dans l’interpréteur de commandes Bash :For example, in the Bash shell:

# Enable content trust for shell session
export DOCKER_CONTENT_TRUST=1

Si vous préférez activer ou désactiver l’approbation de contenu pour une commande spécifique, plusieurs commandes Docker prennent en charge l’argument --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. Pour activer l’approbation de contenu pour une seule commande :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 .

Si vous avez activé l’approbation de contenu pour votre session d’interpréteur de commandes et que vous souhaitez la désactiver pour une commande spécifique :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 .

Accorder des autorisations de signature d’imageGrant image signing permissions

Seuls les utilisateurs ou les systèmes qui disposent des autorisations requises peuvent envoyer des images approuvées à votre registre.Only the users or systems you've granted permission can push trusted images to your registry. Pour accorder l’autorisation d’envoi d’images approuvées à un utilisateur (ou à un système à l’aide d’un principal de service), octroyez à leurs identités Azure Active Directory le rôle 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. Ce rôle vient s’ajouter au rôle AcrPush (ou équivalent) requis pour l’envoi (push) d’images au registre.This is in addition to the AcrPush (or equivalent) role required for pushing images to the registry. Pour plus d’informations, consultez Autorisations et rôles Azure Container Registry.For details, see Azure Container Registry roles and permissions.

Les procédures détaillées d’octroi du rôle AcrImageSigner dans le Portail Azure et dans l’interface de ligne de commande Azure (Azure CLI) sont décrites ci-après.Details for granting the AcrImageSigner role in the Azure portal and the Azure CLI follow.

Portail AzureAzure portal

Accédez à votre registre dans le portail Azure, puis sélectionnez Contrôle d’accès (IAM) > Ajouter une attribution de rôle.Navigate to your registry in the Azure portal, then select Access control (IAM) > Add role assignment. Sous Ajouter une attribution de rôle, sélectionnez AcrImageSigner sous Rôle, sélectionnez un ou plusieurs utilisateurs ou principaux de service dans le champ Sélectionner, puis cliquez sur Enregistrer.Under Add role assignment, select AcrImageSigner under Role, then Select one or more users or service principals, then Save.

Dans cet exemple, le rôle AcrImageSigner a été assigné à deux entités : un principal de service nommé « service-principal » et un utilisateur nommé « 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."

Activation de l’approbation de contenu pour un registre dans le Portail Azure

Azure CLIAzure CLI

Pour accorder des autorisations de signature à un utilisateur à l’aide d’Azure CLI, assignez à cet utilisateur le rôle AcrImageSigner, limité à votre registre.To grant signing permissions to a user with the Azure CLI, assign the AcrImageSigner role to the user, scoped to your registry. Le format de la commande est le suivant :The format of the command is:

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

Par exemple, pour vous octroyer ce rôle, vous pouvez exécuter les commandes ci-après dans une session Azure CLI authentifiée.For example, to grant yourself the role, you can run the following commands in an authenticated Azure CLI session. Modifiez la valeur REGISTRY pour qu’elle reflète le nom de votre registre de conteneurs 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

Vous pouvez également octroyer à un principal de service les droits d’envoyer des images approuvées à votre registre.You can also grant a service principal the rights to push trusted images to your registry. L’utilisation d’un principal de service est utile pour les systèmes de génération et pour d’autres systèmes sans assistance qui doivent envoyer des images approuvées à votre registre.Using a service principal is useful for build systems and other unattended systems that need to push trusted images to your registry. Le format de la commande ci-après est semblable à celui de l’octroi d’une autorisation utilisateur, mais vous devez spécifier un ID de principal de service pour la valeur --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>

La variable <service principal ID> peut correspondre à l’élément appId ou objectId du principal de service, ou à l’un de ses éléments servicePrincipalNames.The <service principal ID> can be the service principal's appId, objectId, or one of its servicePrincipalNames. Pour plus d’informations sur l’utilisation des principaux de service et d’Azure Container Registry, consultez l’article Authentification Azure Container Registry avec des principaux de service.For more information about working with service principals and Azure Container Registry, see Azure Container Registry authentication with service principals.

Après toute modification de rôle, exécutez az acr login pour actualiser le jeton d’identité local pour Azure CLI afin que les nouveaux rôles puissent entrer en vigueur.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.

Envoyer une image approuvéePush a trusted image

Pour envoyer une balise d’image approuvée à votre registre de conteneurs, activez l’approbation de contenu, puis envoyez l’image avec docker push.To push a trusted image tag to your container registry, enable content trust and push the image with docker push. La première fois que vous envoyez une balise signée, vous êtes invité à créer une phrase secrète à la fois pour une clé de signature racine et pour une clé de signature de référentiel.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. La clé racine et la clé de référentiel sont générées et stockées localement sur votre machine.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

Après l’exécution de votre première commande docker push avec l’approbation de contenu activée, le client Docker utilise la même clé racine pour les envois suivants.After your first docker push with content trust enabled, the Docker client uses the same root key for subsequent pushes. Pour chaque envoi ultérieur au même référentiel, vous êtes uniquement invité à fournir la clé de référentiel.On each subsequent push to the same repository, you're asked only for the repository key. Chaque fois que vous envoyez une image approuvée à un nouveau référentiel, vous devez fournir une phrase secrète pour une nouvelle clé de référentiel.Each time you push a trusted image to a new repository, you're asked to supply a passphrase for a new repository key.

Extraire une image approuvéePull a trusted image

Pour extraire une image approuvée, activez l’approbation de contenu et exécutez la commande docker pull normalement.To pull a trusted image, enable content trust and run the docker pull command as normal. Pour tirer (pull) des images approuvées, le rôle AcrPull suffit pour les utilisateurs normaux.To pull trusted images, the AcrPull role is enough for normal users. Aucun rôle supplémentaire comme le rôle AcrImageSigner n’est nécessaire.No additional roles like an AcrImageSigner role are required. Les consommateurs ayant activé l’approbation de contenu peuvent uniquement extraire les images dotées de balises signées.Consumers with content trust enabled can pull only images with signed tags. Voici un exemple d’extraction de balise signée :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

Si un client ayant activé l’approbation de contenu tente d’extraire une balise non signée, l’opération échouera :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

Dans les coulissesBehind the scenes

Lorsque vous exécutez la commande docker pull, le client Docker utilise la même bibliothèque que dans l’interface de ligne de commande Notary pour demander le mappage sur SHA-256 du code de hachage de la balise que vous extrayez.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. Après la validation des signatures sur les données d’approbation, le client demande au moteur Docker d’effectuer une « extraction par code de hachage ».After validating the signatures on the trust data, the client instructs Docker Engine to do a "pull by digest." Pendant l’extraction, le moteur utilise la somme de contrôle SHA-256 comme adresse du contenu pour demander et valider le manifeste d’image à partir du registre de conteneurs 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.

Gestion des clésKey management

Comme indiqué pour la sortie docker push lorsque vous envoyez votre première image approuvée, la clé racine constitue l’information la plus sensible.As stated in the docker push output when you push your first trusted image, the root key is the most sensitive. Veillez à sauvegarder votre clé racine et à la stocker en lieu sûr.Be sure to back up your root key and store it in a secure location. Par défaut, le client Docker stocke les clés de signature dans le répertoire suivant :By default, the Docker client stores signing keys in the following directory:

~/.docker/trust/private

Sauvegardez vos clés racine et de référentiel en les compressant dans une archive et en les stockant à un endroit sécurisé hors connexion (tel qu’un dispositif de stockage USB).Back up your root and repository keys by compressing them in an archive and storing it securely offline (such as on a USB storage device). Par exemple, dans Bash :For example, in Bash:

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

Parallèlement aux clés racine et de référentiel générées localement, plusieurs autres clés sont générées et stockées par Azure Container Registry lorsque vous envoyez une image approuvée.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. Pour découvrir une présentation détaillée des différentes clés dans l’implémentation de l’approbation de contenu de Docker, et notamment des instructions de gestion supplémentaires, consultez l’article Manage keys for content trust (Gérer les clés de l’approbation de contenu) dans la documentation 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.

Clé racine perdueLost root key

Si vous perdez l’accès à votre clé racine, vous perdez l’accès aux balises signées dans tous les référentiels dont les balises ont été signées avec cette clé.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 ne peut pas restaurer l’accès aux balises d’image qui ont été signées avec une clé racine perdue.Azure Container Registry cannot restore access to image tags signed with a lost root key. Pour supprimer toutes les données d’approbation (signatures) de votre registre, commencez par désactiver l’approbation de contenu pour le registre, puis réactivez-la.To remove all trust data (signatures) for your registry, first disable, then re-enable content trust for the registry.

Avertissement

La désactivation et la réactivation de l’approbation de contenu dans votre registre suppriment toutes les données d’approbation pour toutes les balises signées dans chaque référentiel de votre registre.Disabling and re-enabling content trust in your registry deletes all trust data for all signed tags in every repository in your registry. Cette opération est irréversible : Azure Container Registry ne peut pas récupérer les données d’approbation supprimées.This action is irreversible--Azure Container Registry cannot recover deleted trust data. La désactivation de l’approbation de contenu ne supprime pas les images proprement dites.Disabling content trust does not delete the images themselves.

Pour désactiver l’approbation de contenu pour votre registre, accédez au registre dans le Portail Azure.To disable content trust for your registry, navigate to the registry in the Azure portal. Sous Stratégies, sélectionnez Approbation de contenu > Désactivé > Enregistrer.Under Policies, select Content Trust > Disabled > Save. Un message vous signale la perte de toutes les signatures dans le registre.You're warned of the loss of all signatures in the registry. Sélectionnez OK pour supprimer définitivement toutes les signatures dans votre registre.Select OK to permanently delete all signatures in your registry.

Désactivation de l’approbation de contenu pour un registre dans le Portail Azure

Étapes suivantesNext steps

Pour plus d’informations sur l’approbation de contenu, consultez Approbation de contenu dans Docker.See Content trust in Docker for additional information about content trust. Bien que cet article ait abordé plusieurs points clés, l’approbation de contenu est un vaste sujet couvert de manière plus approfondie dans la documentation 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.