Délégations pour la confiance de contenu

Table des matières

Les délégations dans Docker Content Trust (DCT) vous permettent de contrôler qui peut et ne peut pas signer une étiquette d'image. Une délégation aura une paire de clés de délégation privées et publiques. Une délégation pourrait contenir plusieurs paires de clés et contributeurs afin de a) permettre à plusieurs utilisateurs d'être partie d'une délégation, et b) de supporter la rotation des clés.

La délégation la plus importante dans Docker Content Trust est targets/releases. Ceci est vu comme la source canonique d'une étiquette d'image de confiance, et sans qu'une clé de contributeur soit sous cette délégation, ils ne pourront pas signer une étiquette.

Heureusement, lors de l'utilisation des commandes $ docker trust, nous initialiserons automatiquement un dépôt, gérerons les clés du dépôt, et ajouterons la clé d'un collaborateur à la délégation targets/releases via docker trust signer add.

Configuration du client Docker

Par défaut, les commandes $ docker trust s'attendent à ce que l'URL du serveur notary soit la même que l'URL du registre spécifiée dans l'étiquette d'image (suivant une logique similaire à $ docker push). Lors de l'utilisation de Docker Hub ou DTR, l'URL du serveur notary est la même que l'URL du registre. Cependant, pour les environnements auto-hébergés ou les registres tiers, vous devrez spécifier une URL alternative pour le serveur notary. Ceci se fait avec :

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

Si vous n'exportez pas cette variable dans les environnements auto-hébergés, vous pourriez voir des erreurs telles que :

$ 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 vous avez activé l'authentification pour votre serveur notary, ou utilisez DTR, vous devrez vous connecter avant de pouvoir pousser des données vers le serveur 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 vous ne vous connectez pas, vous verrez :

$ 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

Configuration du client Notary

Certaines des fonctionnalités plus avancées de DCT nécessitent le CLI Notary. Pour installer et configurer le CLI Notary :

Téléchargez le client et assurez-vous qu'il soit disponible dans votre chemin.
Créez un fichier de configuration à ~/.notary/config.json avec le contenu suivant :

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

Le fichier de configuration nouvellement créé contient des informations sur l'emplacement de vos données de confiance Docker locales et l'URL du serveur notary.

Pour plus d'informations détaillées sur comment utiliser notary en dehors des cas d'usage de Docker Content Trust, référez-vous à la documentation CLI Notary ici

Création de clés de délégation

Un prérequis pour ajouter votre premier contributeur est une paire de clés de délégation. Ces clés peuvent soit être générées localement en utilisant $ docker trust, soit générées par une autorité de certification.

Utilisation de Docker Trust pour générer des clés

Docker trust a un générateur intégré pour une paire de clés de délégation, $ docker trust generate <n>. L'exécution de cette commande chargera automatiquement la clé privée de délégation dans le magasin de confiance Docker local.

$ 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

Génération manuelle de clés

Si vous devez générer manuellement une clé privée (soit RSA ou ECDSA) et un certificat X.509 contenant la clé publique, vous pouvez utiliser des outils locaux comme openssl ou cfssl avec une Autorité de Certification locale ou d'entreprise.

Voici un exemple de comment générer une clé RSA de 2048 bits (toutes les clés RSA doivent être d'au moins 2048 bits) :

$ openssl genrsa -out delegation.key 2048

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

Ils doivent garder delegation.key privée car elle est utilisée pour signer les étiquettes.

Ensuite, ils doivent générer un certificat x509 contenant la clé publique, qui est ce dont vous avez besoin de leur part. Voici la commande pour générer une CSR (demande de signature de certificat) :

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

Ensuite, ils peuvent l'envoyer à quelque CA que vous faites confiance pour signer les certificats, ou ils peuvent auto-signer le certificat (dans cet exemple, créant un certificat qui est valide pour 1 an) :

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

Ensuite, ils doivent vous donner delegation.crt, qu'il soit auto-signé ou signé par une CA.

Finalement, vous devrez ajouter la clé privée dans votre magasin de confiance Docker local.

$ 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

Visualisation des clés de délégation locales

Pour lister les clés qui ont été importées dans le magasin de confiance Docker local, nous pouvons utiliser le CLI Notary.

$ notary key list

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

Gestion des délégations dans un serveur Notary

Quand la première délégation est ajoutée au serveur Notary en utilisant $ docker trust, nous initions automatiquement les données de confiance pour le dépôt. Cela inclut la création des clés cibles et instantanés notary, et la rotation de la clé d'instantané pour être gérée par le serveur notary. Plus d'informations sur ces clés peuvent être trouvées ici

Lors de l'initiation d'un dépôt, vous aurez besoin de la clé et de la phrase de passe d'une Clé Racine Canonique Notary locale. Si vous n'avez pas initié un dépôt auparavant, et n'avez donc pas de clé racine Notary, $ docker trust en créera une pour vous.

Important

Assurez-vous de protéger et sauvegarder votre Clé Racine Canonique Notary.

Initiation du dépôt

Pour télécharger la première clé vers une délégation, en même temps qu'initialiser un dépôt, vous pouvez utiliser la commande $ docker trust signer add. Cela ajoutera la clé publique du contributeur à la délégation targets/releases, et créera une seconde délégation targets/<n>.

Pour DCT, le nom de la seconde délégation, dans l'exemple ci-dessous jeff, est là pour vous aider à garder trace du propriétaire des clés. Dans des cas d'usage plus avancés de Notary, des délégations supplémentaires sont utilisées pour la hiérarchie.

$ 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

Vous pouvez voir quelles clés ont été poussées vers le serveur Notary pour chaque dépôt avec la commande $ 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

Vous pourriez aussi utiliser le CLI Notary pour lister les délégations et clés. Ici vous pouvez clairement voir que les clés ont été attachées à targets/releases et 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

Ajout de signataires supplémentaires

Docker Trust vous permet de configurer plusieurs délégations par dépôt, vous permettant de gérer le cycle de vie des délégations. Lors de l'ajout de délégations supplémentaires avec $ docker trust, la clé des collaborateurs est une fois de plus ajoutée au rôle targets/release.

Notez que vous aurez besoin de la phrase de passe pour la clé du dépôt ; cela aurait été configuré quand vous avez d'abord initié le dépôt.

$ 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

Vérifiez pour prouver qu'il y a maintenant 2 délégations (Signataire).

$ 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

Ajout de clés à une délégation existante

Pour supporter des choses comme la rotation de clés et l'expiration / retraite de clés, vous pouvez publier plusieurs clés de contributeur par délégation. Le seul prérequis ici est de s'assurer que vous utilisez le même nom de délégation, dans ce cas jeff. Docker trust gérera automatiquement l'ajout de cette nouvelle clé à targets/releases.

Note

Vous aurez besoin de la phrase de passe pour la clé du dépôt ; cela aurait été configuré quand vous avez d'abord initié le dépôt.

$ 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

Vérifiez pour prouver que la délégation (Signataire) contient maintenant plusieurs ID de clé.

$ 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

Suppression d'une délégation

Si vous devez supprimer une délégation, incluant les clés de contributeur qui sont attachées au rôle targets/releases, vous pouvez utiliser la commande $ docker trust signer remove.

Note

Les étiquettes qui ont été signées par la délégation supprimée devront être resignées par une délégation active

$ 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

Dépannage

Si vous voyez une erreur qu'il n'y a pas de clés utilisables dans targets/releases, vous devrez ajouter des délégations supplémentaires en utilisant docker trust signer add avant de resigner les images.
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 vous avez déjà ajouté des délégations supplémentaires et voyez un message d'erreur qu'il n'y a pas de signatures valides dans targest/releases, vous devrez resigner le fichier de délégation targets/releases avec le CLI Notary.
WARN[0000] Error getting targets/releases: valid signatures did not meet threshold for targets/releases
Resigner le fichier de délégation se fait avec la commande $ notary witness
$ notary witness registry.example.com/admin/demo targets/releases --publish
Plus d'informations sur la commande $ notary witness peuvent être trouvées ici

Suppression de la clé d'un contributeur d'une délégation

Dans le cadre de la rotation des clés pour une délégation, vous pouvez vouloir supprimer une clé individuelle mais conserver la délégation. Cela peut être fait avec le CLI Notary.

Rappelez-vous que vous devrez supprimer la clé à la fois du rôle targets/releases et du rôle spécifique à ce signataire targets/<n>.

Nous devrons récupérer l'ID de clé du serveur 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

Supprimer de la délégation 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

Supprimer de la délégation targets/<n>

$ 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

Vérifier la liste de délégation 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

Suppression d'une clé privée de délégation locale

Dans le cadre de la rotation des clés de délégation, vous pourriez avoir besoin de supprimer une clé de délégation locale du magasin de confiance Docker local. Cela se fait avec le CLI Notary, en utilisant la commande $ notary key remove.

Nous devrons obtenir l'ID de clé du magasin de confiance Docker local

$ 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

Supprimer la clé du magasin de confiance Docker local

$ 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.

Suppression de toutes les données de confiance d'un dépôt

Vous pouvez supprimer toutes les données de confiance d'un dépôt, incluant le dépôt, la cible, l'instantané et toutes les clés de délégations en utilisant le CLI Notary.

Ceci est souvent requis par un registre de conteneurs avant qu'un dépôt particulier puisse être supprimé.

$ 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