Delen via

Inhoud vertrouwen in Azure Container Registry

Azure Container Registry implementeert Docker's vertrouwensmodel voor inhoud, waardoor gesigneerde images kan worden gepusht en opgehaald. In dit artikel wordt uitgelegd hoe u inhoudsvertrouwen inschakelt in uw containerregisters.

Belangrijk

Docker Content Trust wordt afgeschaft en volledig verwijderd op 31 maart 2028. Raadpleeg Overgang van Docker Content Trust naar het Notary Project voor details en transitiebegeleiding.

Notitie

Inhoudsvertrouwen is een functie van de Premium-servicelaag van Azure Container Registry.

Beperkingen

  • Token met opslagplaats-specifieke machtigingen ondersteunt momenteel geen docker push en pull van ondertekende afbeeldingen.

Hoe inhoud vertrouwen werkt

Het is belangrijk voor de beveiliging van een gedistribueerd systeem dat zowel de bron als de integriteit van de gegevensinvoer in het systeem kan worden gecontroleerd. Consumenten van de gegevens moeten de uitgever (bron) van de gegevens kunnen verifiëren en kunnen nagaan of de gegevens niet zijn gewijzigd nadat ze zijn gepubliceerd (integriteit).

Als uitgever van images kunt u Content Trust gebruiken voor het ondertekenen van de images die u naar uw register uploadt. Consumenten van uw installatiekopieën (personen of systemen die installatiekopieën ophalen uit het register) kunnen hun clients zo configureren dat alleen ondertekenende installatiekopieën worden opgehaald. Wanneer een gebruiker een ondertekende afbeelding downloadt, controleert hun Docker-client de integriteit van de afbeelding. Zo weten consumenten zeker dat de ondertekende afbeeldingen in uw register inderdaad door u zijn gepubliceerd en dat ze sindsdien niet zijn gewijzigd.

Notitie

Azure Container Registry (ACR) biedt geen ondersteuning acr import voor het importeren van installatiekopieën die zijn ondertekend met Docker Content Trust (DCT). De handtekeningen zijn standaard niet zichtbaar na het importeren en de notaris v2 slaat deze handtekeningen op als artefacten.

Vertrouwde afbeeldingen

Vertrouwen in inhoud werkt samen met de tags in een repository. Afbeeldingsopslagplaatsen kunnen zowel afbeeldingen met ondertekende als niet-ondertekende tags bevatten. Mogelijk ondertekent u bijvoorbeeld alleen de afbeeldingen myimage:stable en myimage:latest, maar niet myimage:dev.

Ondertekeningssleutels

Inhoud vertrouwen wordt beheerd met behulp van cryptografische ondertekeningssleutels. Deze sleutels zijn gekoppeld aan een specifieke opslagplaats in een register. Er zijn verschillende soorten ondertekeningssleutels die door Docker-clients en het register worden gebruikt bij het beheren van vertrouwensrelaties voor de tags in een opslagplaats. Wanneer u vertrouwen in de inhoud inschakelt en integreert in de publicatie- en consumptiepijplijn van uw container, moet u deze sleutels zorgvuldig beheren. Zie voor meer informatie Sleutelbeheer verderop in dit artikel en Manage keys for content trust (sleutels voor inhoud vertrouwen beheren) in de documentatie voor Docker.

Aanbeveling

Dit is een zeer algemeen overzicht van het inhoud vertrouwen-model van Docker. Zie Content trust in Docker (inhoud vertrouwen in Docker) voor een uitgebreide beschrijving van inhoud vertrouwen.

Inhoudsvertrouwen voor register inschakelen

Uw eerste stap is het inschakelen van inhoud vertrouwen op het niveau van het register. Na het inschakelen kunnen clients (gebruikers of services) ondertekende installatiekopieën pushen naar uw register. Als u inhoud vertrouwen voor uw register inschakelt, wordt het gebruik van het register niet beperkt tot consumenten waarvoor inhoud vertrouwen is ingeschakeld. Ook gebruikers waarvoor inhoud vertrouwen niet is ingeschakeld, kunnen uw register gewoon blijven gebruiken. Consumenten die content trust in hun clients hebben ingeschakeld, kunnen echter alleen ondertekende bestanden in uw register zien.

Als u inhoud vertrouwen voor uw register wilt inschakelen, navigeert u eerst naar het register in Azure Portal. Onder Beleid, selecteer Inhoud vertrouwen>Ingeschakeld>Opslaan. U kunt ook de opdracht az acr config content-trust update gebruiken in de Azure CLI.

Schermopname van het inschakelen van inhoudsvertrouwen voor een register in Azure Portal.

Inhoud vertrouwen voor clients inschakelen

Als u wilt werken met vertrouwde installatiekopieën, moeten zowel uitgevers als consumenten van installatiekopieën inhoud vertrouwen voor de Docker-clients inschakelen. Als uitgever kunt u de images die u naar een register pusht waar inhoudsvertrouwen is ingeschakeld, ondertekenen. Wanneer u als consument inhoudvertrouwen inschakelt, ziet u in registers alleen nog ondertekende afbeeldingen. Inhoud vertrouwen is standaard uitgeschakeld voor Docker-clients, maar u kunt dit per shellsessie of opdracht inschakelen.

Als u inhoud vertrouwen voor een shellsessie wilt inschakelen, stelt u de omgevingsvariabele DOCKER_CONTENT_TRUST in op 1. Voorbeeld in de Bash-shell:

# Enable content trust for shell session
export DOCKER_CONTENT_TRUST=1

Als u in plaats daarvan inhoud vertrouwen voor een enkele opdracht wilt inschakelen of uitschakelen, kunt u verschillende Docker-opdrachten gebruiken die het argument --disable-content-trust ondersteunen. Inhoud vertrouwen inschakelen voor één opdracht:

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

Als u inhoud vertrouwen voor uw shellsessie hebt ingeschakeld en het wilt uitschakelen voor één opdracht, doet u het volgende:

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

Verleen machtigingen voor het ondertekenen van afbeeldingen

Alleen de gebruikers of systemen waaraan u toegang hebt gegeven, kunnen vertrouwde afbeeldingen naar uw register pushen. Als u pushmachtigingen voor vertrouwde afbeeldingen wilt verlenen aan een gebruiker (of een systeem via een service-principal), verleent u hun Microsoft Entra-identiteiten de AcrImageSigner rol. Dit is een aanvulling op de AcrPush (of equivalente) rol die nodig is voor het pushen van afbeeldingen naar het register. Zie het overzicht van Azure Container Registry Entra-machtigingen en -rollen voor meer informatie.

Belangrijk

U kunt geen rechten voor vertrouwde afbeeldingen verlenen aan de volgende beheerdersaccounts:

Notitie

Vanaf juli 2021 bevat de AcrImageSigner rol zowel de Microsoft.ContainerRegistry/registries/sign/write actie als de Microsoft.ContainerRegistry/registries/trustedCollections/write gegevensactie.

Detailinformatie over het verlenen van de rol AcrImageSigner in Azure Portal en de Azure-opdrachtregelinterface volgt later.

Azure Portal

  1. Klik op Toegangsbeheer (IAM) .

  2. Selecteer Toevoegen>Roltoewijzing toevoegen om het deelvenster Roltoewijzing toevoegen te openen.

  3. Wijs de volgende rol toe. In dit voorbeeld wordt de rol toegewezen aan een afzonderlijke gebruiker. Raadpleeg Azure-rollen toewijzen met Azure Portal voor informatie over het toewijzen van rollen.

    Instelling Waarde
    Rol AcrImageSigner
    Toegang toewijzen aan Gebruiker
    Leden Alain

    Pagina Roltoewijzing toevoegen in Azure Portal.

Azure-CLI

Als u een gebruiker machtigingen voor ondertekenen wilt verlenen met de Azure CLI, wijst u de rol AcrImageSigner aan de gebruiker binnen uw register. De indeling van de opdracht is als volgt:

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

Als u bijvoorbeeld een gebruiker zonder beheerdersrechten de rol wilt verlenen, kunt u de volgende opdrachten uitvoeren in een geverifieerde Azure CLI-sessie. Wijzig de waarde REGISTRY in de naam van uw Azure-containerregister.

# 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

U kunt ook een service-principal de rechten geven om vertrouwde afbeeldingen naar uw register te pushen. Het gebruik van een service-principal is handig voor buildsystemen en andere onbemande systemen die vertrouwde images naar uw register moeten pushen. De indeling is vergelijkbaar met het verlenen van gebruikersmachtigingen, maar in dit geval moet u de waarde --assignee wijzigen in de id van een service-principal.

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

De <service principal ID> kan de appId, objectId of een van de bijbehorende servicePrincipalNames van de service-principal zijn. Zie Azure Container Registry authentication with service principals (Azure Container Registry-verificatie met service-principals) voor meer informatie over het werken met service-principals en Azure Container Registry.

Belangrijk

Nadat een rol is gewijzigd, voert u de opdracht uit az acr login om het lokale identiteitstoken voor de Azure CLI te vernieuwen, zodat de nieuwe rollen van kracht kunnen worden. Zie Azure-roltoewijzingen toevoegen of verwijderen met behulp van Azure CLI en problemen met Azure RBAC oplossen voor informatie over het verifiëren van rollen voor een identiteit.

Een vertrouwde image pushen

Als u een tag voor een vertrouwde installatiekopie naar uw containerregister wilt pushen, schakelt u inhoud vertrouwen in en pusht u de installatiekopie naar uw register met docker push. Nadat het pushen met een ondertekende tag de eerste keer is voltooid, wordt u gevraagd om een wachtwoordzin te maken voor zowel een basisondertekeningssleutel als een ondertekeningssleutel voor de opslagplaats. Beide sleutels worden gegenereerd en lokaal opgeslagen op uw computer.

$ 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

Na uw eerste docker push waarbij inhoudsvertrouwen is ingeschakeld, wordt voor verdere pushes op de Docker-client dezelfde hoofdsleutel gebruikt. Bij elke volgende push naar dezelfde opslagplaats hoeft u alleen de sleutel voor de opslagplaats op te geven. Telkens wanneer u een vertrouwde image naar een nieuw repository pusht, wordt u gevraagd een passphrase op te geven voor een nieuwe repository-sleutel.

Een vertrouwde afbeelding ophalen

Als u een vertrouwde afbeelding wilt ophalen, schakelt u contentvertrouwen in en voert u de opdracht docker pull zoals gebruikelijk uit. Voor het ophalen van vertrouwde images is de AcrPull rol voldoende voor normale gebruikers. Er zijn geen extra rollen nodig, zoals een AcrImageSigner rol. Consumenten met ingeschakeld inhoudsvertrouwen kunnen alleen afbeeldingen met ondertekende tags ophalen. Voorbeeld van het ophalen van een ondertekende 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

Als een client met ingeschakelde inhoudsvertrouwen probeert een niet-ondertekende tag op te halen, mislukt de bewerking met een fout die vergelijkbaar is met de volgende:

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

Achter de schermen

Wanneer u docker pull uitvoert, gebruikt de Docker-client dezelfde bibliotheek als in de Notary CLI om de tag-to-SHA-256-digest-toewijzing aan te vragen voor de tag die u ophaalt. Na het valideren van de handtekeningen op de vertrouwensdata geeft de client Docker Engine opdracht om een 'pull by digest' uit te voeren. Tijdens de pull gebruikt de Engine de SHA-256-controlesom als contentadres om het imagemanifest van het Azure-containerregister aan te vragen en te valideren.

Notitie

Azure Container Registry biedt geen officiële ondersteuning voor de Notary CLI, maar is compatibel met de Notary Server-API, die is opgenomen in Docker Desktop. Momenteel wordt Notary versie 0.6.0 aanbevolen.

Sleutelbeheer

Zoals vermeld in de docker push uitvoer wanneer u uw eerste vertrouwde image pusht, is de hoofdsleutel het meest gevoelig. Maak een back-up van uw hoofdsleutel en bewaar deze op een veilige locatie. Standaard worden ondertekeningssleutels opgeslagen in de volgende map van de Docker-client:

~/.docker/trust/private

Maak een back-up van uw hoofd- en opslagplaatssleutels door ze te comprimeren in een archief en op een veilige locatie op te slaan. Bijvoorbeeld, in Bash:

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

Naast de lokaal gegenereerde hoofd- en opslagplaats-sleutels worden er, wanneer u een vertrouwde installatiekopie pusht, nog enkele andere sleutels door Azure Container Registry gegenereerd en opgeslagen. Zie Manage keys for content trust (sleutels voor inhoud vertrouwen beheren) in de documentatie voor Docker voor een uitgebreide beschrijving van de verschillende sleutels in de implementatie van inhoud vertrouwen van Docker, inclusief aanvullende richtlijnen voor het beheer.

Verloren hoofdsleutel

Als de hoofdsleutel verloren gaat, hebt u geen toegang meer tot de ondertekende tags in alle opslagplaatsen waarvan de tags zijn ondertekend met die sleutel. Azure Container Registry kan de toegang tot afbeeldingstags die zijn ondertekend met een verloren hoofdsleutel niet herstellen. Om alle vertrouwensgegevens (handtekeningen) voor het register te verwijderen, schakelt u eerst inhoudsverificatie voor het register uit en vervolgens weer in.

Waarschuwing

Door het vertrouwen op inhoud in uw register uit te schakelen en weer in te schakelen, worden alle vertrouwensgegevens voor alle ondertekende tags van elke opslagplaats in uw register verwijderd. Deze actie kan niet ongedaan worden gemaakt. Gegevens van vertrouwensrelaties kunnen nooit worden hersteld in Azure Container Registry. Bij het uitschakelen van content trust worden de afbeeldingen zelf niet verwijderd.

Als u inhoud vertrouwen voor uw register wilt uitschakelen, navigeert u naar het register in Azure Portal. Onder Beleid, selecteer Inhoudsvertrouwen>Uitgeschakeld>Opslaan. U wordt gewaarschuwd dat hierdoor alle handtekeningen in het register verloren gaan. Selecteer OK om alle handtekeningen in het register permanent te verwijderen.

Inhoudsvertrouwen voor een register uitschakelen in de Azure-portal

Volgende stappen