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 a uma chave diferenteKMS.

Criar um alias

Você pode criar aliases no AWS KMS console ou usando AWS KMS APIoperações.

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 alias/aws/ prefixo é reservado para Chaves gerenciadas pela AWS.

Você pode criar um alias para uma nova KMS chave ou para uma KMS chave existente. Você pode adicionar um alias para que uma KMS chave específica seja usada em um projeto ou aplicativo.

Criar um alias (console)

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

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

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

3. No painel de navegação, escolha Chaves gerenciadas pelo cliente. Você não pode gerenciar aliases para Chaves gerenciadas pela AWS ou Chaves pertencentes à AWS.

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

   Se uma KMS chave tiver vários aliases, a coluna Aliases na tabela exibirá um alias e um resumo do alias, como (+ n mais). A escolha do resumo do alias leva você diretamente para a guia Aliases na página de detalhes da KMS chave.

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.

Crie um alias (AWS KMS API)

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

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 CreateAlias operação para criar um alias para uma nova KMS chave sem alias. Você também pode usar a CreateAlias operação para adicionar um alias a qualquer KMS chave existente ou para recriar um alias que foi excluído acidentalmente.

No painel, AWS KMS APIoperações, o nome do alias deve começar alias/ seguido por um nome, comoalias/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.

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

O exemplo a seguir cria o example-key alias e o associa à chave especificadaKMS. Esses exemplos usam o AWS Command Line Interface (AWS CLI). Para obter exemplos em várias linguagens de programação, consulteUse CreateAlias com um AWS SDKou CLI.

$ 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 Visualizando aliases (AWS KMS API).

Visualizar aliases

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

Exibir aliases (console)

O cliente gerenciou as chaves e Chaves gerenciadas pela AWSpáginas no AWS KMS o console exibe o alias associado a cada KMS chave. Você também pode pesquisar, classificar e filtrar KMS chaves com base em seus aliases.

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

Quando uma KMS chave tem vários aliases, a coluna Aliases exibe um alias e um resumo do alias (+ n mais). O resumo do alias mostra quantos aliases adicionais estão associados à KMS chave e links para a exibição de todos os aliases da KMS chave na guia Aliases.

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

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

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

• Ou escolha o alias ou o ID da KMS chave (que abre a página de detalhes da KMS chave) e, em seguida, escolha a guia Aliases. As guias estão na seção General configuration (Configuração geral).

A imagem a seguir mostra a guia Aliases de um exemplo de KMS chave.

Você pode usar o alias para reconhecer um Chave gerenciada pela AWS, conforme mostrado neste exemplo Chaves gerenciadas pela AWSpágina. Os apelidos para Chaves gerenciadas pela AWS sempre tenha o formato:aws/<service-name>. Por exemplo, o alias do Chave gerenciada pela AWS para o Amazon DynamoDB é. aws/dynamodb

Visualizando aliases (AWS KMS API)

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

A resposta também pode incluir aliases sem campo TargetKeyId. Esses são aliases predefinidos que AWS foi criado, mas ainda não está associado a uma KMS chave.

$ 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 KMS chave específica, use o KeyId parâmetro opcional da ListAliases operação. O KeyId parâmetro usa o ID da chave ou a chave ARN da KMS chave.

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

$ 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 seguinte AWS CLI o comando obtém somente os aliases para 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, você pode alterar a KMS chave associada a um alias. Por exemplo, se o test-key alias estiver associado a uma KMS chave, você poderá usar a UpdateAliasoperação para associá-lo a uma KMS chave diferente. Essa é uma das várias maneiras de girar manualmente uma KMS chave sem alterar o material da chave. Você também pode atualizar uma KMS chave para que um aplicativo que estava usando uma KMS chave para novos recursos agora use uma KMS chave diferente.

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

Quando você atualiza um alias, a KMS chave atual e a nova KMS chave devem ser do mesmo tipo (simétrica ou assimétrica ou). HMAC Eles também devem ter o mesmo uso de chave (ENCRYPT_DECRYPTou 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 à KMS chave1234abcd-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 usa a UpdateAlias operação para alterar a KMS chave associada ao test-key alias para KMS chave0987dcba-09fe-87dc-65ba-ab0987654321. Você não precisa especificar a KMS chave atualmente associada, somente a nova KMS chave (“alvo”). 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 à KMS chave de destino, use a ListAliases operação novamente. Esse AWS CLI O comando usa o --query parâmetro para obter somente o test-key alias. 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 KMS chave associada, ela pode criar problemas para qualquer aplicativo que use o alias. Se você excluir um alias por engano, poderá criar um novo alias com o mesmo nome e associá-lo à mesma chave ou a uma chave diferenteKMS.

Se você excluir uma KMS chave, todos os aliases associados a essa KMS chave serão excluídos.

Excluir aliases (console)

Para excluir um alias no AWS KMS console, use a guia Aliases na página de detalhes da KMS chave. Você pode excluir vários aliases de uma KMS chave ao mesmo tempo.

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

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

3. No painel de navegação, escolha Chaves gerenciadas pelo cliente. Você não pode gerenciar aliases para Chaves gerenciadas pela AWS ou Chaves pertencentes à AWS.

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

   Se uma KMS chave tiver vários aliases, a coluna Aliases na tabela exibirá um alias e um resumo do alias, como (+ n mais). A escolha do resumo do alias leva você diretamente para a guia Aliases na página de detalhes da KMS chave.

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

Excluir um alias (AWS KMS API)

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 --query parâmetro no AWS CLI para obter somente o test-key alias. 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`]'
[]