## Contribuindo

Se você estiver interessado em contribuir com o `cosign`, leia a [documentação de contribuição](https://github.com/sigstore/cosign/blob/HEAD/CONTRIBUTING.md).

O desenvolvimento futuro do Cosign será focado na próxima versão principal, que será baseada em
[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, especialmente em relação a trazer suas próprias chaves e assinatura, são apreciadas.
Por favor, consulte o [rastreador de issues](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
que sejam pequenos em escopo e tamanho têm maior probabilidade de serem revisados rapidamente.

PRs que modifiquem significativamente ou quebrem a API não serão aceitos. PRs que sejam significativos em tamanho, mas que não
introduzam mudanças que quebrem a 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 por meio 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/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.

O Cosign solicitará que você se autentique via OIDC, onde fará login com seu endereço de e-mail.
Nos bastidores, o cosign solicitará um certificado de assinatura de código à autoridade de certificação Fulcio.
O assunto do certificado corresponderá ao endereço de e-mail com o qual você fez login.
O cosign armazenará então a assinatura e o certificado no log de transparência Rekor e enviará a assinatura ao registro OCI juntamente com a imagem que você está assinando.


### Verificar um contêiner

Para verificar a imagem, você precisará informar o assunto do certificado esperado e o emissor do certificado por meio das flags `--certificate-identity` e `--certificate-oidc-issuer`:```
cosign verify $IMAGE --certificate-identity=$IDENTITY --certificate-oidc-issuer=$OIDC_ISSUER

### 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 solicitar periodicamente chaves de serviço a um repositório TUF.
Para verificação offline (airgapped) de assinaturas usando a instância de bem público, será necessário obter 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 aviso prévio. Ao não usar TUF, você precisará
criar seu próprio mecanismo para manter sua cópia offline (airgapped) deste arquivo atualizada.

O Cosign pode fazer verificação completamente offline ao verificar um [bundle](https://github.com/sigstore/cosign/blob/HEAD/specs/SIGNATURE_SPEC.md#properties) que normalmente é distribuído como uma anotação no manifesto da imagem.
Desde que essa anotação esteja presente, a verificação offline pode ser realizada.
Essa anotação de bundle é sempre incluída por padrão para assinatura sem chave (keyless), portanto a funcionalidade padrão de `cosign sign` incluirá todos os materiais necessários para a verificação offline.

Para verificar uma imagem em um ambiente isolado (air-gapped), 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

Você precisará fornecer 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á, desde que o material da chave pública esteja presente localmente:```
cosign verify --key cosign.pub --offline --local-image ./path/to/dir

### Solução de problemas

Se você encontrar problemas com o Cosign, primeiro certifique-se de estar 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 timestamps 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: assinar com o Cosign depende de vários serviços Sigstore. Repetir a operação em caso de falha pode ser uma alternativa útil se algum desses serviços falhar — relatar problemas para falhas específicas também é apreciado

#### Meu problema é outro

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 muito 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 criar um sistema de distribuição de artefatos fácil de usar e com compatibilidade reversa, que se integra bem ao restante do Sigstore.

Consulte [a documentação](https://docs.sigstore.dev/cosign/signing/other_types/) para obter 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

O digest é embutido diretamente na URL, para que possam verificar isso também:```shell
$ cat artifact-fetched | shasum -a 256
c69d72c98b55258f9026f984e4656f0e9fd3ef024ea3fac1d7e5c7e6249f1626  -

Como de costume, certifique-se de referenciar qualquer imagem que você assinar pelo seu digest para não assinar a coisa errada!

#### Tekton Bundles

Os bundles do [Tekton](https://tekton.dev) podem ser enviados e gerenciados em 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 bundles Tekton 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

#### eBPF

[eBPF](https://ebpf.io) módulos 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 pode assinar 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}]

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

Ajude a testar e relate bugs se encontrar problemas!
As instruções podem ser encontradas na [issue de acompanhamento](https://github.com/sigstore/cosign/issues/40).

## Ressalvas

### Recursos Intencionalmente Ausentes

O `cosign` gera apenas chaves ECDSA-P256 e usa hashes SHA256, tanto para assinatura keyless efêmera quanto para assinatura com chave gerenciada.
As chaves são armazenadas em 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 [simple signing](https://www.redhat.com/en/blog/container-image-signing) da Red Hat
para payloads.
Isso 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
    }
}

Portanto, a assinatura para `gcr.io/dlorenc-vmtest2/demo` será armazenada em `gcr.io/my-new-repo/demo:sha256-DIGEST.sig`.

Nota: registros diferentes podem esperar formatos diferentes para o "repositório".

* Para usar o [GCR](https://cloud.google.com/container-registry), um nome de registro
  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

As chaves públicas são armazenadas em disco no formato PKIX padrão codificado em PEM, com um cabeçalho de `PUBLIC KEY`.```
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELigCnlLNKgOglRTx1D7JhI7eRw99
QolE9Jo4QUxnbMy5nUuBL+UZF9qqfm/Dg1BNeHRThHzWh2ki9vAEgWEDOw==
-----END PUBLIC KEY-----

Agora assine! 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

## FAQ

### Por que não usar o Notary v2

É difícil responder isso brevemente.
Este post contém algumas comparações:

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

Se você encontrar outros posts de comparação, envie um PR aqui e vamos linká-los todos.

### Por que não usar a assinatura de imagens do containers/image

A assinatura de `containers/image` é próxima da do `cosign`, e reutilizamos os formatos de payload.
O `cosign` difere por assinar com chaves ECDSA-P256 em vez de PGP, e armazenar
assinaturas no registry.

### Por que não usar TUF?

Acredito que esta ferramenta é complementar ao TUF, e eles podem ser usados em conjunto.
Ainda não tentei, mas acho que também podemos reutilizar um registry para armazenamento do TUF.

## Requisitos de Design

* Sem serviços externos para armazenamento, consulta ou recuperação de assinaturas
* Buscamos o máximo de suporte a registries 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 conseguir encontrar todas as assinaturas de uma imagem
* Os signatários podem assinar uma imagem após o push
* Múltiplas entidades podem assinar uma imagem
* Assinar uma imagem não a modifica
* 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, "improvisadas".
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.
Esses 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 artefato podem ser enviados para um registry e assinados.
Um tipo interessante de se armazenar e assinar seriam os repositórios TUF.
Ainda não tentei, mas estou bastante certo de que TUF poderia ser implementado sobre isso.

### Assinatura de Tags

As assinaturas do `cosign` protegem os digests de objetos armazenados em um registry.
O suporte opcional a `annotations` (através da flag `-a` do `cosign sign`) pode ser usado para adicionar dados
extras ao payload que é assinado e protegido pela assinatura.
Um caso de uso para isso poderia ser assinar um mapeamento tag->digest.

Se você quiser 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

Carimbos de data/hora também poderiam ser adicionados aqui, para implementar a prevenção de ataques de congelamento ao estilo TUF.

### Assinatura de Imagem Base/Camada

Novamente, o `cosign` pode assinar qualquer coisa em um registry.
Você poderia 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 poderia ser usado para garantir que uma imagem foi construída a partir de uma imagem base autorizada.

Ideia geral:
* Manifestos OCI possuem uma lista ordenada de `layer` `Descriptors`, que podem conter anotações.
  Veja [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, além de um
  objeto de configuração inicial que é mutado.
  * Uma imagem derivada é livre para excluir/destruir/recriar completamente a configuração de sua imagem base,
    portanto, 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,
    "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 -->

Agora dê a essa assinatura um nome memorável e assine-a:```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"}}

## Cadência de Lançamentos

Fazemos lançamentos conforme necessário. Lançamentos de correção são feitos para corrigir pequenos bugs. Lançamentos menores são feitos periodicamente quando há vários bugs corrigidos ou funcionalidades adicionadas. Lançamentos principais serão lançados quando houver funcionalidades que quebram a compatibilidade.

## Segurança

Se você descobrir quaisquer problemas de segurança, consulte o [processo de segurança](https://github.com/sigstore/.github/blob/main/SECURITY.md) do sigstore.

## Arquivos de bundle nos Assets de Lançamento do GitHub

Os assets de lançamento do GitHub para `cosign` contêm arquivos de bundle do Sigstore produzidos por [GoReleaser](https://github.com/sigstore/cosign/blob/ac999344eb381ae91455b0a9c5c267e747608d76/.goreleaser.yml#L166) ao assinar o blob do cosign que é usado para verificar a integridade dos binários de lançamento. Este arquivo não é usado pelo próprio cosign, mas é fornecido para usuários que desejam [verificar a integridade dos binários de lançamento](https://docs.sigstore.dev/cosign/system_config/installation/#verifying-cosign-with-artifact-key).