sigstore/cosignFirma de código y transparencia para contenedores y binarios
<p align="center">
<img style="max-width: 100%;width: 300px;" src="https://raw.githubusercontent.com/sigstore/community/main/artwork/cosign/horizontal/color/sigstore_cosign-horizontal-color.svg" alt="Cosign logo"/>
</p>
# cosign
¡Firma de contenedores OCI (y otros artefactos) usando [Sigstore](https://sigstore.dev/)!
[](https://goreportcard.com/report/github.com/sigstore/cosign)
[](https://github.com/sigstore/cosign/actions/workflows/e2e-tests.yml)
[](https://bestpractices.coreinfrastructure.org/projects/5715)
[](https://securityscorecards.dev/viewer/?uri=github.com/sigstore/cosign)
Cosign tiene como objetivo hacer que las firmas sean **infraestructura invisible**.
Cosign soporta:
* "Firma sin clave" con la autoridad certificadora Fulcio de bien público de Sigstore y el registro de transparencia Rekor (por defecto)
* Firma con hardware y KMS
* Firma con un par de claves privada/pública cifrado generado por cosign
* Firma, verificación y almacenamiento de contenedores en un registro OCI.
* Trae tu propia PKI
## Información
`Cosign` se desarrolla como parte del proyecto [`sigstore`](https://sigstore.dev).
¡También usamos un [canal de slack](https://sigstore.slack.com)!
Haz clic [aquí](https://join.slack.com/t/sigstore/shared_invite/zt-47srvpyn6-j8Ek5hGBwKN32IjLw8BvYA) para el enlace de invitación.
## Instalación
Para instalaciones con Homebrew, Arch, Nix, GitHub Action y Kubernetes, consulta la [documentación de instalación](https://docs.sigstore.dev/cosign/system_config/installation/).
Para binarios de Linux, macOS y Windows, consulta los [recursos de la versión de GitHub](https://github.com/sigstore/cosign/releases/latest).
:rotating_light: Si estás descargando versiones de cosign desde nuestro bucket de GCS, consulta más información en el [aviso de descontinuación](https://blog.sigstore.dev/cosign-releases-bucket-deprecation/) del 31 de julio de 2023 :rotating_light:
## Instalación para desarrolladores
Si tienes Go 1.22+, puedes configurar un entorno de desarrollo:
```shell
$ git clone https://github.com/sigstore/cosign
$ cd cosign
$ go install ./cmd/cosign
$ $(go env GOPATH)/bin/cosign
```
## Contribuir
Si estás interesado en contribuir a `cosign`, por favor lee la [documentación de contribución](https://github.com/sigstore/cosign/blob/main/CONTRIBUTING.md).
El desarrollo futuro de Cosign se centrará en la próxima versión principal, que estará basada en
[sigstore-go](https://github.com/sigstore/sigstore-go). Los mantenedores se centrarán en el desarrollo de funcionalidades dentro de
sigstore-go. Las contribuciones a sigstore-go, especialmente en torno a claves propias y firma, son bienvenidas.
Por favor, consulta el [issue tracker](https://github.com/sigstore/sigstore-go/issues) para encontrar buenos primeros issues.
Cosign 2.x es una versión estable y seguirá recibiendo actualizaciones periódicas de funcionalidades y correcciones de errores. Los PRs
que sean pequeños en alcance y tamaño son los más propensos a ser revisados rápidamente.
Los PRs que modifiquen o rompan significativamente la API no serán aceptados. Los PRs que sean significativos en tamaño pero que no
introduzcan cambios disruptivos pueden ser aceptados, pero se considerarán de menor prioridad que los PRs en sigstore-go.
## Dockerfile
Aquí se muestra cómo instalar y usar cosign dentro de un Dockerfile a través de la imagen ghcr.io/sigstore/cosign/cosign:
```shell
FROM ghcr.io/sigstore/cosign/cosign:v2.4.1 as cosign-bin
# Source: https://github.com/chainguard-images/images/tree/main/images/static
FROM cgr.dev/chainguard/static:latest
COPY --from=cosign-bin /ko-app/cosign /usr/local/bin/cosign
ENTRYPOINT [ "cosign" ]
```
## Inicio rápido
Esto muestra cómo:
* firmar una imagen de contenedor con el método predeterminado de "firma sin clave" basado en identidad (consulta [la documentación para más información](https://docs.sigstore.dev/cosign/signing/overview/))
* verificar la imagen de contenedor
* explorar flujos más amplios de firma/verificación de blobs sin clave en la [Guía de inicio rápido de Sigstore Cosign](https://docs.sigstore.dev/quickstart/quickstart-cosign/)
### Firmar un contenedor y almacenar la firma en el registro
Ten en cuenta que siempre debes firmar imágenes basándote en su digest (`@sha256:...`)
en lugar de una etiqueta (`:latest`), ¡porque de lo contrario podrías firmar algo que no
pretendías firmar!
```shell
cosign sign $IMAGE
Generating ephemeral keys...
Retrieving signed certificate...
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.
By typing 'y', you attest that you grant (or have permission to grant) and agree to have this information stored permanently in transparency logs.
Are you sure you would like to continue? [y/N] y
Your browser will now be opened to:
https://oauth2.sigstore.dev/auth/auth?access_type=online&client_id=sigstore&code_challenge=OrXitVKUZm2lEWHVt1oQWR4HZvn0rSlKhLcltglYxCY&code_challenge_method=S256&nonce=2KvOWeTFxYfxyzHtssvlIXmY6Jk&redirect_uri=http%3A%2F%2Flocalhost%3A57102%2Fauth%2Fcallback&response_type=code&scope=openid+email&state=2KvOWfbQJ1caqScgjwibzK2qJmb
Successfully verified SCT...
tlog entry created with index: 12086900
Pushing signature to: $IMAGE
```
Cosign te pedirá que te autentiques mediante OIDC, donde iniciarás sesión con tu dirección de correo electrónico.
Internamente, cosign solicitará un certificado de firma de código a la autoridad de certificación Fulcio.
El sujeto del certificado coincidirá con la dirección de correo electrónico con la que iniciaste sesión.
Cosign almacenará entonces la firma y el certificado en el registro de transparencia Rekor, y subirá la firma al registro OCI junto con la imagen que estás firmando.
### Verificar un contenedor
Para verificar la imagen, deberás proporcionar el sujeto del certificado esperado y el emisor del certificado mediante los flags `--certificate-identity` y `--certificate-oidc-issuer`:
```
cosign verify $IMAGE --certificate-identity=$IDENTITY --certificate-oidc-issuer=$OIDC_ISSUER
```
También puedes pasar una expresión regular para los flags de identidad del certificado y del emisor, `--certificate-identity-regexp` y `--certificate-oidc-issuer-regexp`.
### Verificar un contenedor contra una clave pública
Este comando devuelve `0` si se encuentra *al menos una* firma con formato `cosign` para la imagen
que coincida con la clave pública.
Consulta el uso detallado a continuación para obtener información y advertencias sobre otros formatos de firma.
Cualquier payload válido se imprime en stdout, en formato json.
Ten en cuenta que estos payloads firmados incluyen el digest de la imagen del contenedor, que es como podemos estar
seguros de que estas firmas "separadas" cubren la imagen correcta.
```shell
$ cosign verify --key cosign.pub $IMAGE_URI:1h
The following checks were performed on these signatures:
- The cosign claims were validated
- The signatures were verified against the specified public key
{"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"sha256:87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8"},"Type":"cosign container image signature"},"Optional":null}
```
### Verificar un contenedor en un entorno aislado
**Nota:** Esta sección está desactualizada.
**Nota:** La mayoría de los flujos de trabajo de verificación requieren solicitar periódicamente claves de servicio a un repositorio TUF.
Para la verificación aislada de firmas utilizando la instancia de bien público, necesitará recuperar el
archivo [trusted root](https://github.com/sigstore/root-signing/blob/main/targets/trusted_root.json) del repositorio
TUF de producción. El contenido de este archivo cambiará sin previo aviso. Al no utilizar TUF, necesitará
construir su propio mecanismo para mantener actualizada su copia aislada de este archivo.
Cosign puede realizar una verificación completamente sin conexión verificando un [bundle](https://github.com/sigstore/cosign/blob/main/specs/SIGNATURE_SPEC.md#properties) que normalmente se distribuye como una anotación en el manifiesto de la imagen.
Siempre que esta anotación esté presente, se puede realizar la verificación sin conexión.
Esta anotación de bundle siempre se incluye por defecto para la firma sin clave, por lo que la funcionalidad predeterminada de `cosign sign` incluirá todos los materiales necesarios para la verificación sin conexión.
Para verificar una imagen en un entorno aislado, la imagen y las firmas deben estar disponibles localmente en el sistema de archivos.
Una imagen se puede guardar localmente usando `cosign save` (nota: este paso debe realizarse con una conexión de red):
```
cosign initialize # This will pull in the latest TUF root
cosign save $IMAGE_NAME --dir ./path/to/dir
```
Ahora, en un entorno aislado de la red, esta imagen local puede verificarse:
```shell
cosign verify \
--certificate-identity $CERT_IDENTITY \
--certificate-oidc-issuer $CERT_OIDC_ISSUER \
--offline=true \
--new-bundle-format=false \ # for artifacts signed without the new protobuf bundle format
--trusted-root ~/.sigstore/root/tuf-repo-cdn.sigstore.dev/targets/trusted_root.json \ # default location of trusted root
--local-image ./path/to/dir
```
Necesitarás proporcionar los valores esperados para `$CERT_IDENTITY` y `$CERT_OIDC_ISSUER` para verificar correctamente esta imagen.
Si firmaste con un par de claves, el mismo comando funcionará, asumiendo que el material de la clave pública está presente localmente:
```
cosign verify --key cosign.pub --offline --local-image ./path/to/dir
```
### Firma y verificación de blobs basadas en identidad
Utilice la firma de blobs sin clave (`cosign sign-blob` sin `--key`) y verifique contra la identidad del firmante esperada:
```shell
$ cosign sign-blob artifact --bundle artifact.sigstore.json --yes
$ cosign verify-blob artifact \
--bundle artifact.sigstore.json \
--certificate-identity "https://github.com/ORG/REPO/.github/workflows/release.yml@refs/heads/main" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"
```
### Solución de problemas
Si encuentras problemas con Cosign, primero asegúrate de que estás utilizando una versión reciente: El proyecto Cosign admite activamente la versión más reciente, así como la última versión de la serie v2.
#### Problemas comunes y soluciones
1. La verificación falla con `failed to verify timestamps: threshold not met for verified log entry integrated timestamps: 0 < 1`: Es posible que estés verificando una firma que requiere compatibilidad con marcas de tiempo RFC3161
* Actualiza a la versión más reciente de Cosign o
* Con Cosign 2.6.x, usa `--use-signed-timestamps`
1. La verificación falla con `no signatures found`: Es posible que estés verificando una firma de imagen que requiere compatibilidad con el registro de transparencia Rekor v2
* Actualiza a la versión más reciente de Cosign
1. La firma falla con errores HTTP: La firma con Cosign depende de múltiples servicios de Sigstore. Reintentar tras un fallo puede ser una solución útil si alguno de estos servicios falla -- también se agradece reportar problemas para fallos específicos
#### Mi problema es otro
Por favor, abre un [issue](https://github.com/sigstore/cosign/issues/new/choose) o pregunta en el [canal de slack](#info).
## Trabajar con otros artefactos
¡Los registros OCI son útiles para almacenar más que solo imágenes de contenedores!
`Cosign` también incluye algunas utilidades para publicar artefactos genéricos, incluidos binarios, scripts y archivos de configuración usando el protocolo OCI.
Esta sección muestra cómo aprovechar estos para un sistema de distribución de artefactos fácil de usar y compatible con versiones anteriores que se integra bien con el resto de Sigstore.
Consulta [la documentación](https://docs.sigstore.dev/cosign/signing/other_types/) para más información.
### Blobs
Puedes publicar un artefacto con `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
```
Tus usuarios pueden descargarlo desde la url "direct" con herramientas estándar como curl o wget:
```shell
$ curl -L ttl.sh/v2/$BLOB_NAME/blobs/sha256:$BLOB_SUM > artifact-fetched
```
El digest está integrado directamente en la URL, así que también pueden verificarlo:
```shell
$ cat artifact-fetched | shasum -a 256
c69d72c98b55258f9026f984e4656f0e9fd3ef024ea3fac1d7e5c7e6249f1626 -
```
Puedes firmarlo con el comando y los flags habituales de `cosign sign`:
```shell
$ cosign sign --key cosign.key $BLOB_URI_DIGEST
Enter password for private key:
Pushing signature to: ttl.sh/my-artifact-f42c22e0
```
Como siempre, ¡asegúrate de referenciar cualquier imagen que firmes por su digest para asegurarte de no firmar la cosa equivocada!
#### Tekton Bundles
Los bundles de [Tekton](https://tekton.dev) se pueden subir y gestionar dentro de un registro OCI.
La especificación está [aquí](https://tekton.dev/docs/pipelines/tekton-bundle-contracts/).
Esto significa que también se pueden firmar y verificar con `cosign`.
Actualmente, los Tekton Bundles se pueden subir con la [tkn cli](https://github.com/tektoncd/cli), pero es posible que añadamos este soporte a
`cosign` en el futuro.
```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
```
#### WASM
Los módulos de Web Assembly también se pueden almacenar en un registro OCI, utilizando esta [especificación](https://github.com/solo-io/wasm/tree/master/spec).
Cosign puede subirlos utilizando el comando `cosign wasm upload`:
```shell
$ cosign upload wasm -f hello.wasm us.gcr.io/dlorenc-vmtest2/wasm
$ cosign sign --key cosign.key us.gcr.io/dlorenc-vmtest2/wasm@sha256:9e7a511fb3130ee4641baf1adc0400bed674d4afc3f1b81bb581c3c8f613f812
Enter password for private key:
tlog entry created with index: 5198
Pushing signature to: us.gcr.io/dlorenc-vmtest2/wasm:sha256-9e7a511fb3130ee4641baf1adc0400bed674d4afc3f1b81bb581c3c8f613f812.sig
```
#### eBPF
Los módulos de [eBPF](https://ebpf.io) también se pueden almacenar en un registro OCI, utilizando esta [especificación](https://github.com/solo-io/bumblebee/tree/main/spec).
La imagen a continuación se construyó utilizando la herramienta `bee`. Se puede encontrar más información [aquí](https://github.com/solo-io/bumblebee/)
Cosign puede entonces firmar estas imágenes como cualquier otra imagen 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}]
```
#### Atestaciones In-Toto
Cosign también tiene soporte integrado para atestaciones de [in-toto](https://in-toto.io).
La especificación para estas se define [aquí](https://github.com/in-toto/attestation).
Puedes crear y firmar una a partir de un archivo de predicado local usando los siguientes comandos:
```shell
$ cosign attest --predicate <file> --key cosign.key $IMAGE_URI_DIGEST
```
Se admiten todos los sistemas de gestión de claves estándar.
Las cargas útiles se firman utilizando la especificación de firma DSSE, definida [aquí](https://github.com/secure-systems-lab/dsse).
Para verificar:
```shell
$ cosign verify-attestation --key cosign.pub $IMAGE_URI
```
## Uso detallado
Consulte la [documentación de uso](https://docs.sigstore.dev/cosign/signing/overview/) para obtener más información.
## Tokens basados en hardware
Consulte la [documentación de tokens de hardware](https://docs.sigstore.dev/cosign/key_management/hardware-based-tokens/) para obtener información sobre cómo usar `cosign` con hardware.
## Compatibilidad con registros
`cosign` utiliza [go-containerregistry](https://github.com/google/go-containerregistry) para las interacciones con registros, que por lo general tiene una excelente compatibilidad, pero algunos registros pueden tener particularidades.
Actualmente, `cosign` ha sido probado y funciona con los siguientes registros:
* AWS Elastic Container Registry
* GCP's Artifact Registry and Container Registry
* Docker Hub
* Azure Container Registry
* JFrog Artifactory Container Registry
* The CNCF distribution/distribution Registry
* GitLab Container Registry
* GitHub Container Registry
* The CNCF Harbor Registry
* Digital Ocean Container Registry
* Sonatype Nexus Container Registry
* Alibaba Cloud Container Registry
* Red Hat Quay Container Registry 3.6+ / Red Hat quay.io
* Elastic Container Registry
* IBM Cloud Container Registry
* Cloudsmith Container Registry
* The CNCF zot Registry
* OVHcloud Managed Private Registry
Nuestro objetivo es lograr una amplia compatibilidad con registros. Para `sign` imágenes en registros que aún no admiten completamente los [tipos de medios OCI](https://github.com/sigstore/cosign/blob/main/specs/SIGNATURE_SPEC.md), es posible que se deba usar `COSIGN_DOCKER_MEDIA_TYPES` para recurrir a equivalentes heredados. Por ejemplo:
```shell
COSIGN_DOCKER_MEDIA_TYPES=1 cosign sign --key cosign.key legacy-registry.example.com/my/image@$DIGEST
```
¡Por favor, ayuda a probar y reportar errores si ves problemas!
Las instrucciones se pueden encontrar en el [issue de seguimiento](https://github.com/sigstore/cosign/issues/40).
## Advertencias
### Funcionalidades intencionalmente ausentes
`cosign` solo genera claves ECDSA-P256 y utiliza hashes SHA256, tanto para la firma efímera sin clave como para la firma con clave gestionada.
Las claves se almacenan en formato PKCS8 codificado en PEM.
Sin embargo, puedes usar `cosign` para almacenar y recuperar firmas en cualquier formato, de cualquier algoritmo.
### Cosas que probablemente deberían cambiar
#### Formatos de payload
`cosign` solo admite el formato [simple signing](https://www.redhat.com/en/blog/container-image-signing) de Red Hat para los payloads.
Que tiene este aspecto:
```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
}
}
```
**Nota:** Esto se puede generar para una referencia de imagen usando `cosign generate $IMAGE_URI_DIGEST`.
Estoy dispuesto a cambiar este formato por otro si tiene sentido.
Consulte https://github.com/notaryproject/notation/issues/40 para ver una opción.
#### Detalles del registro
Las firmas de `cosign` se almacenan como objetos separados en el registro OCI, con solo una referencia débil
hacia el objeto que "firman".
Esto significa que esta relación es opaca para el registro, y las firmas *no* se eliminarán
ni se recolectarán como basura cuando se elimine la imagen.
De manera similar, **pueden** copiarse fácilmente de un entorno a otro, pero esto no es
automático.
Las múltiples firmas se almacenan en una lista que, desafortunadamente, hoy en día es una condición de carrera.
Para agregar una firma, los clientes orquestan una operación de "lectura-anexado-escritura", por lo que la última escritura
ganará en caso de contención.
##### Especificación del registro
`cosign` almacenará las firmas por defecto en el mismo repositorio que la imagen que está firmando.
Para especificar un repositorio diferente para las firmas, puede establecer la variable de entorno `COSIGN_REPOSITORY`.
Esto reemplazará el repositorio en la imagen proporcionada de esta manera:
```shell
$ export COSIGN_REPOSITORY=gcr.io/my-new-repo
$ cosign sign --key cosign.key $IMAGE_URI_DIGEST
```
Así, la firma de `gcr.io/dlorenc-vmtest2/demo` se almacenará en `gcr.io/my-new-repo/demo:sha256-DIGEST.sig`.
Nota: diferentes registros pueden esperar diferentes formatos para el "repositorio".
* Para usar [GCR](https://cloud.google.com/container-registry), un nombre de registro
como `gcr.io/$REPO` es suficiente, como en el ejemplo anterior.
* Para usar [Artifact Registry](https://cloud.google.com/artifact-registry),
especifique un nombre de imagen completo como
`$LOCATION-docker.pkg.dev/$PROJECT/$REPO/$STORAGE_IMAGE`, no solo un
repositorio. Por ejemplo,
```shell
$ export COSIGN_REPOSITORY=us-docker.pkg.dev/my-new-repo/demo
$ cosign sign --key cosign.key $IMAGE_URI_DIGEST
```
donde el `sha256-DIGEST` coincidirá con el digest para
`gcr.io/dlorenc-vmtest2/demo`. Especificar solo un repositorio como
`$LOCATION-docker.pkg.dev/$PROJECT/$REPO` no funcionará en Artifact Registry.
## Especificación de firma
`cosign` está inspirado en herramientas como [minisign](https://jedisct1.github.io/minisign/) y
[signify](https://www.openbsd.org/papers/bsdcan-signify.html).
Las claves privadas generadas se almacenan en formato PEM.
Las claves se cifran con una contraseña usando scrypt como KDF y nacl/secretbox para el cifrado.
Tienen un encabezado PEM de `ENCRYPTED SIGSTORE PRIVATE KEY`:
```shell
-----BEGIN ENCRYPTED SIGSTORE PRIVATE KEY-----
...
-----END ENCRYPTED SIGSTORE PRIVATE KEY-----
```
Las claves públicas se almacenan en disco en formato PKIX estándar codificado en PEM con una cabecera de `PUBLIC KEY`.
```
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELigCnlLNKgOglRTx1D7JhI7eRw99
QolE9Jo4QUxnbMy5nUuBL+UZF9qqfm/Dg1BNeHRThHzWh2ki9vAEgWEDOw==
-----END PUBLIC KEY-----
```
## Especificación de almacenamiento
`cosign` almacena las firmas en un registro OCI y utiliza una convención de nomenclatura (etiqueta basada
en el sha256 de lo que estamos firmando) para localizar el índice de firmas.
<p align="center">
<img src="https://raw.githubusercontent.com/sigstore/cosign/HEAD/images/signatures.dot.svg" />
</p>
`reg.example.com/ubuntu@sha256:703218c0465075f4425e58fac086e09e1de5c340b12976ab9eb8ad26615c3715` tiene las firmas ubicadas en `reg.example.com/ubuntu:sha256-703218c0465075f4425e58fac086e09e1de5c340b12976ab9eb8ad26615c3715.sig`
A grandes rasgos (ignorando los puertos en el nombre del host): `s/:/-/g` y `s/@/:/g` para encontrar el índice de firmas.
Consulta [Condiciones de carrera](#registry-details) para algunas advertencias sobre esta estrategia.
Implementaciones alternativas podrían usar registros de transparencia, el sistema de archivos local, un registro
de repositorio separado, una referencia explícita a un índice de firmas, una nueva API de registro, grafeas, etc.
### Sujetos de firma
`cosign` solo funciona hoy en día para artefactos almacenados como "manifiestos" en el registro.
El mecanismo propuesto es lo suficientemente flexible como para soportar la firma de elementos arbitrarios.
### Soporte de KMS
`cosign` admite el uso de un proveedor de KMS para generar y firmar claves.
Actualmente cosign admite Hashicorp Vault, AWS KMS, GCP KMS, Azure Key Vault, ¡y esperamos admitir más en el futuro!
Hay proveedores de KMS adicionales disponibles como plugins externos, como [OVHcloud KMS](https://github.com/ovh/sigstore-kms-ovhcloud).
Consulta la [documentación de KMS](https://docs.sigstore.dev/cosign/key_management/overview/) para más detalles.
### Artefactos OCI
Sube un artefacto a un registro usando [oras](https://github.com/deislabs/oras) (en este caso, ¡`cosign` mismo!):
```shell
$ oras push us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact ./cosign
Uploading f53604826795 cosign
Pushed us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact
Digest: sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef
```
Ahora fírmalo. Usando `cosign`, por supuesto:
```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
```
Finalmente, verifica `cosign` con `cosign` de nuevo:
```shell
$ cosign verify --key cosign.pub us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact@sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef
The following checks were performed on each of these signatures:
- The cosign claims were validated
- The claims were present in the transparency log
- The signatures were integrated into the transparency log when the certificate was valid
- The signatures were verified against the specified public key
- The code-signing certificate was verified using trusted certificate authority certificates
{"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef"},"Type":"cosign container image signature"},"Optional":null}
```
## FAQ
### ¿Por qué no usar Notary v2?
Es difícil responder esto brevemente.
Esta publicación contiene algunas comparaciones:
[Notary V2 and Cosign](https://medium.com/@dlorenc/notary-v2-and-cosign-b816658f044d)
Si encuentras otras publicaciones de comparación, por favor envía un PR aquí y las enlazaremos todas.
### ¿Por qué no usar la firma de containers/image?
La firma de `containers/image` es similar a `cosign`, y reutilizamos formatos de payload.
`cosign` difiere en que firma con claves ECDSA-P256 en lugar de PGP, y almacena
las firmas en el registro.
### ¿Por qué no usar TUF?
Creo que esta herramienta es complementaria a TUF, y pueden usarse juntas.
Aún no lo he probado, pero creo que también podemos reutilizar un registro para el almacenamiento de TUF.
## Requisitos de diseño
* Sin servicios externos para el almacenamiento, consulta o recuperación de firmas
* Buscamos el mayor soporte de registros posible
* Todo debería funcionar a través de la API del registro
* PGP no debería ser necesario en absoluto.
* Los usuarios deben poder encontrar todas las firmas de una imagen
* Los firmantes pueden firmar una imagen después del push
* Múltiples entidades pueden firmar una imagen
* Firmar una imagen no modifica la imagen
* Implementación en Go puro
## Ideas futuras
### Cambios en la API del registro
La convención de nomenclatura y los patrones de actualización de lectura-modificación-escritura que usamos para almacenar cosas en
un registro son un poco, bueno, "hacky".
Creo que son la mejor (y única) opción real disponible hoy, pero si la API del registro
cambia podemos mejorar esto.
### Otros tipos
`cosign` puede firmar cualquier cosa en un registro.
Estos ejemplos muestran cómo firmar una sola imagen, pero también podrías firmar un `Index` multiplataforma,
o cualquier otro tipo de artefacto.
Esto incluye Helm Charts, Tekton Pipelines y cualquier otra cosa que actualmente use registros OCI
para su distribución.
Esto también significa que se pueden subir nuevos tipos de artefactos a un registro y firmarlos.
Un tipo interesante para almacenar y firmar serían los repositorios TUF.
Aún no lo he probado, pero estoy bastante seguro de que TUF podría implementarse sobre esto.
### Firma de etiquetas
Las firmas de `cosign` protegen los digests de los objetos almacenados en un registro.
El soporte opcional de `annotations` (mediante el flag `-a` de `cosign sign`) se puede usar para añadir
datos extra al payload que se firma y que están protegidos por la firma.
Un caso de uso para esto podría ser firmar un mapeo tag->digest.
Si deseas atestiguar que una etiqueta específica (o un conjunto de etiquetas) debería apuntar a un digest, puedes
ejecutar algo como:
```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
```
Luego puedes verificar que el mapeo tag->digest también está cubierto en la firma, usando el flag `-a` en `cosign verify`.
Este ejemplo verifica que el digest `$TAG` al que apunta (`sha256:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870`)
ha sido firmado, **y también** que la anotación `tag` tiene el valor `sign-me`:
```shell
$ cosign verify --key cosign.pub -a tag=$TAG $IMAGE_URI | jq .
{
"Critical": {
"Identity": {
"docker-reference": ""
},
"Image": {
"Docker-manifest-digest": "97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36"
},
"Type": "cosign container image signature"
},
"Optional": {
"tag": "sign-me"
}
}
```
También se podrían añadir marcas de tiempo aquí, para implementar la prevención de ataques de congelación al estilo TUF.
### Firma de imagen/capa base
De nuevo, `cosign` puede firmar cualquier cosa en un registro.
Podrías usar `cosign` para firmar una imagen que se pretende utilizar como imagen base,
e incluir esos metadatos de procedencia en las imágenes derivadas resultantes.
Esto podría usarse para exigir que una imagen se construyó a partir de una imagen base autorizada.
Idea aproximada:
* Los manifiestos OCI tienen una lista ordenada de `Descriptors` de `layer`, que pueden contener anotaciones.
Consulta [aquí](https://github.com/opencontainers/image-spec/blob/master/manifest.md) para la
especificación.
* Una imagen base es una lista ordenada de capas a las que se añaden otras capas, así como un
objeto de configuración inicial que se modifica.
* Una imagen derivada es libre de eliminar/destruir/recrear por completo la configuración de su imagen base,
por lo que firmar la configuración proporcionaría un valor limitado.
* Podemos firmar el conjunto completo de capas base ordenadas, y adjuntar esa firma como una anotación a
la **última** capa en la imagen hija resultante.
Este manifiesto de ejemplo representa una imagen que se ha construido a partir de una imagen base con dos
capas.
Se añade una capa adicional, formando la imagen final.
```json
{
```
---
[Read more](https://github.com/sigstore/cosign)