Como gerenciar aliases

Usuários autorizados podem criar, exibir e excluir aliases. Você também pode atualizar um alias, ou seja, associar um alias existente com uma chave do KMS diferente.

Criar um alias

É possível criar aliases no console do AWS KMS ou usando operações de API do AWS KMS.

O alias deve ser uma string contendo de 1 até 256 caracteres. Só pode conter caracteres alfanuméricos, barras (/), sublinhados (_) e traços (-). O nome do alias de uma chave gerenciada pelo cliente não pode começar com alias/aws/. O prefixo alias/aws/ está reservado para a Chave gerenciada pela AWS.

É possível criar um alias para uma nova chave do KMS ou para uma chave do KMS existente. Você pode adicionar um alias para que uma determinada chave do KMS seja usada em um projeto ou uma aplicação.

Criar um alias (console)

Quando você cria uma chave do KMS no AWS KMS, deve criar um alias para essa nova chave do KMS. Para criar um alias para uma chave do KMS existente, use a guia Aliases na página de detalhes da chave do KMS.

1. Faça login no AWS Management Console e abra o console do AWS Key Management Service (AWS KMS) em https://console.aws.amazon.com/kms.

2. Para alterar a Região da AWS, use o seletor de regiões no canto superior direito da página.

3. No painel de navegação, escolha Customer managed keys (Chaves gerenciadas pelo cliente). Não é possível gerenciar aliases para Chaves gerenciadas pela AWS ou Chaves pertencentes à AWS.

4. Na tabela, escolha o ID de chave ou alias da chave do KMS. Em seguida, na página de detalhes da chave do KMS, escolha a guia Aliases.

   Se uma chave do KMS tiver vários aliases, a coluna Aliases na tabela exibe um alias e um resumo de alias, como (Mais n). Escolher o resumo de aliases leva diretamente à guia Aliases na página de detalhes da chave do KMS.

5. Na guia Aliases, escolha Create alias (Criar alias). Insira um nome de alias e escolha Create alias (Criar alias).

   Importante

   Não inclua informações confidenciais ou sigilosas nesse campo. Esse campo pode ser exibido em texto simples em CloudTrail registros e outras saídas.

   nota

   Não adicione o prefixo alias/. O console adiciona isso para você automaticamente. Se você inserir alias/ExampleAlias, o nome do alias real será alias/alias/ExampleAlias.

Criar um alias (API do AWS KMS)

Para criar um alias, use a CreateAliasoperação. Diferentemente do processo de criação de chaves KMS no console, a CreateKeyoperação não cria um alias para uma nova chave KMS.

Importante

Não inclua informações confidenciais ou sigilosas nesse campo. Esse campo pode ser exibido em texto simples em CloudTrail registros e outras saídas.

Você pode usar a operação CreateAlias para criar um alias para uma nova chave do KMS sem alias. Você também pode usar a operação CreateAlias para adicionar um alias a qualquer chave do KMS existente ou para recriar um alias excluído acidentalmente.

Nas operações da API do AWS KMS, o nome do alias deve começar com alias/ seguido de um nome, como alias/ExampleAlias. O alias deve ser exclusivo na conta e na região da . Para encontrar os nomes de alias que já estão em uso, use a ListAliasesoperação. O nome do alias diferencia maiúsculas de minúsculas.

O TargetKeyId pode ser qualquer chave gerenciada pelo cliente na mesma Região da AWS. Para identificar a chave do KMS, use seu ID de chave ou ARN de chave. Não é possível usar outro alias.

O exemplo a seguir cria o alias example-key e o associa à chave do KMS especificada. Estes exemplos usam a AWS Command Line Interface (AWS CLI). Para obter exemplos em várias linguagens de programação, consulte Trabalhar com aliases.

$ aws kms create-alias \
    --alias-name alias/example-key \
    --target-key-id 1234abcd-12ab-34cd-56ef-1234567890ab

CreateAlias não retorna nenhuma saída. Para ver o novo alias, use a operação ListAliases. Para obter detalhes, consulte Exibir aliases (API AWS KMS).

Visualizar aliases

Aliases facilitam o reconhecimento de chaves do KMS no console do AWS KMS. Você pode visualizar os aliases de uma chave KMS no AWS KMS console ou usando a ListAliasesoperação. A DescribeKeyoperação, que retorna as propriedades de uma chave KMS, não inclui aliases.

Exibir aliases (console)

As páginas Customer managed keys (Chaves gerenciadas pelo cliente) e Chaves gerenciadas pela AWS no console do AWS KMS exibem o alias associado a cada chave do KMS. Você também pode pesquisar, classificar e filtrar chaves do KMS com base em seus aliases.

A imagem a seguir do console do AWS KMS mostra os aliases na página Chaves gerenciadas pelo cliente de uma conta demonstrativa. Como mostrado na imagem, algumas chaves do KMS não têm alias.

Quando uma chave do KMS tem diversos aliases, a coluna Aliases mostra um alias e um resumo de aliases (Mais n). O resumo de aliases mostra quantos aliases adicionais estão associados à chave do KMS e contém links para a exibição de todos os aliases da chave do KMS na guia Aliases.

A guia Aliases na página de detalhes de cada chave do KMS mostra o nome e o ARN de todos os aliases para a chave do KMS na região e na Conta da AWS. Também é possível utilizar a guia Aliases para criar aliases e excluir aliases.

Para encontrar o nome e o ARN de todos os aliases para a chave do KMS, use a guia Aliases.

• Para acessar diretamente a guia Aliases, na coluna Aliases, escolha o resumo do alias (Mais n). Um resumo de aliases será exibido somente se a chave do KMS tiver mais de um alias.

• Outra opção é escolher o alias ou o ID da chave do KMS (que abre a página de detalhes da chave do KMS) e escolher a guia Aliases. As guias estão na seção General configuration (Configuração geral).

A seguinte imagem mostra a guia Aliases para um exemplo de chave do KMS.

É possível usar o alias para reconhecer Chave gerenciada pela AWS, como mostra este exemplo da página Chaves gerenciadas pela AWS. Os aliases de Chaves gerenciadas pela AWS sempre têm o formato: aws/<service-name>. Por exemplo, o alias para a Chave gerenciada pela AWS do Amazon DynamoDB é aws/dynamodb.

Exibir aliases (API AWS KMS)

A ListAliasesoperação retorna o nome do alias e o ARN do alias da conta e da região. A saída inclui aliases para Chaves gerenciadas pela AWS e para chaves gerenciadas pelo cliente. Os aliases para Chaves gerenciadas pela AWS têm o formato aws/<service-name>, como aws/dynamodb.

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

$ 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/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/finance-project",
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/finance-project",
            "TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321",
            "CreationDate": 1604958290.014,
            "LastUpdatedDate": 1604958290.014
        },
        {
            "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
        }
    ]
}

Para obter todos os aliases associados a uma determinada chave do KMS, use o parâmetro opcional KeyId da operação ListAliases. O parâmetro KeyId usa o ID de chave ou o ARN de chave da chave do KMS.

Esse exemplo obtém todos os aliases associados à chave do KMS 0987dcba-09fe-87dc-65ba-ab0987654321.

$ aws kms list-aliases --key-id 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": "2018-01-20T15:23:10.194000-07:00",
            "LastUpdatedDate": "2018-01-20T15:23:10.194000-07:00"
        },
        {
            "AliasName": "alias/finance-project",
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/finance-project",
            "TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321",
            "CreationDate": 1604958290.014,
            "LastUpdatedDate": 1604958290.014
        }
    ]
}

O parâmetro KeyId não usa caracteres curinga, mas você pode usar os recursos da linguagem de programação para filtrar a resposta.

Por exemplo, o comando da AWS CLI a seguir obtém apenas os aliases de Chaves gerenciadas pela AWS.

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

O comando a seguir obtém apenas o alias access-key. O nome do alias diferencia maiúsculas de minúsculas.

$ aws kms list-aliases --query 'Aliases[?AliasName==`alias/access-key`]'
[
    {
        "AliasName": "alias/access-key",
        "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/access-key",
        "TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321",
        "CreationDate": "2018-01-20T15:23:10.194000-07:00",
        "LastUpdatedDate": "2018-01-20T15:23:10.194000-07:00"
    }
]

Atualizar aliases

Como um alias é um recurso independente, é possível alterar a chave do KMS associada a ele. Por exemplo, se o test-key alias estiver associado a uma chave KMS, você poderá usar a UpdateAliasoperação para associá-lo a uma chave KMS diferente. Esta é uma das várias maneiras de alternar manualmente uma chave do KMS sem alterar seu material de chave. Também é possível atualizar uma chave do KMS para que uma aplicação que estava usando uma determinada chave do KMS para novos recursos use agora uma diferente.

Não é possível atualizar um alias no console do AWS KMS. Além disso, você não pode usar UpdateAlias (nem qualquer outra operação) para alterar um nome de alias. Para alterar um nome de alias, exclua o alias atual e crie um novo para a chave do KMS.

Quando você atualiza um alias, a chave atual do KMS e a nova chave do KMS devem ser do mesmo tipo (ambas simétricas, assimétricas ou HMAC). Elas também devem ter o mesmo uso de chave (ENCRYPT_DECRYPT ou SIGN_VERIFY ou GENERATE_VERIFY_MAC). Essa restrição previne erros criptográficos no código que usa aliases.

O exemplo a seguir começa usando a ListAliasesoperação para mostrar que o test-key alias está atualmente associado à chave KMS. 1234abcd-12ab-34cd-56ef-1234567890ab

$ aws kms list-aliases --key-id 1234abcd-12ab-34cd-56ef-1234567890ab
{
    "Aliases": [
        {
            "AliasName": "alias/test-key",
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/test-key",
            "TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
            "CreationDate": 1593622000.191,
            "LastUpdatedDate": 1593622000.191
        }
    ]
}

Em seguida, ele usará a operação UpdateAlias para alterar a chave do KMS associada ao alias test-key para a chave do KMS 0987dcba-09fe-87dc-65ba-ab0987654321. Não é necessário especificar a chave do KMS atualmente associada, apenas a nova chave do KMS ("de destino"). O nome do alias diferencia maiúsculas de minúsculas.

$ aws kms update-alias --alias-name 'alias/test-key' --target-key-id 0987dcba-09fe-87dc-65ba-ab0987654321

Para verificar se o alias agora está associado à chave do KMS de destino, use a operação ListAliases novamente. Este comando de AWS CLI usa o parâmetro --query para obter apenas o alias test-key. Os campos TargetKeyId e LastUpdatedDate são atualizados.

$ aws kms list-aliases --query 'Aliases[?AliasName==`alias/test-key`]'
[
    {
        "AliasName": "alias/test-key",
        "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/test-key",
        "TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321",
        "CreationDate": 1593622000.191,
        "LastUpdatedDate": 1604958290.154
    }
]

Excluir um alias

Você pode excluir um alias no AWS KMS console ou usando a DeleteAliasoperação. Antes de excluir um alias, verifique se ele não está em uso. Embora a exclusão de um alias não afete a chave do KMS associada, ela pode criar problemas para qualquer aplicação que use esse alias. Se você excluir um alias por engano, poderá criar um novo alias com o mesmo nome e associá-lo à mesma chave do KMS ou a outra chave do KMS.

Se uma chave do KMS for excluída, todos os aliases associados a ela serão excluídos também.

Excluir aliases (console)

Para excluir um alias no console do AWS KMS, use a guia Aliases na página de detalhes da chave do KMS. É possível excluir vários aliases de uma chave do KMS ao mesmo tempo.

1. Faça login no AWS Management Console e abra o console do AWS Key Management Service (AWS KMS) em https://console.aws.amazon.com/kms.

2. Para alterar a Região da AWS, use o seletor de regiões no canto superior direito da página.

3. No painel de navegação, escolha Customer managed keys (Chaves gerenciadas pelo cliente). Não é possível gerenciar aliases para Chaves gerenciadas pela AWS ou Chaves pertencentes à AWS.

4. Na tabela, escolha o ID de chave ou alias da chave do KMS. Em seguida, na página de detalhes da chave do KMS, escolha a guia Aliases.

   Se uma chave do KMS tiver vários aliases, a coluna Aliases na tabela exibe um alias e um resumo de alias, como (Mais n). Escolher o resumo de aliases leva diretamente à guia Aliases na página de detalhes da chave do KMS.

5. Na guia Aliases, marque a caixa de seleção ao lado dos aliases que deseja excluir. Em seguida, selecione Excluir.

Excluir um alias (API do AWS KMS)

Para excluir um alias, use a DeleteAliasoperação. Essa operação exclui um alias por vez. O nome do alias faz distinção entre maiúsculas e minúsculas e deve ser precedido pelo prefixo alias/.

Por exemplo, o comando a seguir exclui o alias chamado test-key. Esse comando não retorna nenhuma saída.

$ aws kms delete-alias --alias-name alias/test-key

Para verificar se o alias foi excluído, use a ListAliasesoperação. O comando a seguir usa o parâmetro --query na AWS CLI para obter somente o alias test-key. Os colchetes vazios na resposta indicam que a resposta ListAliases não incluiu um alias test-key. Para eliminar os colchetes, use o parâmetro --output text e o valor.

$ aws kms list-aliases --query 'Aliases[?AliasName==`alias/test-key`]'
[]