Visualizar chaves do KMS com a API

Você pode usar a API do AWS Key Management Service(AWS KMS) para ver suas chaves do KMS. Esta seção demonstra várias operações que retornam detalhes sobre as chaves do KMS existentes. Os exemplos usam a AWS Command Line Interface (AWS CLI), mas você pode usar qualquer linguagem de programação compatível.

ListKeys: obtenha o ID e o ARN de todas as chaves KMS

A ListKeysoperação retorna o ID e o Amazon Resource Name (ARN) de todas as chaves KMS na conta e na região.

Por exemplo, essa chamada para a operação ListKeys retorna o ID e o ARN de cada chave do KMS nessa conta fictícia. Para obter exemplos em várias linguagens de programação, consulte Obter IDs e ARNs de chaves do KMS.

$ aws kms list-keys
        
{
  "Keys": [
    {
      "KeyArn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
      "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
    },
    {
      "KeyArn": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
      "KeyId": "0987dcba-09fe-87dc-65ba-ab0987654321"
    },
    {
      "KeyArn": "arn:aws:kms:us-east-2:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d",
      "KeyId": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
    }
}

DescribeKey: Obtenha informações detalhadas sobre uma chave KMS

A DescribeKeyoperação retorna detalhes sobre a chave KMS especificada. Para identificar a chave do KMS, use seu ID de chave, ARN de chave, nome de alias ou ARN de alias.

Ao contrário da ListKeysoperação, que exibe somente as chaves KMS na conta e na região do chamador, os usuários autorizados podem usar a DescribeKey operação para obter detalhes sobre as chaves KMS em outras contas.

nota

A resposta de DescribeKey inclui os membros KeySpec e CustomerMasterKeySpec com os mesmos valores. O membro CustomerMasterKeySpec é defasado.

Por exemplo, essa chamada para DescribeKey retorna informações sobre uma chave do KMS de criptografia simétrica. Os campos na resposta variam de acordo com a especificação da AWS KMS key, o estado da chave e a origem do material de chave. Para obter exemplos em várias linguagens de programação, consulte Como visualizar um AWS KMS key.

$ aws kms describe-key --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

{
    "KeyMetadata": {
        "Origin": "AWS_KMS",
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "Description": "",
        "KeyManager": "CUSTOMER",
        "Enabled": true,
        "KeySpec": "SYMMETRIC_DEFAULT",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "KeyState": "Enabled",
        "CreationDate": 1499988169.234,
        "MultiRegion": false,
        "Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "AWSAccountId": "111122223333",
        "EncryptionAlgorithms": [
            "SYMMETRIC_DEFAULT"
        ]
    }
}

Esse exemplo chama a operação DescribeKey em uma chave do KMS assimétrica usada para assinatura e verificação. A resposta inclui os algoritmos de assinatura compatíveis com o AWS KMS para essa chave do KMS.

$ aws kms describe-key --key-id 0987dcba-09fe-87dc-65ba-ab0987654321

{
    "KeyMetadata": {        
        "KeyId": "0987dcba-09fe-87dc-65ba-ab0987654321",
        "Origin": "AWS_KMS",
        "Arn": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
        "KeyState": "Enabled",
        "KeyUsage": "SIGN_VERIFY",
        "CreationDate": 1569973196.214,
        "Description": "",
        "KeySpec": "ECC_NIST_P521",
        "CustomerMasterKeySpec": "ECC_NIST_P521",
        "AWSAccountId": "111122223333",
        "Enabled": true,
        "MultiRegion": false,
        "KeyManager": "CUSTOMER",
        "SigningAlgorithms": [
            "ECDSA_SHA_512"
        ]
    }
}

GetKeyPolicy: Obtenha a política de chaves anexada a uma chave KMS

A GetKeyPolicyoperação obtém a política de chaves anexada à chave KMS. Para identificar a chave do KMS, use seu ID de chave ou ARN de chave. Você também deve especificar o nome da política, que é sempre default. (Se for difícil realizar a leitura de sua saída, adicione a opção --output text ao seu comando.) GetKeyPolicy só funciona em chaves do KMS na conta e na região do chamador.

Para obter exemplos em várias linguagens de programação, consulte Obter uma política de chaves.

$ aws kms get-key-policy --key-id 1234abcd-12ab-34cd-56ef-1234567890ab --policy-name default

{
  "Version" : "2012-10-17",
  "Id" : "key-default-1",
  "Statement" : [ {
    "Sid" : "Enable IAM User Permissions",
    "Effect" : "Allow",
    "Principal" : {
      "AWS" : "arn:aws:iam::111122223333:root"
    },
    "Action" : "kms:*",
    "Resource" : "*"
  } ]
}

ListAliases: Obtenha nomes de alias e ARNs para chaves KMS

A ListAliasesoperação retorna aliases na conta e na região. O TargetKeyId na resposta exibe o ID de chave da chave do KMS ao qual o alias faz referência, caso exista.

Por padrão, o comando ListAliases gera todos os aliases na conta e na região. Isso inclui aliases que você criou e associou às suas chaves gerenciadas pelo cliente e aliases que a AWS criou e associou à Chave gerenciada pela AWS na sua conta. Você pode reconhecer aliases da AWS porque os nomes têm o formato aws/<service-name>, como aws/dynamodb.

A resposta também pode incluir aliases sem o campo TargetKeyId, como o alias aws/redshift neste exemplo. Estes são aliases predefinidos criados pela AWS, mas que ainda não estão associados a uma chave do KMS.

Para obter exemplos em várias linguagens de programação, consulte Listar aliases.

$ aws kms list-aliases

{
    "Aliases": [
        {
            "AliasName": "alias/access-key",
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/access-key",
            "TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321",
            "CreationDate": 1516435200.399,
            "LastUpdatedDate": 1516435200.399
        }, 
        {
            "AliasName": "alias/financeKey",
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/financeKey",
            "TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321",            
            "CreationDate": 1604958290.014,
            "LastUpdatedDate": 1604958290.014
        },
        {
            "AliasName": "alias/ECC-P521-Sign",
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/ECC-P521-Sign",
            "TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
            "CreationDate": 1693622000.704,
            "LastUpdatedDate": 1693622000.704
        },
        {
            "AliasName": "alias/ImportedKey",
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/ImportedKey",
            "TargetKeyId": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d",
            "CreationDate": 1493622000.704,
            "LastUpdatedDate": 1521097200.235
        },
        {
            "AliasName": "alias/aws/dynamodb",
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/aws/dynamodb",
            "TargetKeyId": "0987ab65-43cd-21ef-09ab-87654321cdef",
            "CreationDate": 1521097200.454,
            "LastUpdatedDate": 1521097200.454
        },
        {
            "AliasName": "alias/aws/ebs",
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/aws/ebs",
            "TargetKeyId": "abcd1234-09fe-ef90-09fe-ab0987654321",
            "CreationDate": 1466518990.200,
            "LastUpdatedDate": 1466518990.200
        },
        {
            "AliasName": "alias/aws/redshift",
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/aws/redshift"
        },
    ]
}

Para obter os aliases que fazem referência a uma determinada chave do KMS, use o parâmetro KeyId. O valor do parâmetro pode ser o ID da chave ou o ARN da chave. Não é possível especificar um nome de alias ou um ARN de alias.

O comando no exemplo a seguir obtém os aliases que fazem referência a uma chave gerenciada pelo cliente. No entanto, também é possível usar um comando como esse para localizar os aliases que fazem referência a Chaves gerenciadas pela AWS.

$ aws kms list-aliases --key-id arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321
{
    "Aliases": [
        {
            "AliasName": "alias/access-key",
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/access-key",
            "TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321",
            "CreationDate": 1516435200.399,
            "LastUpdatedDate": 1516435200.399
        },
        {
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/financeKey",
            "TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321",
            "AliasName": "alias/financeKey",
            "CreationDate": 1604958290.014,
            "LastUpdatedDate": 1604958290.014
        },
    ]
}

Para obter somente os aliases para Chaves gerenciadas pela AWS, use os recursos da sua linguagem de programação para filtrar a resposta.

$ aws kms list-aliases --query 'Aliases[?starts_with(AliasName, `alias/aws/`)]'

ListResourceTags: Obtenha as tags nas chaves KMS

A ListResourceTagsoperação retorna as tags na chave KMS especificada. A API retorna etiquetas para uma chave do KMS, mas você pode executar o comando em um loop para obter etiquetas para todas as chaves do KMS na conta e região, ou para um conjunto de chaves do KMS selecionadas. Como essa API retorna uma página de cada vez, se você tiver várias etiquetas em várias chaves do KMS, talvez seja necessário usar o paginador na sua linguagem de programação para obter todas as etiquetas desejadas.

A operação ListResourceTags retorna tags para todas as chaves do KMS, mas Chave gerenciada pela AWS não são marcadas. Esse recurso só funciona em chaves do KMS na conta e na região do chamador.

Para localizar as etiquetas de uma chave do KMS, use a operação ListResourceTags. O parâmetro KeyId é obrigatório. Ela aceita um ID da chave ou um ARN de chave. Antes de executar este exemplo, substitua o ARN de chave de exemplo por um válido.

$  aws kms list-resource-tags --key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
      {
    "Tags": [
        {
            "TagKey": "Department",
            "TagValue": "IT"
        },
        {
            "TagKey": "Purpose",
            "TagValue": "Test"
        }
    ],
    "Truncated": false
}

Talvez você queira usar a operação ListResourceTags para obter todas as chaves do KMS na conta e região com uma etiqueta, chave de etiqueta ou valor de etiqueta específico. Para fazer isso, use os recursos de filtragem da sua linguagem de programação.

Por exemplo, o script Bash a seguir usa as ListResourceTags operações ListKeyse para obter todas as chaves KMS na conta e na região com uma chave de Project tag. Ambas as operações obtêm apenas a primeira página de resultados. Se você tiver várias chaves do KMS ou várias etiquetas, use os recursos de paginação da sua linguagem para obter todo o resultado de cada operação. Antes de executar esse exemplo, substitua os IDs de chave de exemplo por IDs válidos.

TARGET_TAG_KEY='Project'

for key in $(aws kms list-keys --query 'Keys[*].KeyId' --output text); do
  key_tags=$(aws kms list-resource-tags --key-id "$key" --query "Tags[?TagKey==\`$TARGET_TAG_KEY\`]")
  if [ "$key_tags" != "[]" ]; then
    echo "Key: $key"
    echo "$key_tags"
  fi
done

A saída é formatada como a saída do exemplo a seguir.

Key: 0987dcba-09fe-87dc-65ba-ab0987654321
[
    {
        "TagKey": "Project",
        "TagValue": "Gamma"
    }
]
Key: 1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d
[
    {
        "TagKey": "Project",
        "TagValue": "Alpha"
    }
]
Key: 0987ab65-43cd-21ef-09ab-87654321cdef
[
    {
        "TagKey": "Project",
        "TagValue": "Alpha"
    }
]