Confianza en el contenido en Azure Container Registry

Artículo
10/31/2023

Azure Container Registry implementa el modelo de confianza del contenido de Docker, lo que permite insertar y extraer las imágenes firmadas. Este artículo le permite comenzar a habilitar la confianza del contenido en los registros del contenedor.

Nota

La confianza de contenido es una característica del nivel de servicio Premium de Azure Container Registry.

Limitaciones

El token con los permisos de repositorio actualmente no admite docker push y la extracción de imágenes firmadas.

Cómo funciona la confianza en el contenido

En cualquier sistema distribuido diseñado teniendo en cuenta la seguridad es importante comprobar tanto el origen como la integridad de los datos que entran en el sistema. Los consumidores de los datos deben ser capaces tanto de comprobar el publicador (origen) de los datos, así como de asegurarse de que no se han modificado después de ser publicados (integridad).

Como publicador de imágenes, la confianza en el contenido le permite firmar las imágenes que inserta en el registro. Los consumidores de las imágenes (personas o sistemas que extraen imágenes del registro) pueden configurar sus clientes para extraer solo imágenes firmadas. Cuando un consumidor de imágenes extrae una imagen firmada, su cliente de Docker comprueba la integridad de la imagen. En este modelo, los consumidores se aseguran de que las imágenes firmadas del registro fueron publicadas por usted y no se han modificado desde su publicación.

Nota:

Azure Container Registry (ACR) no admite acr import la importación de imágenes firmadas con Docker Content Trust (DCT). Por diseño, las firmas no son visibles después de la importación, y el notario v2 almacena estas firmas como artefactos.

Imágenes de confianza

La confianza en el contenido funciona con las etiquetas de un repositorio. Los repositorios de imágenes pueden contener imágenes con etiquetas firmadas y sin firmar. Por ejemplo, podría firmar únicamente las imágenes myimage:stable y myimage:latest, pero no myimage:dev.

Claves de firma

La confianza en el contenido se administra mediante el uso de un conjunto de claves de firma criptográficas. Estas claves están asociadas a un repositorio específico de un registro. Los clientes de Docker y el registro utilizan varios tipos de claves de firma en la administración de la confianza para las etiquetas de un repositorio. Debe administrar cuidadosamente estas claves al habilitar la confianza en el contenido e integrarla en la canalización de publicación y consumo del contenedor. Para más información, consulte Administración de claves más adelante en este artículo y Administración de claves para la confianza en el contenido en la documentación de Docker.

Sugerencia

Esta ha sido una introducción muy general al modelo de confianza en el contenido de Docker. Para una explicación detallada de la confianza en el contenido, consulte Confianza en el contenido en Docker.

Habilitación de la confianza en el contenido del registro

El primer paso es habilitar la confianza en el contenido en el nivel de registro. Una vez que habilite la confianza en el contenido, los clientes (usuarios o servicios) pueden insertar imágenes firmadas en el registro. Habilitar la confianza en el contenido en el registro no restringe el uso del registro solo a los consumidores con la confianza en el contenido habilitada. Los consumidores sin la confianza en el contenido habilitada pueden seguir usando el registro de la forma habitual. Los consumidores que han habilitado la confianza en el contenido en sus clientes, sin embargo, serán capaces de ver solo las imágenes firmadas del registro.

Para habilitar la confianza en el contenido para el registro, primero vaya al registro en Azure Portal. En Directivas, seleccione Confianza del contenido>Habilitada>Guardar. También puede usar el comando az acr config content-trust update en la CLI de Azure.

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

Habilitación de la confianza en el contenido en el cliente

Para trabajar con imágenes de confianza, tanto los publicadores de imágenes como los consumidores deben habilitar la confianza en el contenido en sus clientes de Docker. Como publicador, puede firmar las imágenes que inserta en un registro con la confianza en el contenido habilitada. Como consumidor, habilitar la confianza en el contenido limita la vista de un registro a únicamente las imágenes firmadas. La confianza en el contenido está deshabilitada de forma predeterminada en los clientes de Docker, pero puede habilitarla para una sesión del shell o para un comando.

Para habilitar la confianza en el contenido para una sesión del shell, establezca la variable de entorno DOCKER_CONTENT_TRUST en 1. Por ejemplo, en el shell de Bash:

# Enable content trust for shell session
export DOCKER_CONTENT_TRUST=1

Si, en su lugar, desea habilitar o deshabilitar la confianza en el contenido para un único comando, varios comandos de Docker admiten el argumento --disable-content-trust. Para habilitar la confianza en el contenido para un único comando:

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

Si ha habilitado la confianza en el contenido para la sesión del shell y desea deshabilitarla para un único comando:

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

Concesión de permisos de firma de imágenes

Solo los usuarios o sistemas a los que se ha concedido permiso pueden insertar imágenes de confianza en el registro. Para conceder permiso de inserción de imágenes de confianza a un usuario (o a un sistema con una entidad de servicio), debe conceder a sus identidades de Microsoft Entra el rol AcrImageSigner. Esto se agrega al rol AcrPush (o equivalente) necesario para insertar imágenes en el registro. Para más información, consulte Roles y permisos de Azure Container Registry.

Importante

No se puede conceder permiso de inserción de imágenes de confianza a las siguientes cuentas administrativas:

la cuenta de administrador de un registro de contenedor de Azure;
una cuenta de usuario de Microsoft Entra ID con el rol de administrador del sistema clásico.

Nota:

A partir de julio de 2021, el rol AcrImageSigner incluye la acción Microsoft.ContainerRegistry/registries/sign/write y la acción de datos Microsoft.ContainerRegistry/registries/trustedCollections/write.

A continuación, puede ver los detalles de la concesión del rol AcrImageSigner en Azure Portal y la CLI de Azure.

Azure portal

Seleccione Access Control (IAM) .
Seleccione Agregar>Agregar asignación de roles para abrir la página Agregar asignación de roles.
Asigne el siguiente rol. En este ejemplo, el rol se asigna a un usuario individual. Para asignar roles, consulte Asignación de roles de Azure mediante Azure Portal.

Configuración Valor

Role AcrImageSigner

Asignar acceso a Usuario

Members Alain

Configuración	Valor
Role	AcrImageSigner
Asignar acceso a	Usuario
Members	Alain

CLI de Azure

Para conceder permisos de firma a un usuario con la CLI de Azure, asigne el rol AcrImageSigner al usuario, en el ámbito del registro. El formato del comando es:

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

Por ejemplo, para conceder el rol a un usuario no administrativo, puede ejecutar los siguientes comandos en una sesión autenticada de la CLI de Azure. Modifique el valor de REGISTRY para que refleje el nombre del registro de contenedor de 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

También puede conceder a una entidad de servicio derechos para insertar imágenes de confianza en el registro. El uso de una entidad de servicio es útil para sistemas de compilación y otros sistemas desatendidos que deban insertar imágenes de confianza en el registro. El formato es similar al utilizado para conceder un permiso de usuario, pero debe especificar un identificador de la entidad de servicio para el valor --assignee.

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

<service principal ID> puede ser el valor de appId, de objectId o uno de los valores de servicePrincipalNames de la entidad de servicio. Para más información sobre cómo trabajar con entidades de servicio y Azure Container Registry, consulte Autenticación de Azure Container Registry con entidades de servicio.

Importante

Después de realizar cualquier cambio de rol, ejecute az acr login para actualizar el token de identidad local para la CLI de Azure, con el fin de que los nuevos roles surtan efecto. Para obtener más información sobre la comprobación de roles de una identidad, vea Incorporación o eliminación de asignaciones de roles de Azure mediante la CLI de Azure y Solución de problemas de Azure RBAC.

Inserción de una imagen de confianza

Para insertar una etiqueta de imagen de confianza en el registro de contenedor, habilite la confianza en el contenido e inserte la imagen con docker push. La primera vez que se complete una inserción con una etiqueta firmada, se le solicitará que cree una frase de contraseña para una clave de firma de raíz y una clave de firma del repositorio. Las claves de raíz y del repositorio se generan y almacenan localmente en su equipo.

$ 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

Después del primer uso de docker push con la confianza en el contenido habilitada, el cliente de Docker usa la misma clave de raíz para las inserciones posteriores. En cada inserción posterior en el mismo repositorio, solo se le pedirá la clave del repositorio. Cada vez que inserte una imagen de confianza en un nuevo repositorio, se le pide que proporcione una frase de contraseña para una nueva clave del repositorio.

Extracción de una imagen de confianza

Para extraer una imagen de confianza, habilite la confianza en el contenido y ejecute el comando docker pull como hace habitualmente. Para extraer imágenes de confianza, el rol AcrPull es suficiente para los usuarios normales. No se requieren roles adicionales, como AcrImageSigner. Los consumidores con la confianza en el contenido habilitada pueden extraer solo imágenes con etiquetas firmadas. Este es un ejemplo de extracción de una etiqueta firmada:

$ 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 cliente con la confianza en el contenido habilitada trata de extraer una etiqueta sin firmar, se produce un error en la operación similar al siguiente:

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

Entre bambalinas

Al ejecutar docker pull, el cliente de Docker usa la misma biblioteca que en la CLI de Notary para solicitar la asignación de hash de etiqueta a SHA-256 para la etiqueta que va a extraer. Después de la validación de las firmas en los datos de confianza, el cliente indica al motor de Docker que haga una "extracción por hash". Durante la extracción, el motor usa la suma de comprobación SHA-256 como dirección de contenido para solicitar y validar el manifiesto de imagen del registro de contenedor de Azure.

Nota

Azure Container Registry no es compatible oficialmente con la CLI de Notary, pero sí es compatible con Notary Server API, que se incluye con Docker Desktop. Actualmente se recomienda la versión 0.6.0 de Notary.

Administración de claves

Como se indica en la salida de docker push cuando se inserta la primera imagen de confianza, la clave de raíz es la más confidencial. No olvide hacer una copia de seguridad de la clave de raíz y almacenarla en una ubicación segura. De forma predeterminada, el cliente de Docker almacena las claves de firma en el directorio siguiente:

~/.docker/trust/private

Puede hacer una copia de seguridad de las claves de raíz y del repositorio mediante su compresión en un archivo y su almacenamiento en una ubicación segura. Por ejemplo, en Bash:

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

Junto con las claves de raíz y del repositorio que se generan localmente, Azure Container Registry genera y almacena otras claves cuando se inserta una imagen de confianza. Para una explicación detallada de las diversas claves en la implementación de la confianza en el contenido de Docker, incluida guía de administración adicional, consulte Administración de claves para la confianza en el contenido en la documentación de Docker.

Pérdida de la clave de raíz

Si pierde el acceso a la clave de raíz, perderá el acceso a las etiquetas firmadas en cualquiera de los repositorios cuyas etiquetas se firmaron con esa clave. Azure Container Registry no puede restaurar el acceso a las etiquetas de imagen firmadas con una clave de raíz perdida. Para eliminar todos los datos de confianza (firmas) del registro, deshabilite y vuelva a habilitar la confianza en el contenido para el registro.

Advertencia

Deshabilitar y volver a habilitar la confianza en el contenido en el registro elimina todos los datos de confianza de todas las etiquetas firmadas de cada repositorio del registro. Esta acción es irreversible: Azure Container Registry no puede recuperar los datos de confianza eliminados. La deshabilitación de la confianza en el contenido no elimina las imágenes en sí.

Para deshabilitar la confianza en el contenido para el registro, vaya al registro en Azure Portal. En Directivas, seleccione Confianza del contenido>Deshabilitada>Guardar. Se le advertirá de la pérdida de todas las firmas del registro. Seleccione Aceptar para eliminar permanentemente todas las firmas del registro.

Disabling content trust for a registry in the Azure portal

Pasos siguientes

Consulte Confianza en el contenido en Docker para obtener más información sobre la confianza en el contenido, incluidos los comandos de confianza de Docker y las delegaciones de confianza. Aunque se han tratado varios aspectos importantes en este artículo, la confianza en el contenido es un tema amplio y se describe con más profundidad en la documentación de Docker.
Consulte la documentación de Azure Pipelines para un ejemplo de uso de la confianza en contenido al compilar una imagen de Docker e insertarla.