Gerenciar etiquetas de chaves do KMS com operações de API

É possível usar a API do AWS Key Management Service (AWS KMS) para adicionar, excluir e listar etiquetas das chaves do KMS gerenciadas. Estes exemplos usam a AWS Command Line Interface (AWS CLI), mas você pode usar qualquer linguagem de programação compatível. Você não pode marcar Chaves gerenciadas pela AWS.

Para adicionar, editar, visualizar e excluir etiquetas de uma chave do KMS, é necessário ter as permissões apropriadas. Para obter detalhes, consulte Controlar o acesso a etiquetas.

CreateKey: Adicionar tags a uma nova chave KMS

Você pode adicionar tags ao criar uma chave gerenciada pelo cliente. Para especificar as tags, use o Tags parâmetro da CreateKeyoperação.

Para adicionar etiquetas ao criar uma chave do KMS, o chamador deve ter a permissão kms:TagResource em uma política do IAM. Essa permissão deve abranger pelo menos todas as chaves do KMS na conta e na região. Para obter detalhes, consulte Controlar o acesso a etiquetas.

O valor do parâmetro Tags de CreateKey é uma coleção de pares de chave de etiqueta e valor de etiqueta que faz distinção entre maiúsculas e minúsculas. Cada etiqueta em uma chave do KMS deve ter um nome de etiqueta diferente. O valor da tag pode ser uma string nula ou vazia.

Por exemplo, o seguinte comando da AWS CLI cria uma chave do KMS de criptografia simétrica com uma etiqueta Project:Alpha. Ao especificar mais de um par de chave-valor, use um espaço para separar cada par.

$ aws kms create-key --tags TagKey=Project,TagValue=Alpha

Quando esse comando é bem-sucedido, ele retorna um objeto KeyMetadata com informações sobre a nova chave do KMS. No entanto, o KeyMetadata não inclui tags. Para obter as tags, use a ListResourceTagsoperação.

TagResource: Adicionar ou alterar tags para uma chave KMS

A TagResourceoperação adiciona uma ou mais tags a uma chave KMS. Não é possível usar essa operação para adicionar ou editar etiquetas em uma Conta da AWS diferente.

Para adicionar uma tag, especifique uma nova chave e um valor de tag. Para editar uma tag, especifique uma chave de tag existente e um novo valor de tag. Cada etiqueta em uma chave do KMS deve ter um nome de etiqueta diferente. O valor da tag pode ser uma string nula ou vazia.

Por exemplo, o comando a seguir adiciona as etiquetas Purpose e Department a uma chave do KMS demonstrativa.

$ aws kms tag-resource \
         --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
         --tags TagKey=Purpose,TagValue=Pretest TagKey=Department,TagValue=Finance

Quando esse comando for executado com êxito, ele não retornará nenhuma saída. Para visualizar as tags em uma chave KMS, use a ListResourceTagsoperação.

Você também pode usar TagResource para alterar o valor de uma tag existente. Para substituir um valor de tag, especifique a mesma chave de tag com um valor diferente.

Por exemplo, esse comando altera o valor da tag Purpose de Pretest para Test.

$ aws kms tag-resource \
         --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
         --tags TagKey=Purpose,TagValue=Test

ListResourceTags: Obtenha as tags para uma chave KMS

A ListResourceTagsoperação obtém as tags de uma chave KMS. O parâmetro KeyId é obrigatório. Essa operação não pode ser usada para visualizar as etiquetas nas chaves do KMS em uma Conta da AWS diferente.

Por exemplo, o comando a seguir obtém as etiquetas para uma chave do KMS demonstrativa.

$ aws kms list-resource-tags --key-id 1234abcd-12ab-34cd-56ef-1234567890ab
       
  "Truncated": false,
  "Tags": [
      {
        "TagKey": "Project",
        "TagValue": "Alpha"
     },
     {
       "TagKey": "Purpose",
       "TagValue": "Test"
     },
     {
       "TagKey": "Department",
       "TagValue": "Finance"
     }
  ]
}

UntagResource: Excluir tags de uma chave KMS

A UntagResourceoperação exclui as tags de uma chave KMS. Para identificar as etiquetas a serem excluídas, especifique as chaves de etiqueta. Essa operação não pode ser usada para excluir etiquetas de chaves do KMS em uma Conta da AWS diferente.

Quando é bem-sucedida, a operação UntagResource não retorna nenhuma saída. Além disso, se a chave de etiqueta especificada não for encontrada na chave do KMS, ela não lançará uma exceção nem retornará uma resposta. Para confirmar se a operação funcionou, use a ListResourceTagsoperação.

Por exemplo, esse comando exclui a etiqueta Purpose e seu valor da chave do KMS especificada.

$ aws kms untag-resource --key-id 1234abcd-12ab-34cd-56ef-1234567890ab --tag-keys Purpose