Assinar imagens de contêiner com o Notation e o Azure Key Vault usando um certificado emitido por AC

Assinar e verificar imagens de contêiner com um certificado emitido por uma AC (Autoridade de Certificação) confiável é uma prática de segurança valiosa. Essa medida de segurança ajudará você a identificar, autorizar e validar com responsabilidade a identidade do editor da imagem do contêiner e da própria imagem do contêiner. As Autoridades de Certificação Confiáveis (CAs), como GlobalSign, DigiCert e outros, desempenham um papel crucial na validação da identidade de um usuário ou da organização, mantendo a segurança dos certificados digitais e revogando o certificado imediatamente após qualquer risco ou uso indevido.

Aqui estão alguns componentes essenciais que ajudam você a assinar e verificar imagens de contêiner com um certificado emitido por uma AC confiável:

• A Notação é uma ferramenta de segurança da cadeia de suprimentos de código aberto desenvolvida pela comunidade Projeto Notário e apoiada pela Microsoft, que oferece suporte à assinatura e verificação de imagens de contêineres e outros artefatos.
• O AKV (Azure Key Vault), um serviço baseado em nuvem para gerenciar chaves criptográficas, segredos e certificados, ajudará você a garantir o armazenamento e o gerenciamento seguro de um certificado com uma chave de assinatura.
• O plug-in akv de Notação azure-kv, a extensão do Notation usa as chaves armazenadas no Azure Key Vault para assinar e verificar as assinaturas digitais de imagens e artefatos de contêiner.
• O Registro de Contêiner do Azure (ACR) permite anexar essas assinaturas à imagem assinada e ajuda você a armazenar e gerenciar essas imagens de contêiner.

Quando você verifica a imagem, a assinatura é usada para validar a integridade da imagem e a identidade do signatário. Isso ajuda a garantir que as imagens de contêiner não sejam adulteradas e sejam de uma fonte confiável.

Neste artigo:

• Instalar a CLI de notação e o plug-in AKV
• Criar ou importar um certificado emitido por uma AC no AKV
• Criar e enviar por push uma imagem de contêiner com a tarefa do ACR
• Assine uma imagem de contêiner com a CLI do Notation e o plug-in AKV
• Verificar uma assinatura de imagem de contêiner com a CLI de Notação
• Carimbo de data/hora

Pré-requisitos

• Criar ou usar um Registro de Contêiner do Azure para armazenar imagens de contêiner e assinaturas
• Criar ou usar um Azure Key Vault.
• Instalar e configurar a CLI do Azure mais recente ou executar comandos no Azure Cloud Shell

Observação

É recomendável criar um novo Azure Key Vault apenas para armazenar certificados.

Instalar a CLI de notação e o plug-in AKV

1. Instale o Notation v1.2.0 em um ambiente amd64 do Linux. Siga o guia de instalação do Notação para baixar o pacote para outros ambientes.

   # Download, extract and install
   curl -Lo notation.tar.gz https://github.com/notaryproject/notation/releases/download/v1.2.0/notation_1.2.0_linux_amd64.tar.gz
   tar xvzf notation.tar.gz
   
   # Copy the notation cli to the desired bin directory in your PATH, for example
   cp ./notation /usr/local/bin
   

2. Instale o plug-in Notation Azure Key Vault azure-kv v1.2.0 em um ambiente Linux amd64.

   Observação

   A soma de verificação de URL e SHA256 para o plug-in de Notação do Azure Key Vault, pode ser encontrada na página de lançamento do plug-in.

   notation plugin install --url https://github.com/Azure/notation-azure-kv/releases/download/v1.2.0/notation-azure-kv_1.2.0_linux_amd64.tar.gz --sha256sum 06bb5198af31ce11b08c4557ae4c2cbfb09878dfa6b637b7407ebc2d57b87b34
   

3. Liste os plug-ins disponíveis e confirme se o plug-in azure-kv com a versão 1.2.0 está incluída na lista.

   notation plugin ls
   

Configurar variáveis de ambiente

Observação

Este guia usa variáveis de ambiente para conveniência ao configurar o AKV e o ACR. Atualize os valores dessas variáveis de ambiente para seus recursos específicos.

1. Configurar variáveis de ambiente para AKV e certificados

   AKV_SUB_ID=myAkvSubscriptionId
   AKV_RG=myAkvResourceGroup
   AKV_NAME=myakv 
   
   # Name of the certificate created or imported in AKV 
   CERT_NAME=wabbit-networks-io 
   
   # X.509 certificate subject
   CERT_SUBJECT="CN=wabbit-networks.io,O=Notation,L=Seattle,ST=WA,C=US"
   

2. Configure variáveis de ambiente para ACR e imagens.

   ACR_SUB_ID=myAcrSubscriptionId
   ACR_RG=myAcrResourceGroup
   # Name of the existing registry example: myregistry.azurecr.io 
   ACR_NAME=myregistry 
   # Existing full domain of the ACR 
   REGISTRY=$ACR_NAME.azurecr.io 
   # Container name inside ACR where image will be stored 
   REPO=net-monitor 
   TAG=v1 
   # Source code directory containing Dockerfile to build 
   IMAGE_SOURCE=https://github.com/wabbit-networks/net-monitor.git#main  
   

Entrar com a CLI do Azure

az login

Para saber mais sobre a CLI do Azure e como fazer entrar com ela, confira Entrar com a CLI do Azure.

Criar ou importar um certificado emitido por uma AC no AKV

Requisitos de certificado

Ao criar certificados para assinatura e verificação, os certificados devem atender ao requisito de certificado do Projeto de Notário.

Aqui estão os requisitos para certificados raiz e intermediário:

• A extensão basicConstraints deve estar presente e marcada como crítica. O campo CA deve ser definido true.
• A extensão keyUsage deve estar presente e marcada critical. As posições de bit para keyCertSign DEVEM ser definidas.

Aqui estão os requisitos para certificados emitidos por uma AC:

• Propriedades do certificado X.509:
  • O assunto deve conter nome comum (CN), país (C), estado ou província (ST) e organização (O). Neste tutorial, $CERT_SUBJECT é usado como o assunto.
  • O sinalizador de uso da chave X.509 deve ser apenas DigitalSignature.
  • Os EKUs (usos de chave estendida) devem estar vazios ou 1.3.6.1.5.5.7.3.3 (para a atribuição de código).
• Propriedades da chave:
  • A propriedade exportable precisa ser definida como false.
  • Selecione um tipo de chave e um tamanho com suporte na especificação do Projeto de Notário.

Importante

Para garantir a integração bem-sucedida com a Integridade da Imagem, o tipo de conteúdo do certificado deve ser definido como PEM.

Observação

Este guia usa a versão 1.0.1 do plug-in do AKV. As versões anteriores do plug-in tinham uma limitação que exigia uma ordem de certificado específica em uma cadeia de certificados. A versão 1.0.1 do plug-in não tem essa limitação, portanto, é recomendável que você use a versão 1.0.1 ou posterior.

Criar um certificado emitido por uma AC

Crie uma CSR (solicitação de assinatura de certificado) seguindo as instruções para criar uma solicitação de assinatura de certificado.

Importante

Ao mesclar a CSR, certifique-se de mesclar toda a cadeia que trouxe de volta do fornecedor de AC.

Importar o certificado no AKV

Para importar o certificado:

1. Obtenha o arquivo de certificado do fornecedor de AC com toda a cadeia de certificados.
2. Importe o certificado para o Azure Key Vault seguindo as instruções de importação de um certificado.

Observação

Se o certificado não contiver uma cadeia de certificados após a criação ou importação, você poderá obter os certificados intermediários e raiz do fornecedor de AC. Você pode pedir ao fornecedor que forneça um arquivo PEM que contenha os certificados intermediários (se houver) e o certificado raiz. Esse arquivo pode ser usado na etapa 5 de assinatura de imagens de contêiner.

Assine uma imagem de contêiner com a CLI do Notation e o plug-in AKV

Ao trabalhar com o ACR e o AKV, é essencial conceder as permissões apropriadas para garantir acesso seguro e controlado. Você pode autorizar o acesso a entidades diferentes, como entidades de usuário, entidades de serviço ou identidades gerenciadas, dependendo de seus cenários específicos. Neste tutorial, o acesso está autorizado a um usuário conectado do Azure.

Criando acesso ao ACR

As funções AcrPull e AcrPush são necessárias para criar e assinar imagens de contêiner no ACR.

1. Definir a assinatura que contém o recurso do ACR

   az account set --subscription $ACR_SUB_ID
   

2. Atribuir as funções

   USER_ID=$(az ad signed-in-user show --query id -o tsv)
   az role assignment create --role "AcrPull" --role "AcrPush" --assignee $USER_ID --scope "/subscriptions/$ACR_SUB_ID/resourceGroups/$ACR_RG/providers/Microsoft.ContainerRegistry/registries/$ACR_NAME"
   

Compilar e efetuar push da imagem do contêiner para o ACR

1. Faça a autenticação no ACR usando sua identidade individual do Azure.

   az acr login --name $ACR_NAME
   

Importante

Se você tiver o Docker instalado no sistema e usou az acr login ou docker login para se autenticar no ACR, suas credenciais já estarão armazenadas e disponíveis para notação. Nesse caso, você não precisa executar notation login novamente para se autenticar no ACR. Para saber mais sobre as opções de autenticação para notação, confira Autenticar com registros compatíveis com OCI.

1. Compilar e enviar por push uma nova imagem com Tarefas do ACR. Sempre use digest para identificar a imagem para assinatura, já que as marcas são mutáveis e podem ser substituídas.

   DIGEST=$(az acr build -r $ACR_NAME -t $REGISTRY/${REPO}:$TAG $IMAGE_SOURCE --no-logs --query "outputImages[0].digest" -o tsv)
   IMAGE=$REGISTRY/${REPO}@$DIGEST
   

Neste tutorial, se a imagem já foi criada e armazenada no registro, a marca servirá como um identificador para essa imagem por conveniência.

IMAGE=$REGISTRY/${REPO}@$TAG

Criando acesso ao AKV

Usar o RBAC do Azure (recomendado)

1. Definir a assinatura que contém o recurso AKV

   az account set --subscription $AKV_SUB_ID
   

2. Atribuir as funções

   Se o certificado contiver toda a cadeia de certificados, as seguintes funções precisarão ser atribuídas à entidade de segurança:

   • Key Vault Secrets User para ler segredos
   • Key Vault Certificates User para ler certificados
   • Key Vault Crypto User para operações de assinatura

   USER_ID=$(az ad signed-in-user show --query id -o tsv)
   az role assignment create --role "Key Vault Secrets User" --role "Key Vault Certificates User" --role "Key Vault Crypto User" --assignee $USER_ID --scope "/subscriptions/$AKV_SUB_ID/resourceGroups/$AKV_RG/providers/Microsoft.KeyVault/vaults/$AKV_NAME"
   

   Se o certificado não contiver a cadeia, as seguintes funções precisarão ser atribuídas à entidade de segurança:

   • Key Vault Certificates User para ler certificados
   • Key Vault Crypto User para operações de assinatura

   USER_ID=$(az ad signed-in-user show --query id -o tsv)
   az role assignment create --role "Key Vault Certificates User" --role "Key Vault Crypto User" --assignee $USER_ID --scope "/subscriptions/$AKV_SUB_ID/resourceGroups/$AKV_RG/providers/Microsoft.KeyVault/vaults/$AKV_NAME"
   

Para saber mais sobre o acesso ao Key Vault com o RBAC do Azure, consulte Usar um RBAC do Azure para gerenciar o acesso.

Usar a política de acesso (herdada)

Para definir a assinatura que contém os recursos do AKV, execute o seguinte comando:

az account set --subscription $AKV_SUB_ID

Se o certificado contiver toda a cadeia de certificados, a entidade de segurança deverá receber permissão de chave Sign, permissão secreta Get e permissões de certificado Get. Para conceder essas permissões à entidade de segurança:

USER_ID=$(az ad signed-in-user show --query id -o tsv)
az keyvault set-policy -n $AKV_NAME --key-permissions sign --secret-permissions get --certificate-permissions get --object-id $USER_ID

Se o certificado não contiver a cadeia, a entidade de segurança deverá receber permissão de chave Sign e permissões de certificado Get. Para conceder essas permissões à entidade de segurança:

USER_ID=$(az ad signed-in-user show --query id -o tsv)
az keyvault set-policy -n $AKV_NAME --key-permissions sign --certificate-permissions get --object-id $USER_ID

Para saber mais sobre a atribuição de política a uma entidade de segurança, confira Atribuir Política de Acesso.

Assinar imagens de contêiner usando o certificado no AKV

1. Obtenha a ID da chave de um certificado. Um certificado no AKV pode ter várias versões, o comando a seguir obtém a ID da chave para a versão mais recente do certificado $CERT_NAME.

   KEY_ID=$(az keyvault certificate show -n $CERT_NAME --vault-name $AKV_NAME --query 'kid' -o tsv) 
   

2. Assine a imagem de contêiner com o formato de assinatura COSE usando a ID da chave.

   Se o certificado contiver toda a cadeia de certificados, execute o seguinte comando:

   notation sign --signature-format cose $IMAGE --id $KEY_ID --plugin azure-kv 
   

   Se o certificado não contiver a cadeia, use o parâmetro --plugin-config ca_certs=<ca_bundle_file> para passar os certificados de AC em um arquivo PEM para o plug-in do AKV, execute o seguinte comando:

   notation sign --signature-format cose $IMAGE --id $KEY_ID --plugin azure-kv --plugin-config ca_certs=<ca_bundle_file> 
   

   Para autenticar com o AKV, por padrão, os seguintes tipos de credencial se habilitados serão testados na ordem:

   • Credencial de ambiente
   • Credencial de identidade de carga de trabalho
   • Credencial de identidade gerenciada
   • Credencial da CLI do Azure

   Se você quiser especificar um tipo de credencial, use uma configuração de plug-in adicional chamada credential_type. Por exemplo, você pode definir credential_type explicitamente como azurecli para usar a credencial da CLI do Azure, conforme demonstrado abaixo:

   notation sign --signature-format cose --id $KEY_ID --plugin azure-kv --plugin-config credential_type=azurecli $IMAGE
   

   Consulte a tabela abaixo para obter os valores de credential_type para vários tipos de credencial.

   Tipo de credencial	Valor para credential_type
   Credencial de ambiente	environment
   Credencial de identidade de carga de trabalho	workloadid
   Credencial de identidade gerenciada	managedid
   Credencial da CLI do Azure	azurecli

3. Veja o grafo de imagens assinadas e assinaturas associadas.

   notation ls $IMAGE
   

   No exemplo de saída a seguir, uma assinatura do tipo application/vnd.cncf.notary.signature identificada pelo digest sha256:d7258166ca820f5ab7190247663464f2dcb149df4d1b6c4943dcaac59157de8e está associada ao $IMAGE.

   myregistry.azurecr.io/net-monitor@sha256:17cc5dd7dfb8739e19e33e43680e43071f07497ed716814f3ac80bd4aac1b58f
   └── application/vnd.cncf.notary.signature
       └── sha256:d7258166ca820f5ab7190247663464f2dcb149df4d1b6c4943dcaac59157de8e
   

Verificar uma imagem de contêiner com a CLI do Notation

1. Adicione o certificado raiz a um repositório de confiança nomeado para verificação de assinatura. Se você não tiver o certificado raiz, poderá obtê-lo de sua AC. O exemplo a seguir adiciona o certificado raiz $ROOT_CERT ao repositório de confiança $STORE_NAME.

   STORE_TYPE="ca" 
   STORE_NAME="wabbit-networks.io" 
   notation cert add --type $STORE_TYPE --store $STORE_NAME $ROOT_CERT  
   

2. Liste o certificado raiz para confirmar se o $ROOT_CERT foi adicionado com êxito.

   notation cert ls 
   

3. Configure a política de confiança antes da verificação.

   As políticas de confiança permitem que os usuários especifiquem políticas de verificação com ajuste fino. Use o comando a seguir para configurar a política de confiança.

   cat <<EOF > ./trustpolicy.json
   {
       "version": "1.0",
       "trustPolicies": [
           {
               "name": "wabbit-networks-images",
               "registryScopes": [ "$REGISTRY/$REPO" ],
               "signatureVerification": {
                   "level" : "strict" 
               },
               "trustStores": [ "$STORE_TYPE:$STORE_NAME" ],
               "trustedIdentities": [
                   "x509.subject: $CERT_SUBJECT"
               ]
           }
       ]
   }
   EOF
   

   O arquivo acima trustpolicy.json define uma política de confiança chamada wabbit-networks-images. Essa política de confiança se aplica a todos os artefatos armazenados nos repositórios $REGISTRY/$REPO. O repositório de confiança nomeado $STORE_NAME do tipo $STORE_TYPE contém os certificados raiz. Ele também pressupõe que o usuário confia em uma identidade específica com o assunto X.509 $CERT_SUBJECT. Para obter mais detalhes, confira Especificação do repositório confiável e da política de confiança.

4. Use notation policy para importar a configuração de política de confiança de trustpolicy.json.

   notation policy import ./trustpolicy.json
   

5. Mostrar a configuração da política de confiança para confirmar sua importação bem-sucedida.

   notation policy show
   

6. Use notation verify para verificar a integridade da imagem:

   notation verify $IMAGE
   

   Após a verificação bem-sucedida da imagem usando a política de confiança, o código hash sha256 da imagem verificada será retornado em uma mensagem de saída bem-sucedida. Um exemplo de saída:

   Successfully verified signature for myregistry.azurecr.io/net-monitor@sha256:17cc5dd7dfb8739e19e33e43680e43071f07497ed716814f3ac80bd4aac1b58f

Carimbo de data/hora

Desde o lançamento do Notation v1.2.0, o Notation oferece suporte a carimbos de data/hora compatíveis com RFC 3161. Esse aprimoramento estende a confiança das assinaturas criadas no período de validade do certificado confiando em uma Autoridade de Carimbo de Data/Hora (TSA), permitindo a verificação de assinatura bem-sucedida mesmo após os certificados expirarem. Como signatário de imagem, você deve garantir a assinatura de imagens de contêineres com carimbos de data/hora gerados por um TSA confiável. Como verificador de imagens, para verificar carimbos de data/hora, você deve garantir que confia no signatário da imagem e no TSA associado e estabelecer a confiança usando armazenamentos e políticas de confiança. O registro de data e hora reduz custos ao eliminar a necessidade de assinar novamente imagens periodicamente devido à expiração do certificado, o que é especialmente crítico ao usar certificados de curta duração. Para obter instruções detalhadas sobre como assinar e verificar usando carimbo de data/hora, consulte o Guia de carimbo de data/hora do Notary Project.

Perguntas frequentes

• O que devo fazer se o certificado tiver expirado?

  Se o seu certificado tiver expirado, você precisará obter um novo de um fornecedor de AC confiável, juntamente com uma nova chave privada. Um certificado expirado não pode ser usado para assinar imagens de contêineres. Para imagens que foram assinadas antes da expiração do certificado, elas ainda poderão ser validadas com sucesso se forem assinadas com carimbo de data/hora. Sem o carimbo de data/hora, a verificação da assinatura falhará e você precisará assinar novamente essas imagens com o novo certificado para que a verificação seja bem-sucedida.

• O que devo fazer se o certificado for revogado?

  Se seu certificado for revogado, a assinatura será invalidada. Isso pode ocorrer por vários motivos, como o comprometimento da chave privada ou alterações na afiliação do titular do certificado. Para resolver esse problema, você deve primeiro garantir que o código-fonte e o ambiente de compilação estejam atualizados e seguros. Em seguida, crie imagens de contêineres a partir do código-fonte, obtenha um novo certificado de um fornecedor de AC confiável juntamente com uma nova chave privada e assine novas imagens de contêineres com o novo certificado seguindo este guia.

Próximas etapas

A notação também fornece soluções de CI/CD no fluxo de trabalho do Azure Pipeline e do GitHub Actions:

• Assinar e verificar uma imagem de contêiner com Notação no Azure Pipeline
• Assinar e verificar uma imagem de contêiner com Notação no Fluxo de Trabalho do GitHub Actions

Para validar a implantação de imagem assinada no AKS ou Kubernetes:

• Usar a Integridade da imagem para validar imagens conectadas antes de implantá-las em seus clusters do Serviço de Kubernetes do Azure (AKS) (Versão prévia)
• Usar o Ratify para validar e auditar a implantação de imagem em qualquer cluster do Kubernetes