## Contributing

Si vous êtes intéressé·e par une contribution à `cosign`, veuillez lire la [documentation sur les contributions](https://github.com/sigstore/cosign/blob/HEAD/CONTRIBUTING.md).

Le développement futur de Cosign sera axé sur la prochaine version majeure, qui sera basée sur
[sigstore-go](https://github.com/sigstore/sigstore-go). Les mainteneurs se concentreront sur le développement de fonctionnalités dans
sigstore-go. Les contributions à sigstore-go, en particulier autour de l'utilisation de vos propres clés et de la signature, sont appréciées.
Veuillez consulter le [suivi des problèmes](https://github.com/sigstore/sigstore-go/issues) pour les bonnes premières issues.

Cosign 2.x est une version stable et continuera de recevoir des mises à jour de fonctionnalités et des corrections de bogues périodiques. Les PR
de petite portée et de petite taille ont le plus de chances d'être rapidement examinées.

Les PR qui modifient ou cassent significativement l'API ne seront pas acceptées. Les PR de taille importante mais qui
n'introduisent pas de changements cassants peuvent être acceptées, mais seront considérées comme moins prioritaires que les PR dans sigstore-go.

## Dockerfile

Voici comment installer et utiliser cosign dans un Dockerfile via l'image ghcr.io/sigstore/cosign/cosign :```shell
FROM ghcr.io/sigstore/cosign/cosign:v2.4.1 as cosign-bin

# Source: https://github.com/chainguard-images/static
FROM cgr.dev/chainguard/static:latest
COPY --from=cosign-bin /ko-app/cosign /usr/local/bin/cosign
ENTRYPOINT [ "cosign" ]

Note that there may be personally identifiable information associated with this signed artifact.
This may include the email address associated with the account with which you authenticate.
This information will be used for signing this artifact and will be stored in public transparency logs and cannot be removed later.

Cosign vous invitera à vous authentifier via OIDC, où vous vous connecterez avec votre adresse e-mail.
En coulisses, cosign demandera un certificat de signature de code à l'autorité de certification Fulcio.
Le sujet du certificat correspondra à l'adresse e-mail avec laquelle vous vous êtes connecté.
Cosign stockera ensuite la signature et le certificat dans le journal de transparence Rekor, et téléchargera la signature vers le registre OCI en même temps que l'image que vous signez.

### Vérifier un conteneur

Pour vérifier l'image, vous devrez fournir le sujet de certificat et l'émetteur de certificat attendus via les options `--certificate-identity` et `--certificate-oidc-issuer` :```
cosign verify $IMAGE --certificate-identity=$IDENTITY --certificate-oidc-issuer=$OIDC_ISSUER

### Verify a container in an air-gapped environment

**Note :** Cette section est obsolète.

**Note :** La plupart des workflows de vérification nécessitent de demander périodiquement des clés de service auprès d'un dépôt TUF.
Pour la vérification hors ligne des signatures à l'aide de l'instance public-good, vous devrez récupérer le fichier
[racine de confiance](https://github.com/sigstore/root-signing/blob/main/targets/trusted_root.json) depuis le dépôt TUF
de production. Le contenu de ce fichier est susceptible de changer sans préavis. En n'utilisant pas TUF, vous devrez
mettre en place votre propre mécanisme pour maintenir à jour votre copie hors ligne de ce fichier.

Cosign peut effectuer une vérification entièrement hors ligne en vérifiant un [bundle](https://github.com/sigstore/cosign/blob/HEAD/specs/SIGNATURE_SPEC.md#properties) qui est généralement distribué sous forme d'annotation sur le manifeste de l'image.
Tant que cette annotation est présente, la vérification hors ligne peut être effectuée.
Cette annotation de bundle est toujours incluse par défaut pour la signature sans clé, de sorte que la fonctionnalité `cosign sign` par défaut inclut tous les éléments nécessaires à la vérification hors ligne.

Pour vérifier une image dans un environnement air-gapped, l'image et les signatures doivent être disponibles localement sur le système de fichiers.

Une image peut être enregistrée localement à l'aide de `cosign save` (notez que cette étape doit être effectuée avec une connexion réseau) :```
cosign initialize # This will pull in the latest TUF root
cosign save $IMAGE_NAME --dir ./path/to/dir

Vous devrez fournir les valeurs attendues pour `$CERT_IDENTITY` et `$CERT_OIDC_ISSUER` afin de vérifier correctement cette image.
Si vous avez signé avec une paire de clés, la même commande fonctionnera, à condition que le matériel de clé publique soit présent localement:```
cosign verify --key cosign.pub --offline --local-image ./path/to/dir

### Troubleshooting

Si vous rencontrez des problèmes avec Cosign, assurez-vous d'abord d'utiliser une version récente : le projet Cosign prend activement en charge la version la plus récente ainsi que la dernière version de la série v2.

#### Problèmes courants et solutions

1. La vérification échoue avec `failed to verify timestamps: threshold not met for verified log entry integrated timestamps: 0 < 1` : vous vérifiez peut-être une signature qui nécessite la prise en charge des horodatages RFC3161
   * Mettez à niveau vers la version la plus récente de Cosign ou
   * Avec Cosign 2.6.x, utilisez `--use-signed-timestamps`
1. La vérification échoue avec `no signatures found` : vous vérifiez peut-être une signature d'image qui nécessite la prise en charge du journal de transparence Rekor v2
   * Mettez à niveau vers la version la plus récente de Cosign
1. La signature échoue avec des erreurs HTTP : la signature avec Cosign dépend de plusieurs services Sigstore. Réessayer en cas d'échec peut être une solution de contournement utile si l'un de ces services échoue -- signaler les problèmes spécifiques est également apprécié

#### Mon problème est autre chose

Veuillez ouvrir un [problème](https://github.com/sigstore/cosign/issues/new/choose) ou poser votre question dans le [canal Slack](#info).

## Travailler avec d'autres artefacts

Les registres OCI sont utiles pour stocker bien plus que de simples images de conteneurs !
`Cosign` inclut également des utilitaires pour publier des artefacts génériques, notamment des binaires, des scripts et des fichiers de configuration, à l'aide du protocole OCI.

Cette section montre comment les exploiter pour créer un système de distribution d'artefacts facile à utiliser et rétrocompatible, qui s'intègre bien avec le reste de Sigstore.

Consultez [la documentation](https://docs.sigstore.dev/cosign/signing/other_types/) pour plus d'informations.

### Blobs

Vous pouvez publier un artefact avec `cosign upload blob` :```shell
$ echo "my first artifact" > artifact
$ BLOB_SUM=$(shasum -a 256 artifact | cut -d' ' -f 1) && echo "$BLOB_SUM"
c69d72c98b55258f9026f984e4656f0e9fd3ef024ea3fac1d7e5c7e6249f1626
$ BLOB_NAME=my-artifact-$(uuidgen | head -c 8 | tr 'A-Z' 'a-z')
$ BLOB_URI=ttl.sh/$BLOB_NAME:1h

$ BLOB_URI_DIGEST=$(cosign upload blob -f artifact $BLOB_URI) && echo "$BLOB_URI_DIGEST"
Uploading file from [artifact] to [ttl.sh/my-artifact-f42c22e0:5m] with media type [text/plain]
File [artifact] is available directly at [ttl.sh/v2/my-artifact-f42c22e0/blobs/sha256:c69d72c98b55258f9026f984e4656f0e9fd3ef024ea3fac1d7e5c7e6249f1626]
Uploaded image to:
ttl.sh/my-artifact-f42c22e0@sha256:790d47850411e902aabebc3a684eeb78fcae853d4dd6e1cc554d70db7f05f99f

Le digest est intégré directement dans l'URL, ils peuvent donc le vérifier également :```shell
$ cat artifact-fetched | shasum -a 256
c69d72c98b55258f9026f984e4656f0e9fd3ef024ea3fac1d7e5c7e6249f1626  -

Comme d'habitude, assurez-vous de référencer les images que vous signez par leur digest afin de ne pas signer la mauvaise chose !

#### Tekton Bundles

Les bundles [Tekton](https://tekton.dev) peuvent être téléversés et gérés dans un registre OCI.
La spécification se trouve [ici](https://tekton.dev/docs/pipelines/tekton-bundle-contracts/).
Cela signifie qu'ils peuvent également être signés et vérifiés avec `cosign`.

Les bundles Tekton peuvent actuellement être téléversés avec la [tkn cli](https://github.com/tektoncd/cli), mais nous pourrions ajouter cette prise en charge à
`cosign` à l'avenir.```shell
$ tkn bundle push us.gcr.io/dlorenc-vmtest2/pipeline:latest -f task-output-image.yaml
Creating Tekton Bundle:
        - Added TaskRun:  to image

Pushed Tekton Bundle to us.gcr.io/dlorenc-vmtest2/pipeline@sha256:124e1fdee94fe5c5f902bc94da2d6e2fea243934c74e76c2368acdc8d3ac7155
$ cosign sign --key cosign.key us.gcr.io/dlorenc-vmtest2/pipeline@sha256:124e1fdee94fe5c5f902bc94da2d6e2fea243934c74e76c2368acdc8d3ac7155
Enter password for private key:
tlog entry created with index: 5086
Pushing signature to: us.gcr.io/dlorenc-vmtest2/demo:sha256-124e1fdee94fe5c5f902bc94da2d6e2fea243934c74e76c2368acdc8d3ac7155.sig

#### eBPF

Les modules [eBPF](https://ebpf.io) peuvent également être stockés dans un registre OCI, à l'aide de cette [spécification](https://github.com/solo-io/bumblebee/tree/main/spec).

L'image ci-dessous a été construite à l'aide de l'outil `bee`. Plus d'informations peuvent être trouvées [ici](https://github.com/solo-io/bumblebee/).

Cosign peut ensuite signer ces images comme il peut signer n'importe quelle autre image OCI.```shell
$ bee build ./examples/tcpconnect/tcpconnect.c localhost:5000/tcpconnect:test
$ bee push localhost:5000/tcpconnect:test
$ cosign sign  --key cosign.key localhost:5000/tcpconnect@sha256:7a91c50d922925f152fec96ed1d84b7bc6b2079c169d68826f6cf307f22d40e6
Enter password for private key:
Pushing signature to: localhost:5000/tcpconnect
$ cosign verify --key cosign.pub localhost:5000/tcpconnect:test

Verification for localhost:5000/tcpconnect:test --
The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - The signatures were verified against the specified public key

[{"critical":{"identity":{"docker-reference":"localhost:5000/tcpconnect"},"image":{"docker-manifest-digest":"sha256:7a91c50d922925f152fec96ed1d84b7bc6b2079c169d68826f6cf307f22d40e6"},"type":"cosign container image signature"},"optional":null}]

Tous les systèmes de gestion de clés standard sont pris en charge.
Les charges utiles sont signées à l'aide de la spécification de signature DSSE, définie [ici](https://github.com/secure-systems-lab/dsse).

Pour vérifier :```shell
$ cosign verify-attestation --key cosign.pub $IMAGE_URI

Merci de tester et de signaler les bogues si vous voyez des problèmes !
Les instructions se trouvent dans l'[issue de suivi](https://github.com/sigstore/cosign/issues/40).

## Mises en garde

### Fonctionnalités intentionnellement absentes

`cosign` ne génère que des clés ECDSA-P256 et utilise des hachages SHA256, à la fois pour la signature sans clé éphémère et la signature avec clé gérée.
Les clés sont stockées au format PKCS8 encodé en PEM.
Cependant, vous pouvez utiliser `cosign` pour stocker et récupérer des signatures dans n'importe quel format, quel que soit l'algorithme.

### Éléments qui devraient probablement changer

#### Formats de charge utile

`cosign` ne prend en charge que le format [simple signing](https://www.redhat.com/en/blog/container-image-signing)
de Red Hat pour les charges utiles.
Cela ressemble à :```json
{
    "critical": {
           "identity": {
               "docker-reference": "testing/manifest"
           },
           "image": {
               "Docker-manifest-digest": "sha256:20be...fe55"
           },
           "type": "cosign container image signature"
    },
    "optional": {
           "creator": "Bob the Builder",
           "timestamp": 1458239713
    }
}

Ainsi, la signature de `gcr.io/dlorenc-vmtest2/demo` sera stockée dans `gcr.io/my-new-repo/demo:sha256-DIGEST.sig`.

Remarque : différents registres peuvent attendre différents formats pour le « référentiel ».

* Pour utiliser [GCR](https://cloud.google.com/container-registry), un nom de
  registre comme `gcr.io/$REPO` suffit, comme dans l'exemple ci-dessus.
* Pour utiliser [Artifact Registry](https://cloud.google.com/artifact-registry),
  spécifiez un nom d'image complet comme
  `$LOCATION-docker.pkg.dev/$PROJECT/$REPO/$STORAGE_IMAGE`, pas seulement un
  référentiel. Par exemple,  ```shell
  $ export COSIGN_REPOSITORY=us-docker.pkg.dev/my-new-repo/demo
  $ cosign sign --key cosign.key $IMAGE_URI_DIGEST

Les clés publiques sont stockées sur disque au format PKIX standard encodé en PEM avec un en-tête de `PUBLIC KEY`.```
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELigCnlLNKgOglRTx1D7JhI7eRw99
QolE9Jo4QUxnbMy5nUuBL+UZF9qqfm/Dg1BNeHRThHzWh2ki9vAEgWEDOw==
-----END PUBLIC KEY-----

Maintenant, signez-le ! En utilisant `cosign` bien sûr :```shell
$ cosign sign --key cosign.key us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact@sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef
Enter password for private key:
Pushing signature to: us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact:sha256-551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef.sig

## FAQ

### Pourquoi ne pas utiliser Notary v2

Il est difficile de répondre brièvement.
Ce post contient quelques comparaisons :

[Notary V2 et Cosign](https://medium.com/@dlorenc/notary-v2-and-cosign-b816658f044d)

Si vous trouvez d'autres posts de comparaison, envoyez une PR ici et nous les listerons tous.

### Pourquoi ne pas utiliser la signature de containers/image

La signature de `containers/image` est proche de `cosign`, et nous réutilisons les formats de payload.
`cosign` diffère en ce qu'il signe avec des clés ECDSA-P256 au lieu de PGP, et stocke
les signatures dans le registre.

### Pourquoi ne pas utiliser TUF ?

Je crois que cet outil est complémentaire à TUF, et ils peuvent être utilisés ensemble.
Je n'ai pas encore essayé, mais je pense que nous pouvons aussi réutiliser un registre pour le stockage TUF.

## Exigences de conception

* Aucun service externe pour le stockage, l'interrogation ou la récupération des signatures
* Nous visons un support de registre aussi large que possible
* Tout doit fonctionner via l'API du registre
* PGP ne devrait pas être requis du tout.
* Les utilisateurs doivent pouvoir trouver toutes les signatures d'une image
* Les signataires peuvent signer une image après le push
* Plusieurs entités peuvent signer une image
* Signer une image ne modifie pas l'image
* Implémentation en pur Go

## Idées futures

### Modifications de l'API du registre

Les conventions de nommage et les modèles de mise à jour en lecture-modification-écriture que nous utilisons pour stocker des choses dans
un registre sont un peu, disons, « bricolés ».
Je pense que c'est la meilleure (seule) option réelle disponible aujourd'hui, mais si l'API du registre
change, nous pouvons améliorer tout cela.

### Autres types

`cosign` peut signer n'importe quoi dans un registre.
Ces exemples montrent la signature d'une seule image, mais vous pourriez aussi signer un `Index` multi-plateformes,
ou tout autre type d'artefact.
Cela inclut les Helm Charts, les Tekton Pipelines, et tout ce qui utilise actuellement les registres OCI
pour la distribution.

Cela signifie aussi que de nouveaux types d'artefacts peuvent être téléchargés vers un registre et signés.
Un type intéressant à stocker et à signer serait les dépôts TUF.
Je n'ai pas encore essayé, mais je suis assez certain que TUF pourrait être implémenté par-dessus.

### Signature de tags

Les signatures `cosign` protègent les digest des objets stockés dans un registre.
Le support optionnel des `annotations` (via le flag `-a` de `cosign sign`) peut être utilisé pour ajouter des données
supplémentaires au payload qui est signé et protégé par la signature.
Un cas d'usage pourrait être de signer un mappage tag->digest.

Si vous souhaitez attester qu'un tag spécifique (ou un ensemble de tags) doit pointer vers un digest, vous pouvez
exécuter quelque chose comme :```shell
$ docker push $IMAGE_URI
The push refers to repository [dlorenc/demo]
994393dc58e7: Pushed
5m: digest: sha256:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870 size: 528
$ TAG=sign-me
$ cosign sign --key cosign.key -a tag=$TAG $IMAGE_URI_DIGEST
Enter password for private key:
Pushing signature to: dlorenc/demo:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870.sig

Les horodatages pourraient également être ajoutés ici, pour implémenter la prévention des attaques de gel de type TUF.

### Signature de l'image de base / des couches

Encore une fois, `cosign` peut signer n'importe quoi dans un registre.
Vous pourriez utiliser `cosign` pour signer une image destinée à être utilisée comme image de base,
et inclure ces métadonnées de provenance dans les images dérivées résultantes.
Cela pourrait être utilisé pour garantir qu'une image a été construite à partir d'une image de base autorisée.

Idée sommaire :
* Les manifests OCI ont une liste ordonnée de `Descriptors` de `layer`, qui peuvent contenir des annotations.
  Voir [ici](https://github.com/opencontainers/image-spec/blob/master/manifest.md) pour la
  spécification.
* Une image de base est une liste ordonnée de couches auxquelles d'autres couches sont ajoutées, ainsi qu'un
  objet de configuration initial qui est muté.
  * Une image dérivée est libre de supprimer/détruire/recréer complètement la config à partir de son image de base,
    donc signer la config n'offrirait qu'une valeur limitée.
* Nous pouvons signer l'ensemble complet des couches de base ordonnées, et attacher cette signature comme annotation à
  la **dernière** couche de l'image enfant résultante.

Cet exemple de manifest manifest représente une image qui a été construite à partir d'une image de base avec deux
couches.
Une couche supplémentaire est ajoutée, formant l'image finale.```json
{
  "schemaVersion": 2,
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "size": 7023,
    "digest": "sha256:b5b2b2c507a0944348e0303114d8d93aaaa081732b86451d9bce1f432a537bc7"
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "size": 32654,
      "digest": "sha256:9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0"
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "size": 16724,
      "digest": "sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b",
      "annotations": {
        "dev.cosign.signature.baseimage": "Ejy6ipGJjUzMDoQFePWixqPBYF0iSnIvpMWps3mlcYNSEcRRZelL7GzimKXaMjxfhy5bshNGvDT5QoUJ0tqUAg=="
      }
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "size": 73109,
      "digest": "sha256:ec4b8955958665577945c89419d1af06b5f7636b4ac3da7f12184802ad867736"
    }
  ],
}

<!-- TODO: https://github.com/sigstore/cosign/issues/2333 -->

Donnez maintenant à cette signature un nom mémorable, puis signez-la :```shell
$ crane tag $(cosign triangulate $IMAGE_URI) mysignature
2021/02/15 20:22:55 dlorenc/demo:mysignature: digest: sha256:71f70e5d29bde87f988740665257c35b1c6f52dafa20fab4ba16b3b1f4c6ba0e size: 556
$ cosign sign --key cosign.key -a sig=counter dlorenc/demo:mysignature
Enter password for private key:
Pushing signature to: dlorenc/demo:sha256-71f70e5d29bde87f988740665257c35b1c6f52dafa20fab4ba16b3b1f4c6ba0e.sig
$ cosign verify --key cosign.pub dlorenc/demo:mysignature
{"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"71f70e5d29bde87f988740665257c35b1c6f52dafa20fab4ba16b3b1f4c6ba0e"},"Type":"cosign container image signature"},"Optional":{"sig":"counter"}}

## Release Cadence

Nous publions des versions selon les besoins. Les versions correctives sont publiées pour corriger de petits bogues. Les versions mineures sont
publiées périodiquement lorsque plusieurs bogues sont corrigés ou des fonctionnalités ajoutées. Les versions majeures
seront publiées lorsqu'il y a des changements cassants.

## Sécurité

Si vous découvrez des problèmes de sécurité, veuillez vous référer au [processus de
sécurité](https://github.com/sigstore/.github/blob/main/SECURITY.md) de sigstore.

## Fichiers de bundle dans les artefacts de publication GitHub

Les artefacts de publication GitHub pour `cosign` contiennent des fichiers de bundle Sigstore produits par [GoReleaser](https://github.com/sigstore/cosign/blob/ac999344eb381ae91455b0a9c5c267e747608d76/.goreleaser.yml#L166) lors de la signature du blob cosign qui est utilisé pour vérifier l'intégrité des binaires de publication. Ce fichier n'est pas utilisé par cosign lui-même, mais est fourni aux utilisateurs qui souhaitent [vérifier l'intégrité des binaires de publication](https://docs.sigstore.dev/cosign/system_config/installation/#verifying-cosign-with-artifact-key).