Gerando uma chave GPG

Os artefatos criados pela cadeia de ferramentas de integração contínua IBM Cloud DevSecOps e registrados no inventário devem ser assinados antes de serem implantados em produção. O pipeline de integração contínua utiliza Skopeo como ferramenta padrão para fornecer a capacidade de assinatura de artefatos.

Crie e armazene uma chave GPG que é usada pelo pipeline de integração contínua do DevSecOps automática ou manualmente.

Gerar automaticamente uma chave GPG

Usando esse método, o modelo gera a chave GPG para você. Insira o name e email para a geração de chaves concluindo estas etapas:

  1. Acesse Assinatura de artefato e clique em Novo.

    Assinatura de imagem
    Assinatura de artefato

  2. Na janela, os campos name e email são pré-preenchidos com o nome da cadeia de ferramentas e o ID do email.. Altere o nome e o ID do e-mail para refletir seus requisitos de chave GPG. Também é possível armazenar as chaves em seu provedor de segredos selecionando a caixa.

    Alterar nome e e-mail
    Alterar nome e e-mail

  3. Depois que a chave for gerada, será possível copiá-la para sua referência

    Certificado de assinatura de imagem
    Figura 3 Certificado de assinatura de artefato

A chave copiada está no formato base64.. Decodifique a chave antes de importá-la para seu chaveiro. echo <encoded_gpg_key> | base64 --decode

Gerar manualmente uma chave GPG

Faça download e instale as ferramentas de linha de comandos do GPG

Baixe e instale as ferramentas de linha de comando do GPG para o seu sistema operacional. Acesse a seção “ GnuPG versões binárias ” para baixar as ferramentas para o seu sistema operacional.

Mac OS X

  • Faça download e instale Mac GPG.
  • Verifique a versão do GPG instalado. Na linha de comandos, execute o comando a seguir:
$ gpg --version
gpg (GnuPG) 2.3.1
libgcrypt 1.9.3
Copyright (C) 2021 Free Software Foundation, Inc.
  • Nas versões do GPG anteriores à 2.3.1, talvez não seja possível usar a opção --passphrase=''. Nesse caso, é possível omitir a senha no diálogo a seguir pressionando Enter quando solicitado..

Windows™

  • Baixe e instale GitBash (necessário para a codificação base64 ).
  • Verifique a versão do GPG instalado. Execute o seguinte comando no prompt de comandos do Git bash:
$ gpg --version
gpg (GnuPG) 2.2.27
libgcrypt 1.8.7
Copyright (C) 2021 g10 Code GmbH

Gere uma chave de API.

Deixe a passphrase e o campo vazio se o comando generate-key abrir um diálogo que solicita uma passphrase.. Essa é uma limitação do utilitário skopeo para assinatura de imagens, em que o pipeline não aceita chaves privadas protegidas por senha. Se você fornecer a senha durante a criação, o pipeline não conseguirá decodificar o certificado e falhará na etapa de assinatura da imagem. Observe que isso também se aplica à assinatura de tags do GIT.

Mac OS X e Linux™

No prompt do shell, execute o seguinte comando:

gpg --pinentry-mode loopback --passphrase='' --generate-key
  • Digite seu nome e endereço de e-mail.
  • Digite O para iniciar a criação da chave.
  • Depois que a chave for gerada, selecione a opção O.

Windows™

GPG Versão > 1.4

No prompt de comandos Git bash, execute o seguinte comando:

gpg --pinentry-mode loopback --passphrase='' --generate-key
  • Digite seu nome no campo “Nome verdadeiro ”.
  • Insira o seu endereço de e-mail no Endereço de e-mail
  • Digite O para iniciar a criação da chave.
  • Depois que a chave for gerada, selecione a opção O.

Versão do GPG < 1.4 (ou qualquer falha no comando anterior)

No prompt de comandos Git bash, execute o seguinte comando:

gpg --gen-key
  • tipo de chave: selecione a opção Padrão (1) RSA e RSA (padrão)
  • tamanho da chave: manter o padrão (2048)
  • key validade: manter o valor padrão como 0. Isso ocorre porque o valor da chave 0 não expira.
  • Confirme sua escolha: digite y.
  • Insira o seu nome no campo Nome Real
  • Insira o seu endereço de e-mail no Endereço de e-mail
  • Digite O para iniciar a criação da chave.
  • Depois que a chave for gerada, selecione a opção O.

Verifique a criação da chave

Verifique se a chave gpg foi criada. No prompt de comando, execute o seguinte comando:

gpg --list-keys

Certifique-se de que sua chave esteja listada Saída de exemplo no Windows:

$ gpg --list-keys
/c/Users/FredSmith/.gnupg/pubring.gpg
-------------------------------------
pub   2048R/1BB354B5 2021-06-08
uid   Fred Smith <fred@company.com>
sub   2048R/F91C39A6 2021-06-08

Exporte a chave

Esta etapa é opcional. Execute este comando para assegurar que seja possível exportar a chave gpg.

gpg --export-secret-key <Email Address>

A chave bruta exportada não deve ser copiada diretamente. Recomenda-se guardar com segurança a chave gerada nesta etapa na sua instância do Key Protect ou do Secrets Manager. Consulte as próximas seções para obter mais detalhes.

Armazene a chave

A chave GPG deve ser fornecida ao pipeline de integração contínua de uma das seguintes formas:

  • Armazenada em IBM® Key Protect for IBM Cloud®
  • Armazenada em IBM Cloud® Secrets Manager
  • Armazenada diretamente na cadeia de ferramentas de integração contínua

Certifique-se de que a chave seja copiada no formato correto para evitar que haja um erro de assinatura do pipeline de integração contínua causado por uma falha de importação. Use pbcopy ( Mac OS X ) ou clip (Windows Git bash) no comando a seguir para copiar o conteúdo da chave para a área de transferência.

Armazene a chave em Key Protect

Exporte e copie a chave GPG para a área de transferência.

É necessário realizar a codificação dupla com o algoritmo “ base64 ” da chave GPG antes de armazená-la na sua instância do Key Protect.

OS X

gpg --export-secret-key <Email Address> | base64 | base64 | pbcopy

Windows™

gpg --export-secret-key <Email Address> | base64 -w0 | base64 -w0 | clip

Linux™

gpg --export-secret-key <Email Address> | base64 | base64

  1. No console do IBM Cloud, selecione a instância do Key Protect na qual deseja armazenar a chave GPG gerada a partir das etapas anteriores.

  2. Clique no ícone Incluir + para incluir uma nova chave na instância

  3. Selecione a opção “Importar sua própria chave ”.

  4. Selecione um tipo de chave como Chave Padrão.

  5. Insira o nome adequado no campo " Nome da chave ". A chave GPG armazenada pode ser recuperada posteriormente por meio desse nome de chave.

  6. Copie a chave exportada anteriormente no campo " Material da chave ".

    Certifique-se de que, ao copiar a chave e colá-la no campo “Material da chave”, não haja nenhuma linha extra no final da chave.

  7. Selecione a opção “Escolher um chaveiro” como padrão.

  8. Clique em Incluir chave para incluir a chave em sua proteção de chave

    Adicionar a chave para proteger a chave
    Adicionar a chave para proteger a chave

Para obter mais informações sobre Key Protect, consulte os documentos do Key Protect.

Armazene a chave em Secrets Manager

É necessário fazer a codificação simples base64 da chave GPG antes de armazená-la em sua instância do Secrets Manager .

Exporte e copie a chave GPG para a área de transferência.

OS X

gpg --export-secret-key <Email Address> | base64 | pbcopy

Windows™

gpg --export-secret-key <Email Address> | base64 -w0 | clip

Linux™

gpg --export-secret-key <Email Address> | base64

  1. No console do IBM Cloud, selecione a instância do Secrets Manager na qual deseja armazenar a chave GPG gerada a partir das etapas anteriores.

  2. Clique no ícone Incluir + para incluir uma nova chave na instância

  3. Selecione a opção “Outro tipo de segredo ”.

    Outro tipo de segredo
    Outro tipo de segredo

  4. Selecione o tipo de Chave Padrão para a opção Selecionar um Tipo de Chave

  5. Insira um nome adequado no campo " Nome ". Posteriormente, é possível usar esse nome para recuperar a chave GPG armazenada.

  6. Selecione a opção “ Valor secreto ” e cole a chave exportada anteriormente no campo “Valor secreto ”.

    Certifique-se de que, ao copiar a chave e colá-la no campo “Valor secreto”, não haja nenhuma linha extra no final da chave.

  7. Inclua a chave em sua instância do Key Protect clicando no ícone Incluir.

    Adicionar a chave
    Adicionar a chave

Para obter mais informações sobre o Secrets Manager, consulte Introdução ao Secrets Manager.

Exporte a chave privada e armazene-a diretamente no pipeline de integração contínua

Essa abordagem não é recomendada e deve ser usada apenas para fins experimentais. Use Key Protect ou Secrets Manager para armazenar as chaves. Para obter mais informações, consulte Configurando os armazenamentos de segredos

É necessário fazer a codificação simples base64 da chave GPG antes de armazená-la como uma propriedade de pipeline protegida.

Armazene a chave GPG de forma segura em uma instância do Key Protect ou do Secrets Manager.

Mac OS X / Linux™

gpg --export-secret-key <Email Address> | base64

Windows™

gpg --export-secret-key <Email Address> | base64 -w0

Configurando credenciais do Registro para assinatura

Ao assinar imagens de contêiner, o pipeline precisa de credenciais para se autenticar no registro de contêineres. O pipeline do DevSecOps oferece suporte à resolução dinâmica de credenciais em tempo de execução, permitindo que você configure credenciais de várias maneiras com mecanismos automáticos de fallback.

Hierarquia de resolução de credenciais

O pipeline resolve dinamicamente as credenciais de nome de usuário e chave de API em tempo de execução, utilizando a seguinte hierarquia.

Quando uma substituição do destino de assinatura é configurada usando gara-destination-registry e gara-destination-namespace, e gara-destination-apikey também é fornecido, o pipeline atribui a maior prioridade a gara-destination-apikey para a autenticação no registro de destino. Caso contrário, recorre-se à resolução de credenciais abaixo para a imagem de destino.

Ordem de resolução da chave da API:

  1. Chave de API específica do namespace: signing-token-apikey-{registry}-{namespace} (segredo)
  2. Chave de API específica do registro: signing-token-apikey-{registry} (segredo)
  3. Docker Arquivo de configuração JSON: signing-dockerconfigjson (segredo)
  4. Soluções alternativas específicas para ICR:
    • ciso-ibmcloud-api-key (segredo)
    • ibmcloud-api-key (segredo)

Ordem de resolução de nomes de usuário:

  1. Nome de usuário específico do namespace: signing-token-username-{registry}-{namespace} (variável de ambiente)
  2. Nome de usuário específico do Registro: signing-token-username-{registry} (variável de ambiente)
  3. Padrão: iamapikey (se nenhum nome de usuário estiver configurado)

Em que:

  • {registry} é o nome de host do registro (por exemplo, us.icr.io, de.icr.io)
  • {namespace} é o caminho completo do namespace, com barras e pontos substituídos por sublinhados (por exemplo, my_namespace_path)

Configurando credenciais específicas do namespace

Para um controle de acesso mais detalhado, é possível configurar credenciais específicas para um namespace do registro:

Chave da API (Segredo): signing-token-apikey-{registry}-{namespace}

Nome de usuário (variável de ambiente): signing-token-username-{registry}-{namespace}

Exemplo: Para a imagem us.icr.io/my-namespace/my-app:latest

  • Registro: us.icr.io
  • Espaço de nomes: my-namespace
  • Chave secreta da API: signing-token-apikey-us.icr.io-my_namespace
  • Variável de ambiente "username": signing-token-username-us.icr.io-my_namespace
  • Se o nome de usuário não for fornecido, o padrão será: iamapikey

Configurando credenciais específicas do registro

Para obter acesso mais amplo a todos os espaços de nomes em um registro:

Chave da API (Segredo): signing-token-apikey-{registry}

Nome de usuário (variável de ambiente): signing-token-username-{registry}

Exemplo: Para qualquer imagem em us.icr.io

  • Chave secreta da API: signing-token-apikey-us.icr.io
  • Variável de ambiente "username": signing-token-username-us.icr.io
  • Se o nome de usuário não for fornecido, o padrão será: iamapikey

Configurando o arquivo JSON de configuração d Docker

Você pode fornecer um arquivo JSON de configuração do tipo base64-encoded Docker que contenha credenciais para vários registros:

Nome secreto: signing-dockerconfigjson

Formato: Base64-encoded JSON compatível com o formato config.json do site Docker:

{
  "auths": {
    "us.icr.io": {
      "username": "iamapikey",
      "password": "your-api-key"
    },
    "us.icr.io/my-namespace": {
      "username": "iamapikey",
      "password": "namespace-specific-key"
    }
  }
}

O pipeline corresponde primeiro ao caminho mais específico, permitindo substituições no nível do namespace dentro da configuração do Docker.

Configuração de exemplo

Para ver uma imagem us.icr.io/production/my-app:v1.0.0:

Opção 1: Específico do namespace (recomendado para produção)

  • Chave secreta da API: signing-token-apikey-us.icr.io-production = your-namespace-api-key
  • Variável de ambiente de nome de usuário (opcional): signing-token-username-us.icr.io-production = iamapikey
  • Se o nome de usuário não for especificado, o padrão será iamapikey

Opção 2: Em todo o Registro

  • Chave secreta da API: signing-token-apikey-us.icr.io = your-registry-api-key
  • Variável de ambiente de nome de usuário (opcional): signing-token-username-us.icr.io = iamapikey
  • Se o nome de usuário não for especificado, o padrão será iamapikey

Opção 3: Arquivo JSON de configuração do Docker

  • Segredo: signing-dockerconfigjson = base64-encoded-docker-config
  • O nome de usuário é extraído do arquivo JSON de configuração Docker

Opção 4: Padrão do IBM Cloud (automático para ICR)

  • Chave secreta da API: ibmcloud-api-key = your-ibmcloud-api-key
  • O nome de usuário padrão é iamapikey