sigstore/cosignAssinatura de código e transparência para contêineres e binários
<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
Assinatura de contêineres OCI (e outros artefatos) 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)
O Cosign tem como objetivo tornar as assinaturas **infraestrutura invisível**.
O Cosign suporta:
* "Assinatura sem chave" com a autoridade certificadora Fulcio de bem público do Sigstore e o log de transparência Rekor (padrão)
* Assinatura com hardware e KMS
* Assinatura com um par de chaves privada/pública criptografado gerado pelo cosign
* Assinatura, Verificação e Armazenamento de Contêineres em um registro OCI.
* Traga sua própria PKI
## Informações
O `Cosign` é desenvolvido como parte do projeto [`sigstore`](https://sigstore.dev).
Também usamos um [canal do slack](https://sigstore.slack.com)!
Clique [aqui](https://join.slack.com/t/sigstore/shared_invite/zt-47srvpyn6-j8Ek5hGBwKN32IjLw8BvYA) para o link de convite.
## Instalação
Para instalações via Homebrew, Arch, Nix, GitHub Action e Kubernetes, consulte a [documentação de instalação](https://docs.sigstore.dev/cosign/system_config/installation/).
Para binários de Linux, macOS e Windows, consulte os [ativos de release do GitHub](https://github.com/sigstore/cosign/releases/latest).
:rotating_light: Se você está baixando releases do cosign do nosso bucket GCS - consulte mais informações no [aviso de descontinuação](https://blog.sigstore.dev/cosign-releases-bucket-deprecation/) de 31 de julho de 2023 :rotating_light:
## Instalação para Desenvolvedores
Se você tem Go 1.22+, pode configurar um ambiente de desenvolvimento:
```shell
$ git clone https://github.com/sigstore/cosign
$ cd cosign
$ go install ./cmd/cosign
$ $(go env GOPATH)/bin/cosign
```
## Contribuindo
Se você tem interesse em contribuir com o `cosign`, por favor leia a [documentação de contribuição](https://github.com/sigstore/cosign/blob/main/CONTRIBUTING.md).
O desenvolvimento futuro do Cosign será focado na próxima versão principal, que será baseada no
[sigstore-go](https://github.com/sigstore/sigstore-go). Os mantenedores estarão focados no desenvolvimento de funcionalidades dentro do
sigstore-go. Contribuições para o sigstore-go, particularmente em torno de bring-your-own keys e assinatura, são bem-vindas.
Por favor, consulte o [issue tracker](https://github.com/sigstore/sigstore-go/issues) para boas primeiras issues.
O Cosign 2.x é uma versão estável e continuará recebendo atualizações periódicas de funcionalidades e correções de bugs. PRs
de escopo e tamanho pequenos têm maior probabilidade de serem revisados rapidamente.
PRs que modificam ou quebram significativamente a API não serão aceitos. PRs que são significativos em tamanho mas não
introduzem mudanças que quebram compatibilidade podem ser aceitos, mas serão considerados de prioridade menor do que PRs no sigstore-go.
## Dockerfile
Veja como instalar e usar o cosign dentro de um Dockerfile através da imagem 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" ]
```
## Início Rápido
Isto mostra como:
* assinar uma imagem de contêiner com o método padrão de "assinatura sem chave" baseado em identidade (consulte [a documentação para mais informações](https://docs.sigstore.dev/cosign/signing/overview/))
* verificar a imagem de contêiner
* explorar fluxos mais amplos de assinatura/verificação de blobs sem chave no [Sigstore Cosign Quickstart](https://docs.sigstore.dev/quickstart/quickstart-cosign/)
### Assinar um contêiner e armazenar a assinatura no registro
Observe que você deve sempre assinar imagens com base em seu digest (`@sha256:...`)
em vez de uma tag (`:latest`), pois caso contrário você pode assinar algo que
não pretendia!
```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
```
O Cosign solicitará que você se autentique via OIDC, onde você fará login com seu endereço de e-mail.
Nos bastidores, o cosign solicitará um certificado de assinatura de código à autoridade certificadora Fulcio.
O titular do certificado corresponderá ao endereço de e-mail com o qual você fez login.
O Cosign então armazenará a assinatura e o certificado no log de transparência Rekor, e enviará a assinatura para o registro OCI junto com a imagem que você está assinando.
### Verificar um contêiner
Para verificar a imagem, você precisará informar o titular esperado do certificado e o emissor do certificado através das flags `--certificate-identity` e `--certificate-oidc-issuer`:
```
cosign verify $IMAGE --certificate-identity=$IDENTITY --certificate-oidc-issuer=$OIDC_ISSUER
```
Você também pode passar uma regex para as flags de identidade do certificado e emissor, `--certificate-identity-regexp` e `--certificate-oidc-issuer-regexp`.
### Verificar um container em relação a uma chave pública
Este comando retorna `0` se *pelo menos uma* assinatura formatada pelo `cosign` para a imagem for encontrada
correspondendo à chave pública.
Consulte o uso detalhado abaixo para obter informações e ressalvas sobre outros formatos de assinatura.
Quaisquer payloads válidos são impressos em stdout, no formato json.
Observe que esses payloads assinados incluem o digest da imagem do container, que é como podemos ter
certeza de que essas assinaturas "desanexadas" cobrem a imagem correta.
```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 um contêiner em um ambiente isolado (air-gapped)
**Nota:** Esta seção está desatualizada.
**Nota:** A maioria dos fluxos de trabalho de verificação exige a solicitação periódica de chaves de serviço de um repositório TUF.
Para verificação isolada de assinaturas usando a instância de bem público, você precisará recuperar o
arquivo [trusted root](https://github.com/sigstore/root-signing/blob/main/targets/trusted_root.json) do repositório
TUF de produção. O conteúdo deste arquivo mudará sem notificação. Ao não usar o TUF, você precisará
criar seu próprio mecanismo para manter sua cópia isolada deste arquivo atualizada.
O Cosign pode fazer verificação completamente offline verificando um [bundle](https://github.com/sigstore/cosign/blob/main/specs/SIGNATURE_SPEC.md#properties) que normalmente é distribuído como uma anotação no manifesto da imagem.
Desde que esta anotação esteja presente, a verificação offline pode ser realizada.
Esta anotação de bundle é sempre incluída por padrão para assinatura sem chave (keyless), então a funcionalidade padrão do `cosign sign` incluirá todos os materiais necessários para verificação offline.
Para verificar uma imagem em um ambiente isolado, a imagem e as assinaturas devem estar disponíveis localmente no sistema de arquivos.
Uma imagem pode ser salva localmente usando `cosign save` (observe que esta etapa deve ser feita com uma conexão de rede):
```
cosign initialize # This will pull in the latest TUF root
cosign save $IMAGE_NAME --dir ./path/to/dir
```
Agora, em um ambiente isolado (air-gapped), esta imagem local pode ser verificada:
```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
```
Você precisará passar os valores esperados para `$CERT_IDENTITY` e `$CERT_OIDC_ISSUER` para verificar corretamente esta imagem.
Se você assinou com um par de chaves, o mesmo comando funcionará, assumindo que o material da chave pública esteja presente localmente:
```
cosign verify --key cosign.pub --offline --local-image ./path/to/dir
```
### Assinatura e verificação de blob baseadas em identidade
Use a assinatura de blob sem chave (`cosign sign-blob` sem `--key`) e verifique em relação à identidade do signatário 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"
```
### Solução de problemas
Se você encontrar problemas com o Cosign, primeiro certifique-se de que está usando uma versão recente: O projeto Cosign oferece suporte ativo à versão mais recente, bem como à última versão da série v2.
#### Problemas comuns e soluções
1. A verificação falha com `failed to verify timestamps: threshold not met for verified log entry integrated timestamps: 0 < 1`: Você pode estar verificando uma assinatura que requer suporte a timestamp RFC3161
* Atualize para a versão mais recente do Cosign ou
* Com o Cosign 2.6.x, use `--use-signed-timestamps`
1. A verificação falha com `no signatures found`: Você pode estar verificando uma assinatura de imagem que requer suporte ao log de transparência Rekor v2
* Atualize para a versão mais recente do Cosign
1. A assinatura falha com erros HTTP: A assinatura com o Cosign depende de vários serviços do Sigstore. Tentar novamente em caso de falha pode ser uma solução alternativa útil se algum desses serviços falhar -- abrir issues para falhas específicas também é apreciado
#### Meu problema é outro
Por favor, abra uma [issue](https://github.com/sigstore/cosign/issues/new/choose) ou pergunte no [canal do slack](#info).
## Trabalhando com Outros Artefatos
Os registros OCI são úteis para armazenar mais do que apenas imagens de contêiner!
O `Cosign` também inclui alguns utilitários para publicar artefatos genéricos, incluindo binários, scripts e arquivos de configuração usando o protocolo OCI.
Esta seção mostra como aproveitar esses recursos para um sistema de distribuição de artefatos fácil de usar e retrocompatível que se integra bem com o restante do Sigstore.
Consulte [a documentação](https://docs.sigstore.dev/cosign/signing/other_types/) para mais informações.
### Blobs
Você pode publicar um artefato com `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
```
Seus usuários podem baixá-lo a partir da url "direct" com ferramentas padrão como curl ou wget:
```shell
$ curl -L ttl.sh/v2/$BLOB_NAME/blobs/sha256:$BLOB_SUM > artifact-fetched
```
O digest já está embutido na própria URL, então eles também podem verificar isso:
```shell
$ cat artifact-fetched | shasum -a 256
c69d72c98b55258f9026f984e4656f0e9fd3ef024ea3fac1d7e5c7e6249f1626 -
```
Você pode assiná-lo com o comando e as flags normais do `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 sempre, certifique-se de referenciar qualquer imagem que você assinar pelo seu digest para garantir que você não assine a coisa errada!
#### Tekton Bundles
Os bundles do [Tekton](https://tekton.dev) podem ser enviados e gerenciados dentro de um registro OCI.
A especificação está [aqui](https://tekton.dev/docs/pipelines/tekton-bundle-contracts/).
Isso significa que eles também podem ser assinados e verificados com `cosign`.
Atualmente, os Tekton Bundles podem ser enviados com a [tkn cli](https://github.com/tektoncd/cli), mas podemos adicionar esse suporte ao
`cosign` no 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
Módulos Web Assembly também podem ser armazenados em um registro OCI, usando esta [especificação](https://github.com/solo-io/wasm/tree/master/spec).
O Cosign pode carregá-los usando o 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
Os módulos [eBPF](https://ebpf.io) também podem ser armazenados em um registro OCI, usando esta [especificação](https://github.com/solo-io/bumblebee/tree/main/spec).
A imagem abaixo foi construída usando a ferramenta `bee`. Mais informações podem ser encontradas [aqui](https://github.com/solo-io/bumblebee/)
O Cosign pode então assinar essas imagens como faria com qualquer outra imagem 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}]
```
#### Atestados In-Toto
O Cosign também possui suporte integrado para atestados [in-toto](https://in-toto.io).
A especificação para estes é definida [aqui](https://github.com/in-toto/attestation).
Você pode criar e assinar um a partir de um arquivo de predicado local usando os seguintes comandos:
```shell
$ cosign attest --predicate <file> --key cosign.key $IMAGE_URI_DIGEST
```
Todos os sistemas padrão de gerenciamento de chaves são suportados.
Os payloads são assinados usando a especificação de assinatura DSSE, definida [aqui](https://github.com/secure-systems-lab/dsse).
Para verificar:
```shell
$ cosign verify-attestation --key cosign.pub $IMAGE_URI
```
## Uso Detalhado
Consulte a [documentação de Uso](https://docs.sigstore.dev/cosign/signing/overview/) para mais informações.
## Tokens Baseados em Hardware
Consulte a [documentação de Tokens de Hardware](https://docs.sigstore.dev/cosign/key_management/hardware-based-tokens/) para informações sobre como usar o `cosign` com hardware.
## Suporte a Registries
O `cosign` usa o [go-containerregistry](https://github.com/google/go-containerregistry) para interações com registries, que geralmente tem excelente compatibilidade, mas alguns registries podem ter peculiaridades.
Atualmente, o `cosign` foi testado e funciona com os seguintes registries:
* 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
Nosso objetivo é um amplo suporte a registries. Para `sign` imagens em registries que ainda não suportam totalmente [tipos de mídia OCI](https://github.com/sigstore/cosign/blob/main/specs/SIGNATURE_SPEC.md), pode ser necessário usar `COSIGN_DOCKER_MEDIA_TYPES` para recorrer a equivalentes legados. Por exemplo:
```shell
COSIGN_DOCKER_MEDIA_TYPES=1 cosign sign --key cosign.key legacy-registry.example.com/my/image@$DIGEST
```
Ajude a testar e a registrar bugs se encontrar problemas!
As instruções podem ser encontradas na [issue de acompanhamento](https://github.com/sigstore/cosign/issues/40).
## Ressalvas
### Funcionalidades intencionalmente ausentes
O `cosign` gera apenas chaves ECDSA-P256 e usa hashes SHA256, tanto para assinatura efêmera sem chave quanto para assinatura com chave gerenciada.
As chaves são armazenadas no formato PKCS8 codificado em PEM.
No entanto, você pode usar o `cosign` para armazenar e recuperar assinaturas em qualquer formato, de qualquer algoritmo.
### Coisas que provavelmente deveriam mudar
#### Formatos de payload
O `cosign` suporta apenas o formato [simple signing](https://www.redhat.com/en/blog/container-image-signing) da Red Hat para payloads.
Que se parece com:
```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:** Isto pode ser gerado para uma referência de imagem usando `cosign generate $IMAGE_URI_DIGEST`.
Fico feliz em mudar este formato para outra coisa se fizer sentido.
Veja https://github.com/notaryproject/notation/issues/40 para uma opção.
#### Detalhes do Registry
As assinaturas do `cosign` são armazenadas como objetos separados no registry OCI, com apenas uma referência fraca de volta ao objeto que elas "assinam".
Isto significa que esta relação é opaca para o registry, e as assinaturas *não serão* eliminadas
nem recolhidas pelo garbage collector quando a imagem for eliminada.
Da mesma forma, elas **podem** facilmente ser copiadas de um ambiente para outro, mas isto não é
automático.
Múltiplas assinaturas são armazenadas numa lista que, infelizmente, é hoje uma race condition.
Para adicionar uma assinatura, os clientes orquestram uma operação de "read-append-write", pelo que a última escrita
vencerá em caso de contenção.
##### Especificar o Registry
O `cosign` irá, por defeito, armazenar as assinaturas no mesmo repo que a imagem que está a assinar.
Para especificar um repo diferente para as assinaturas, pode definir a variável de ambiente `COSIGN_REPOSITORY`.
Isto irá substituir o repo na imagem fornecida assim:
```shell
$ export COSIGN_REPOSITORY=gcr.io/my-new-repo
$ cosign sign --key cosign.key $IMAGE_URI_DIGEST
```
Portanto, a assinatura para `gcr.io/dlorenc-vmtest2/demo` será armazenada em `gcr.io/my-new-repo/demo:sha256-DIGEST.sig`.
Nota: registries diferentes podem esperar formatos diferentes para o "repositório".
* Para usar o [GCR](https://cloud.google.com/container-registry), um nome de registry
como `gcr.io/$REPO` é suficiente, como no exemplo acima.
* Para usar o [Artifact Registry](https://cloud.google.com/artifact-registry),
especifique um nome de imagem completo como
`$LOCATION-docker.pkg.dev/$PROJECT/$REPO/$STORAGE_IMAGE`, não apenas um
repositório. Por exemplo,
```shell
$ export COSIGN_REPOSITORY=us-docker.pkg.dev/my-new-repo/demo
$ cosign sign --key cosign.key $IMAGE_URI_DIGEST
```
onde o `sha256-DIGEST` corresponderá ao digest para
`gcr.io/dlorenc-vmtest2/demo`. Especificar apenas um repositório como
`$LOCATION-docker.pkg.dev/$PROJECT/$REPO` não funcionará no Artifact Registry.
## Especificação de Assinatura
O `cosign` é inspirado em ferramentas como [minisign](https://jedisct1.github.io/minisign/) e
[signify](https://www.openbsd.org/papers/bsdcan-signify.html).
As chaves privadas geradas são armazenadas no formato PEM.
As chaves são criptografadas sob uma senha usando scrypt como KDF e nacl/secretbox para criptografia.
Elas possuem um cabeçalho PEM de `ENCRYPTED SIGSTORE PRIVATE KEY`:
```shell
-----BEGIN ENCRYPTED SIGSTORE PRIVATE KEY-----
...
-----END ENCRYPTED SIGSTORE PRIVATE KEY-----
```
As chaves públicas são armazenadas em disco no formato PKIX padrão codificado em PEM com um cabeçalho `PUBLIC KEY`.
```
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELigCnlLNKgOglRTx1D7JhI7eRw99
QolE9Jo4QUxnbMy5nUuBL+UZF9qqfm/Dg1BNeHRThHzWh2ki9vAEgWEDOw==
-----END PUBLIC KEY-----
```
## Especificação de Armazenamento
O `cosign` armazena assinaturas em um registro OCI e usa uma convenção de nomenclatura (tag baseada
no sha256 do que estamos assinando) para localizar o índice de assinatura.
<p align="center">
<img src="https://raw.githubusercontent.com/sigstore/cosign/HEAD/images/signatures.dot.svg" />
</p>
`reg.example.com/ubuntu@sha256:703218c0465075f4425e58fac086e09e1de5c340b12976ab9eb8ad26615c3715` tem assinaturas localizadas em `reg.example.com/ubuntu:sha256-703218c0465075f4425e58fac086e09e1de5c340b12976ab9eb8ad26615c3715.sig`
Aproximadamente (ignorando portas no hostname): `s/:/-/g` e `s/@/:/g` para encontrar o índice de assinatura.
Consulte [Condições de corrida](#registry-details) para algumas ressalvas sobre essa estratégia.
Implementações alternativas poderiam usar logs de transparência, sistema de arquivos local, um registro
de repositório separado, uma referência explícita a um índice de assinatura, uma nova API de registro, grafeas, etc.
### Assinando sujeitos
O `cosign` só funciona para artefatos armazenados como "manifests" no registro atualmente.
O mecanismo proposto é flexível o suficiente para suportar a assinatura de coisas arbitrárias.
### Suporte a KMS
O `cosign` suporta o uso de um provedor KMS para gerar e assinar chaves.
No momento, o cosign suporta Hashicorp Vault, AWS KMS, GCP KMS, Azure Key Vault e esperamos suportar mais no futuro!
Provedores KMS adicionais estão disponíveis como plugins externos, como [OVHcloud KMS](https://github.com/ovh/sigstore-kms-ovhcloud).
Consulte a [documentação do KMS](https://docs.sigstore.dev/cosign/key_management/overview/) para mais detalhes.
### Artefatos OCI
Envie um artefato para um registro usando [oras](https://github.com/deislabs/oras) (neste caso, o próprio `cosign`!):
```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
```
Agora assine-o! Usando `cosign`, é claro:
```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
```
Por fim, verifique o `cosign` com o `cosign` novamente:
```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 que não usar o Notary v2
É difícil responder isso brevemente.
Este post contém algumas comparações:
[Notary V2 and Cosign](https://medium.com/@dlorenc/notary-v2-and-cosign-b816658f044d)
Se você encontrar outros posts de comparação, por favor envie um PR aqui e nós iremos linká-los todos.
### Por que não usar a assinatura do containers/image
A assinatura do `containers/image` é próxima do `cosign`, e nós reutilizamos os formatos de payload.
O `cosign` difere por assinar com chaves ECDSA-P256 em vez de PGP, e armazena
as assinaturas no registry.
### Por que não usar o TUF?
Acredito que esta ferramenta é complementar ao TUF, e eles podem ser usados juntos.
Ainda não tentei, mas acho que também podemos reutilizar um registry para armazenamento do TUF.
## Requisitos de Design
* Nenhum serviço externo para armazenamento, consulta ou recuperação de assinaturas
* Nosso objetivo é o máximo de suporte a registry possível
* Tudo deve funcionar através da API do registry
* PGP não deve ser necessário de forma alguma.
* Os usuários devem ser capazes de encontrar todas as assinaturas de uma imagem
* Os assinantes podem assinar uma imagem após o push
* Múltiplas entidades podem assinar uma imagem
* Assinar uma imagem não modifica a imagem
* Implementação em Go puro
## Ideias Futuras
### Mudanças na API do Registry
A convenção de nomenclatura e os padrões de atualização read-modify-write que usamos para armazenar coisas em
um registry são um pouco, bem, "hacky".
Acho que são a melhor (única) opção real disponível hoje, mas se a API do registry
mudar, podemos melhorar isso.
### Outros Tipos
O `cosign` pode assinar qualquer coisa em um registry.
Estes exemplos mostram a assinatura de uma única imagem, mas você também pode assinar um `Index` multi-plataforma,
ou qualquer outro tipo de artefato.
Isso inclui Helm Charts, Tekton Pipelines, e qualquer outra coisa que atualmente use registries OCI
para distribuição.
Isso também significa que novos tipos de artefatos podem ser enviados para um registry e assinados.
Um tipo interessante para armazenar e assinar seriam os repositórios TUF.
Ainda não tentei, mas estou bastante certo de que o TUF poderia ser implementado em cima disso.
### Assinatura de Tags
As assinaturas do `cosign` protegem os digests dos objetos armazenados em um registry.
O suporte opcional a `annotations` (através da flag `-a` para `cosign sign`) pode ser usado para adicionar dados
extras ao payload que é assinado e protegido pela assinatura.
Um caso de uso para isso pode ser assinar um mapeamento tag->digest.
Se você gostaria de atestar que uma tag específica (ou conjunto de tags) deve apontar para um digest, você pode
executar 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
```
Em seguida, você pode verificar que o mapeamento tag->digest também está coberto na assinatura, usando a flag `-a` para `cosign verify`.
Este exemplo verifica que o digest `$TAG` que aponta para (`sha256:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870`)
foi assinado, **e também** que a anotação `tag` tem o 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"
}
}
```
Timestamps também podem ser adicionados aqui, para implementar a prevenção de ataques de congelamento no estilo TUF.
### Assinatura de Imagem/Camada Base
Novamente, o `cosign` pode assinar qualquer coisa em um registro.
Você pode usar o `cosign` para assinar uma imagem que se destina a ser usada como imagem base,
e incluir esses metadados de proveniência nas imagens derivadas resultantes.
Isso pode ser usado para garantir que uma imagem foi construída a partir de uma imagem base autorizada.
Ideia Geral:
* Os manifestos OCI têm uma lista ordenada de `Descriptors` de `layer`, que podem conter anotações.
Consulte [aqui](https://github.com/opencontainers/image-spec/blob/master/manifest.md) para a
especificação.
* Uma imagem base é uma lista ordenada de camadas às quais outras camadas são anexadas, bem como um
objeto de configuração inicial que é mutado.
* Uma imagem derivada é livre para excluir/destruir/recriar completamente a configuração da sua imagem base,
então assinar a configuração forneceria valor limitado.
* Podemos assinar o conjunto completo de camadas base ordenadas, e anexar essa assinatura como uma anotação à
**última** camada na imagem filha resultante.
Este manifesto de exemplo representa uma imagem que foi construída a partir de uma imagem base com duas
camadas.
Uma camada adicional é adicionada, formando a imagem final.
```json
{
"schemaVersion": 2,
"config": {
"mediaType": "application/vnd.oci.image.config.v1+json",
"size": 7023,
```
---
[Read more](https://github.com/sigstore/cosign)