Como verificar atestados

Neste guia, você vai aprender a verificar atestados para chaves do Cloud HSM, que são sempre armazenadas em um módulo de segurança de hardware (HSM). Este guia se aplica às chaves do Cloud HSM multitenant e do Cloud HSM de locatário único.

Visão geral

Na criptografia, um atestado é uma instrução legível por máquina que pode ser programada por um software. Os atestados são um componente importante da computação confiável e podem ser necessários por motivos de conformidade.

Para visualizar e verificar os atestados, solicite uma declaração de atestado assinada por criptografia no HSM, com as cadeias de certificados usadas para assiná-los. A declaração de atestado é produzida pelo hardware HSM e assinada por certificados de propriedade do Google e do fabricante do HSM.

Depois de fazer o download da declaração de atestado e das cadeias de certificados, é possível verificar os atributos ou verificar a validade do atestado usando as cadeias de certificado.

O script de atestado é um script Python de código aberto desenvolvido pelo Google. É possível ver o código-fonte do script para saber mais sobre o formato do atestado e como a verificação funciona ou como um modelo para uma solução personalizada.

Os exemplos neste tópico foram desenvolvidos para ambientes Linux, incluindo o Cloud Shell. Para acompanhar os clientes do macOS ou do Windows, talvez seja necessário fazer modificações.

Antes de começar

Se necessário, crie uma chave do Cloud HSM em um keyring em uma região compatível com o Cloud HSM.
Faça o download e instale os scripts para analisar os valores do atestado do fabricante do HSM. Faça o download de cada um desses scripts:
- verify_pubkey.py
- parse_v1.py
- parse_v2.py
Observação: não faça o download de verify_attest.py. Em vez disso, use o script de verificação fornecido pelo Google.

Procure a documentação para usar os scripts, fornecidos no mesmo local.
Faça o download e instale o script para verificar atestados e os pré-requisitos dele. Em seguida, analise a documentação do script.

Como verificar o atestado

O processo de verificação de atestado pode ser executado automaticamente no console do Google Cloud ou manualmente, fazendo o download do pacote de atestado e do script de verificação do atestado e executando-o localmente ou no Cloud Shell.

Como verificar atestados no console do Google Cloud

É possível verificar o atestado no console do Google Cloud , que abrirá um Cloud Shell e o preencherá com os snippets de código necessários para executar todo o processo de verificação.

Acesse a página Gerenciamento de chaves no console do Google Cloud .

Acessar a página "Gerenciamento de chaves"
Selecione o keyring que contém a chave que você quer atestar e selecione a chave.
Clique em Mais na versão da chave que você quer atestar e selecione Verificar atestado.
Na caixa de diálogo Verificar atestado, clique em Abrir o Cloud Shell. O Cloud Shell será aberto e preenchido com o snippet de código necessário para o processo de verificação.
Inspecione o snippet de código pré-preenchido no Cloud Shell. O snippet faz o download do script de verificação do atestado e das respectivas dependências, executa os comandos da gcloud para fazer o download do atestado e das cadeias de certificados e, em seguida, executa o script para verificar o atestado.
Execute o snippet de código para verificar o atestado.

Como verificar o atestado manualmente

O atestado, as cadeias de certificados e o script de verificação de atestado precisam ser baixados antes de verificar manualmente o atestado.

Faça o download das cadeias de atestados e certificados.
Console
1. Acesse a página Gerenciamento de chaves no console do Google Cloud .
  
  Acessar a página "Gerenciamento de chaves"
2. Selecione o keyring que contém a chave que você quer atestar e selecione a chave.
3. Clique em Mais na versão da chave que você quer atestar e selecione Verificar atestado.
4. Na caixa de diálogo Verificar atestado, clique em Fazer download do pacote de atestado. Isso fará o download de um arquivo ZIP contendo as cadeias de atestado e de certificado.
5. Extraia as cadeias de atestados e certificados do pacote de atestados.
gcloud
1. Clique em Ativar o Cloud Shell na parte superior da janela do console.
  
  Uma sessão do Cloud Shell é aberta em um novo frame na parte inferior do console, e um prompt de linha de comando é exibido. A inicialização da sessão do shell pode levar alguns segundos.
2. No prompt de linha de comando do Cloud Shell, use o comando gcloud kms keys versions describe para recuperar o atestado da chave que você quer atestar. A sinalização --attestation-file especifica o caminho e o destino do nome de arquivo do atestado recuperado.
  gcloud kms keys versions describe key-version \ --key key-name \ --location location \ --keyring keyring-name \ --attestation-file [attestation-file] \
3. No prompt de linha de comando do Cloud Shell, use o comando gcloud kms keys versions get-certificate-chain para recuperar as cadeias de certificado da chave que você quer atestar. A sinalização --output-file especifica o caminho e o destino do nome de arquivo do certificado recuperado.
  gcloud kms keys versions get-certificate-chain key-version \ --key key-name \ --location location \ --keyring keyring-name \ --output-file [certificates-file] \
Faça o download do script para verificar atestados e os pré-requisitos dele. Em seguida, siga a documentação do script para verificar o atestado no arquivo de atestado usando os certificados no arquivo de certificados.

Como analisar os valores do atestado

A documentação do fabricante do HSM inclui instruções completas sobre o uso dos scripts para analisar os valores de um atestado e verificar a chave pública de um par de chaves assimétricas. O atestado precisa ser descompactado com o comando a seguir antes de ser analisado.

Descompacte o atestado compactado.

gzip -d < compressed_attestation.dat > attestation.dat

Esses links vão diretamente para instruções específicas do fabricante do HSM:

Verificar a chave pública de par de chaves assimétrica (em inglês)
Analisar os valores do atestado (em inglês)

As instruções para analisar o valor do atestado incluem uma referência de campos gerais no atestado, não específicas para chaves HSM no Cloud HSM.

As seções a seguir ilustram como verificar informações sobre suas chaves que são específicas do Cloud HSM.

Verificar o ID da versão da chave

Você pode verificar se o hash SHA-256 do código do recurso da versão-chave está no atestado. O nome do recurso da chave faz parte do campo 0x0102 ou do campo de ID da chave no arquivo de atestado. O ID da chave é composto de dois resumos de hash SHA-256 concatenados no formato hexadecimal. O segundo deve corresponder ao nome do recurso da chave.

Consiga o ID do recurso da versão da chave para a versão da chave. Use o consoleGoogle Cloud para conseguir o ID do recurso da versão da chave ou execute o seguinte comando:
```
gcloud kms keys versions list \
   --location location \
   --keyring key-ring-name \
   --key key-name
```

Na linha de comando, atribua resource_name ao ID do recurso da versão da chave que você acabou de recuperar.

RESOURCE_NAME="projects/project-id/locations/location/keyRings/key-ring-name/cryptoKeys/key-name/cryptoKeyVersions/key-version"

Como o script de análise despeja todos os campos de atestado no formato hexadecimal, o ID da chave teria sido formatado duas vezes em hexadecimal. Uma vez ao criar o ID da chave e outra ao analisar o atestado. Para verificar se o nome do recurso corresponde ao ID da chave, converta-o em um resumo hexadecimal de SHA-256, reverta uma conversão hexadecimal do ID da chave no arquivo de atestado e compare os dois.
```
RESOURCE_NAME_HEX="$(echo -n ${RESOURCE_NAME} | openssl dgst -sha256 -hex | awk '{print $2}')"
```
O script de análise despeja todos os campos de atestado no formato hexadecimal, e o código da chave é codificado internamente em hexadecimal. Defina a variável de ambiente KEYID_HEX como o valor do código da chave com uma camada de codificação hexadecimal decodificada:
```
KEYID_HEX=$(grep -m 1 0x0102 /path/to/parsed/attestation.dat | awk '{print $2}' | xxd -p -r)
```
Compare os valores de RESOURCE_NAME_HEX e KEYID_HEX como strings:
```
test  ${RESOURCE_NAME_HEX} == ${KEYID_HEX:(-64)} || echo "Values don't match"
```
Se os valores forem correspondentes, nenhuma saída será retornada e o comando será encerrado com o código 0.

Verificar outras propriedades da chave

Você pode visualizar várias propriedades de chave, que correspondem aos campos no padrão PKCS #11. Use os seguintes exemplos como guias para verificar outras propriedades da chave.

Se uma chave é extraível, ela é armazenada no campo 0x0102 da saída analisada. Para determinar se uma chave pode ser extraída, observe o campo 0x0162: Um valor de \x01 é true e um valor de \x00 é false.

Chaves do Cloud HSM não podem ser extraídas.
```
grep '0x0162:' /path/to/parsed/attestation.dat
```
Como a chave chegou ao HSM, se ela foi criada diretamente ou importada, é armazenado no campo 0x0163. Se a chave tiver sido criada localmente no HSM, o campo será definido como \x01. O campo de uma chave importada é definido como \x00.

Você pode inferir algumas informações sobre como a chave chegou ao HSM. Se a chave foi criada no Cloud HSM, isso significa que ela nunca foi armazenada sem criptografia fora de um HSM. Se a chave foi importada, o mecanismo de importação garante que ela esteja protegida durante o processo de importação e no Cloud HSM posteriormente.
```
grep '0x0163:' /path/to/parsed/attestation.dat
```
O tipo de chave é armazenado no campo 0x0100. Os tipos de chave são documentados no padrão PCKS#11 com o prefixo CKK_*. Por exemplo, uma chave AES tem um tipo de \x1f.
```
grep '0x0100:' /path/to/parsed/attestation.dat
```

Mais informações

Verifique um atestado para determinar se uma versão de chave foi criada em um HSM.