Delegaciones para la confianza de contenido

Tabla de contenidos

Las delegaciones en Docker Content Trust (DCT) te permiten controlar quién puede y quién no puede firmar una etiqueta de imagen. Una delegación tendrá un par de claves de delegación privada y pública. Una delegación podría contener múltiples pares de claves y colaboradores para a) permitir que varios usuarios formen parte de una delegación, y b) admitir la rotación de claves.

La delegación más importante dentro de Docker Content Trust es targets/releases. Esta es vista como la fuente canónica de una etiqueta de imagen de confianza, y sin la clave de un colaborador bajo esta delegación, este no podrá firmar una etiqueta.

Afortunadamente, al usar los comandos de docker trust, se iniciará automáticamente el repositorio, se gestionarán las claves del repositorio y se añadirá la clave del colaborador a la delegación targets/releases mediante docker trust signer add.

Configurar el cliente de Docker

Por defecto, los comandos de docker trust esperan que la URL del servidor Notary sea la misma que la URL del registro especificada en la etiqueta de la imagen (siguiendo una lógica similar a la de docker push). Al usar Docker Hub o DTR, la URL del servidor Notary es la misma que la del registro. Sin embargo, para entornos autoalojados (self-hosted) o registros de terceros, deberás especificar una URL alternativa del servidor Notary. Esto se hace con:

$ export DOCKER_CONTENT_TRUST_SERVER=https://<URL>:<PORT>

Si no exportas esta variable en entornos autoalojados, es posible que veas errores como:

$ docker trust signer add --key cert.pem jeff registry.example.com/admin/demo
Adding signer "jeff" to registry.example.com/admin/demo...
<...>
Error: trust data missing for remote repository registry.example.com/admin/demo or remote repository not found: timestamp key trust data unavailable.  Has a notary repository been initialized?

$ docker trust inspect registry.example.com/admin/demo --pretty
WARN[0000] Error while downloading remote metadata, using cached timestamp - this might not be the latest version available remotely
<...>

Si has habilitado la autenticación para tu servidor Notary, o estás usando DTR, deberás iniciar sesión antes de poder subir datos al servidor Notary.

$ docker login registry.example.com/user/repo
Username: admin
Password:

Login Succeeded

$ docker trust signer add --key cert.pem jeff registry.example.com/user/repo
Adding signer "jeff" to registry.example.com/user/repo...
Initializing signed repository for registry.example.com/user/repo...
Successfully initialized "registry.example.com/user/repo"
Successfully added signer: jeff to registry.example.com/user/repo

Si no inicias sesión, verás:

$ docker trust signer add --key cert.pem jeff registry.example.com/user/repo
Adding signer "jeff" to registry.example.com/user/repo...
Initializing signed repository for registry.example.com/user/repo...
you are not authorized to perform this operation: server returned 401.

Failed to add signer to: registry.example.com/user/repo

Configurar el cliente de Notary

Algunas de las características más avanzadas de DCT requieren la CLI de Notary. Para instalar y configurar la CLI de Notary:

Descarga el cliente y asegúrate de que esté disponible en tu ruta de búsqueda (PATH).
Crea un archivo de configuración en ~/.notary/config.json con el siguiente contenido:

{
  "trust_dir" : "~/.docker/trust",
  "remote_server": {
    "url": "https://registry.example.com",
    "root_ca": "../.docker/ca.pem"
  }
}

El archivo de configuración recién creado contiene información sobre la ubicación de tus datos locales de confianza de Docker y la URL del servidor Notary.

Para obtener información más detallada sobre cómo usar Notary fuera de los casos de uso de Docker Content Trust, consulta la documentación de la CLI de Notary.

Crear claves de delegación

Un requisito previo para añadir a tu primer colaborador es tener un par de claves de delegación. Estas claves pueden generarse localmente utilizando docker trust o ser generadas por una autoridad de certificación.

Usar Docker Trust para generar claves

Docker trust tiene un generador incorporado para un par de claves de delegación, docker trust key generate <name>. Ejecutar este comando cargará automáticamente la clave privada de delegación en el almacén local de confianza de Docker.

$ docker trust key generate jeff

Generating key for jeff...
Enter passphrase for new jeff key with ID 9deed25: 
Repeat passphrase for new jeff key with ID 9deed25: 
Successfully generated and loaded private key. Corresponding public key available: /home/ubuntu/Documents/mytrustdir/jeff.pub

Generar claves manualmente

Si necesitas generar manualmente una clave privada (ya sea RSA o ECDSA) y un certificado X.509 que contenga la clave pública, puedes utilizar herramientas locales como openssl o cfssl junto con una autoridad de certificación local o corporativa.

Aquí tienes un ejemplo de cómo generar una clave RSA de 2048 bits (todas las claves RSA deben tener al menos 2048 bits):

$ openssl genrsa -out delegation.key 2048

Generating RSA private key, 2048 bit long modulus
....................................................+++
............+++
e is 65537 (0x10001)

Se debe mantener delegation.key privada porque se utiliza para firmar etiquetas.

Luego, se debe generar un certificado X.509 que contenga la clave pública. Aquí tienes el comando para generar una solicitud de firma de certificado (CSR):

$ openssl req -new -sha256 -key delegation.key -out delegation.csr

Después, se puede enviar a la CA en la que confíes para firmar certificados, o se puede autofirmar el certificado (en este ejemplo, se crea un certificado válido por 1 año):

$ openssl x509 -req -sha256 -days 365 -in delegation.csr -signkey delegation.key -out delegation.crt

Luego, te deben proporcionar delegation.crt, ya sea autofirmado o firmado por una CA.

Finalmente, deberás añadir la clave privada a tu almacén local de confianza de Docker.

$ docker trust key load delegation.key --name jeff

Loading key from "delegation.key"...
Enter passphrase for new jeff key with ID 8ae710e: 
Repeat passphrase for new jeff key with ID 8ae710e: 
Successfully imported key from delegation.key

Ver las claves de delegación locales

Para enumerar las claves que se han importado al almacén local de confianza de Docker, podemos usar la CLI de Notary.

$ notary key list

ROLE       GUN                          KEY ID                                                              LOCATION
----       ---                          ------                                                              --------
root                                    f6c6a4b00fefd8751f86194c7d87a3bede444540eb3378c4a11ce10852ab1f96    /home/ubuntu/.docker/trust/private
jeff                                    9deed251daa1aa6f9d5f9b752847647cf8d705da0763aa5467650d0987ed5306    /home/ubuntu/.docker/trust/private

Gestionar delegaciones en un servidor Notary

Cuando se añade la primera delegación al servidor Notary utilizando docker trust, se inician automáticamente los datos de confianza para el repositorio. Esto incluye la creación de las claves de snapshot y de target de Notary, y la rotación de la clave de snapshot para que sea gestionada por el servidor Notary. Puedes encontrar más información sobre estas claves en Gestionar claves para la confianza de contenido.

Al iniciar un repositorio, necesitarás la clave y la frase de contraseña de una clave raíz canónica local de Notary. Si no has iniciado un repositorio antes y, por lo tanto, no tienes una clave raíz de Notary, docker trust creará una por ti.

Important
Asegúrate de proteger y hacer una copia de seguridad de tu clave raíz canónica de Notary.

Iniciar el repositorio

Para subir la primera clave a una delegación, iniciando al mismo tiempo un repositorio, puedes utilizar el comando docker trust signer add. Esto añadirá la clave pública del colaborador a la delegación targets/releases y creará una segunda delegación targets/<name>.

Para DCT, el nombre de la segunda delegación (en el ejemplo a continuación, jeff) sirve para ayudarte a realizar un seguimiento del propietario de las claves. En casos de uso más avanzados de Notary, se utilizan delegaciones adicionales para establecer una jerarquía.

$ docker trust signer add --key cert.pem jeff registry.example.com/admin/demo

Adding signer "jeff" to registry.example.com/admin/demo...
Initializing signed repository for registry.example.com/admin/demo...
Enter passphrase for root key with ID f6c6a4b: 
Enter passphrase for new repository key with ID b0014f8: 
Repeat passphrase for new repository key with ID b0014f8: 
Successfully initialized "registry.example.com/admin/demo"
Successfully added signer: jeff to registry.example.com/admin/demo

Puedes ver qué claves se han subido al servidor Notary para cada repositorio utilizando el comando docker trust inspect.

$ docker trust inspect --pretty registry.example.com/admin/demo

No signatures for registry.example.com/admin/demo


List of signers and their keys for registry.example.com/admin/demo

SIGNER              KEYS
jeff                1091060d7bfd

Administrative keys for registry.example.com/admin/demo

  Repository Key:	b0014f8e4863df2d028095b74efcb05d872c3591de0af06652944e310d96598d
  Root Key:	64d147e59e44870311dd2d80b9f7840039115ef3dfa5008127d769a5f657a5d7

También puedes usar la CLI de Notary para enumerar las delegaciones y las claves. Aquí puedes ver claramente que las claves se asociaron a targets/releases y targets/jeff.

$ notary delegation list registry.example.com/admin/demo

ROLE                PATHS             KEY IDS                                                             THRESHOLD
----                -----             -------                                                             ---------
targets/jeff        "" <all paths>    1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1    1
                                          
targets/releases    "" <all paths>    1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1    1

Añadir firmantes adicionales

Docker Trust te permite configurar múltiples delegaciones por repositorio, lo que te permite gestionar el ciclo de vida de las delegaciones. Al añadir delegaciones adicionales con docker trust, la clave del colaborador se añade de nuevo al rol targets/releases.

Ten en cuenta que necesitarás la frase de contraseña de la clave del repositorio; esta se habría configurado cuando iniciaste el repositorio por primera vez.

$ docker trust signer add --key ben.pub ben registry.example.com/admin/demo

Adding signer "ben" to registry.example.com/admin/demo...
Enter passphrase for repository key with ID b0014f8: 
Successfully added signer: ben to registry.example.com/admin/demo

Comprueba para verificar que ahora hay 2 delegaciones (firmantes).

$ docker trust inspect --pretty registry.example.com/admin/demo

No signatures for registry.example.com/admin/demo

List of signers and their keys for registry.example.com/admin/demo

SIGNER              KEYS
ben                 afa404703b25
jeff                1091060d7bfd

Administrative keys for registry.example.com/admin/demo

  Repository Key:	b0014f8e4863df2d028095b74efcb05d872c3591de0af06652944e310d96598d
  Root Key:	64d147e59e44870311dd2d80b9f7840039115ef3dfa5008127d769a5f657a5d7

Añadir claves a una delegación existente

Para admitir aspectos como la rotación de claves y la expiración o retiro de claves, puedes publicar múltiples claves de colaboradores por delegación. El único requisito previo aquí es asegurarse de utilizar el mismo nombre de delegación (en este caso, jeff). Docker trust se encargará automáticamente de añadir esta nueva clave a targets/releases.

Note
Ten en cuenta que necesitarás la frase de contraseña de la clave del repositorio; esta se habría configurado cuando iniciaste el repositorio por primera vez.

$ docker trust signer add --key cert2.pem jeff registry.example.com/admin/demo

Adding signer "jeff" to registry.example.com/admin/demo...
Enter passphrase for repository key with ID b0014f8: 
Successfully added signer: jeff to registry.example.com/admin/demo

Comprueba para verificar que la delegación (firmante) ahora contiene múltiples Key IDs.

$ docker trust inspect --pretty registry.example.com/admin/demo

No signatures for registry.example.com/admin/demo


List of signers and their keys for registry.example.com/admin/demo

SIGNER              KEYS
jeff                1091060d7bfd, 5570b88df073

Administrative keys for registry.example.com/admin/demo

  Repository Key:	b0014f8e4863df2d028095b74efcb05d872c3591de0af06652944e310d96598d
  Root Key:	64d147e59e44870311dd2d80b9f7840039115ef3dfa5008127d769a5f657a5d7

Eliminar una delegación

Si necesitas eliminar una delegación, incluidas las claves de colaboradores que están asociadas al rol targets/releases, puedes utilizar el comando docker trust signer remove.

Note
Las etiquetas que fueron firmadas por la delegación eliminada deberán ser firmadas de nuevo por una delegación activa.

$ docker trust signer remove ben registry.example.com/admin/demo
Removing signer "ben" from registry.example.com/admin/demo...
Enter passphrase for repository key with ID b0014f8: 
Successfully removed ben from registry.example.com/admin/demo

Resolución de problemas

Si ves un error que indica que no hay claves utilizables en targets/releases, deberás añadir delegaciones adicionales utilizando docker trust signer add antes de volver a firmar las imágenes.
WARN[0000] role targets/releases has fewer keys than its threshold of 1; it will not be usable until keys are added to it
Si ya has añadido delegaciones adicionales y ves un mensaje de error que indica que no hay firmas válidas en targets/releases, deberás volver a firmar el archivo de delegación de targets/releases con la CLI de Notary.
WARN[0000] Error getting targets/releases: valid signatures did not meet threshold for targets/releases
La firma de nuevo del archivo de delegación se realiza con el comando notary witness
$ notary witness registry.example.com/admin/demo targets/releases --publish
Para obtener más información sobre el comando notary witness, consulta la guía de uso avanzado del cliente Notary

Eliminar la clave de un colaborador de una delegación

Como parte de la rotación de claves para una delegación, es posible que desees eliminar una clave de delegación local pero conservar la delegación. Esto se puede hacer con la CLI de Notary.

Recuerda que tendrás que eliminar la clave tanto del rol targets/releases como del rol específico de ese firmante targets/<name>.

Necesitaremos obtener el ID de la clave (Key ID) del servidor Notary

$ notary delegation list registry.example.com/admin/demo

ROLE                PATHS             KEY IDS                                                             THRESHOLD
----                -----             -------                                                             ---------
targets/jeff        "" <all paths>    8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9    1
                                      1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1    
targets/releases    "" <all paths>    8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9    1
                                      1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1

Eliminar de la delegación targets/releases

$ notary delegation remove registry.example.com/admin/demo targets/releases 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 --publish

Auto-publishing changes to registry.example.com/admin/demo
Enter username: admin
Enter password: 
Enter passphrase for targets key with ID b0014f8: 
Successfully published changes for repository registry.example.com/admin/demo

Eliminar de la delegación targets/<name>

$ notary delegation remove registry.example.com/admin/demo targets/jeff 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 --publish

Removal of delegation role targets/jeff with keys [5570b88df0736c468493247a07e235e35cf3641270c944d0e9e8899922fc6f99], to repository "registry.example.com/admin/demo" staged for next publish.

Auto-publishing changes to registry.example.com/admin/demo
Enter username: admin    
Enter password: 
Enter passphrase for targets key with ID b0014f8: 
Successfully published changes for repository registry.example.com/admin/demo

Comprobar la lista de delegaciones restante

$ notary delegation list registry.example.com/admin/demo

ROLE                PATHS             KEY IDS                                                             THRESHOLD
----                -----             -------                                                             ---------
targets/jeff        "" <all paths>    8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9    1    
targets/releases    "" <all paths>    8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9    1

Eliminar una clave privada de delegación local

Como parte de la rotación de claves de delegación, es posible que debas eliminar una clave de delegación local del almacén local de confianza de Docker. Esto se hace con la CLI de Notary, utilizando el comando notary key remove.

Necesitaremos obtener el ID de la clave (Key ID) del almacén local de confianza de Docker

$ notary key list

ROLE       GUN                          KEY ID                                                              LOCATION
----       ---                          ------                                                              --------
root                                    f6c6a4b00fefd8751f86194c7d87a3bede444540eb3378c4a11ce10852ab1f96    /home/ubuntu/.docker/trust/private
admin                                   8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9    /home/ubuntu/.docker/trust/private
jeff                                    1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1    /home/ubuntu/.docker/trust/private
targets    ...example.com/admin/demo    c819f2eda8fba2810ec6a7f95f051c90276c87fddfc3039058856fad061c009d    /home/ubuntu/.docker/trust/private

Eliminar la clave del almacén local de confianza de Docker

$ notary key remove 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1

Are you sure you want to remove 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 (role jeff) from /home/ubuntu/.docker/trust/private?  (yes/no)  y

Deleted 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 (role jeff) from /home/ubuntu/.docker/trust/private.

Eliminar todos los datos de confianza de un repositorio

Puedes eliminar todos los datos de confianza de un repositorio, incluidos los del repositorio, target, snapshot y todas las claves de delegaciones utilizando la CLI de Notary.

Esto suele ser requerido por un registro de contenedores antes de que se pueda eliminar un repositorio en particular.

$ notary delete registry.example.com/admin/demo --remote

Deleting trust data for repository registry.example.com/admin/demo
Enter username: admin
Enter password: 
Successfully deleted local and remote trust data for repository registry.example.com/admin/demo

$ docker trust inspect --pretty registry.example.com/admin/demo

No signatures or cannot access registry.example.com/admin/demo

¿En qué te puedo ayudar?

Delegaciones para la confianza de contenido

Configurar el cliente de Docker

Configurar el cliente de Notary

Crear claves de delegación

Usar Docker Trust para generar claves

Generar claves manualmente

Ver las claves de delegación locales

Gestionar delegaciones en un servidor Notary

Iniciar el repositorio

Añadir firmantes adicionales

Añadir claves a una delegación existente

Eliminar una delegación

Resolución de problemas

Eliminar la clave de un colaborador de una delegación

Eliminar una clave privada de delegación local

Eliminar todos los datos de confianza de un repositorio

Información relacionada