Gerenciar um HSM Gerenciado usando a CLI do Azure

Artigo
08/08/2024

Observação

O Key Vault é compatível com dois tipos de recurso: cofres e HSMs Gerenciados. Este artigo é sobre o HSM Gerenciado. Se você quiser aprender como gerenciar um cofre, confira Gerenciar o Key Vault usando a CLI do Azure.

Para obter uma visão geral do HSM Gerenciado, confira O que é o HSM Gerenciado?

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

Pré-requisitos

Para concluir as etapas deste artigo, você precisará ter os seguintes itens:

Uma assinatura do Microsoft Azure. Se você não tiver uma, pode se inscrever e fazer uma avaliação gratuita.
A CLI do Azure versão 2.25.0 ou posterior. Execute az --version para encontrar a versão. Se você precisar instalar ou atualizar, confira Instalar a CLI do Azure.
Um HSM Gerenciado na sua assinatura. Confira Início Rápido: Provisione e ative um HSM Gerenciado usando a CLI do Azure para provisionar e ativar um HSM Gerenciado.

Azure Cloud Shell

O Azure hospeda o Azure Cloud Shell, um ambiente de shell interativo que pode ser usado por meio do navegador. É possível usar o bash ou o PowerShell com o Cloud Shell para trabalhar com os serviços do Azure. É possível usar os comandos pré-instalados do Cloud Shell para executar o código neste artigo, sem precisar instalar nada no seu ambiente local.

Para iniciar o Azure Cloud Shell:

Opção	Exemplo/Link
Selecione Experimentar no canto superior direito de um bloco de código ou de comando. Selecionar Experimentar não copia automaticamente o código nem o comando para o Cloud Shell.
Acesse https://shell.azure.com ou selecione o botão Iniciar o Cloud Shell para abri-lo no navegador.
Selecione o botão Cloud Shell na barra de menus no canto superior direito do portal do Azure.

Para usar o Azure Cloud Shell:

Inicie o Cloud Shell.
Selecione o botão Copiar em um bloco de código (ou bloco de comando) para copiar o código ou o comando.
Cole o código ou comando na sessão do Cloud Shell selecionando Ctrl+Shift+V no Windows e no Linux, ou selecionando Cmd+Shift+V no macOS.
Pressione Enter para executar o código ou comando.

Para entrar no Azure usando a CLI, você pode digitar:

az login

Para obter mais informações sobre as opções de logon por meio da CLI, confira Entrar com a CLI do Azure

Observação

Todos os comandos a seguir mostram dois métodos de uso. Alguém usando os parâmetros de --hsm-name e --name (para nome da chave) e outro usando os parâmetros --id em que você pode especificar toda a URL, incluindo o nome da chave, quando apropriado. O último método é útil quando o chamador (seja um usuário ou um aplicativo) não tem acesso de leitura ao plano de controle e somente acesso restrito ao plano de dados.

Observação

Algumas interações com o material da chave exigem permissões específicas de RBAC Local. Para obter uma lista completa de funções e permissões RBAC Locais internas, consulte Funções internas RBAC locais do HSM Gerenciado. Para atribuir essas permissões a um usuário, confira Proteger o acesso aos HSMs gerenciados

Criar uma chave HSM

Observação

A chave gerada ou importada para o HSM gerenciado não pode ser exportada. Consulte as melhores práticas para portabilidade e durabilidade principais.

Use o comando az keyvault key create para criar uma chave.

Criar uma chave RSA

O exemplo a seguir mostra como criar uma chave RSA de 3.072 bits que será usada somente para as operações wrapKey e unwrapKey (--ops).

az keyvault key create --hsm-name ContosoMHSM --name myrsakey --ops wrapKey unwrapKey --kty RSA-HSM --size 3072

## OR
# Note the key name (myrsakey) in the URI

az keyvault key create --id https://ContosoMHSM.managedhsm.azure.net/keys/myrsakey --ops wrapKey unwrapKey --kty RSA-HSM --size 3072

Observe que a operação get retorna apenas a chave pública e os atributos de chave. Ela não retorna a chave privada (em caso de chave assimétrica) ou o material da chave (em caso de chave simétrica).

Criar uma chave do EC

O exemplo a seguir mostra como criar uma chave do EC com curva P-256 que será usada somente para assinar e verificar operações (--ops) e que tem duas marcações, usage e appname. As marcações ajudam na inclusão de metadados adicionais à chave para fins de acompanhamento e gerenciamento.

az keyvault key create --hsm-name ContosoMHSM --name myec256key --ops sign verify  --tags ‘usage=signing] appname=myapp’ --kty EC-HSM --curve P-256

## OR
# Note the key name (myec256key) in the URI

az keyvault key create --id https://ContosoMHSM.managedhsm.azure.net/keys/myec256key --ops sign verify  --tags ‘usage=signing] appname=myapp’ --kty EC-HSM --curve P-256

Criar uma chave simétrica de 256 bits

O exemplo a seguir mostra como criar uma chave simétrica de 256 bits que será usada somente para as operações encrypt e decrypt (--ops).

az keyvault key create --hsm-name ContosoMHSM --name myaeskey --ops encrypt decrypt  --tags --kty oct-HSM --size 256

## OR
# Note the key name (myaeskey) in the URI

az keyvault key create --id https://ContosoMHSM.managedhsm.azure.net/keys/myaeskey --ops encrypt decrypt  --tags ‘usage=signing] appname=myapp’ --kty oct-HSM --size 256

Visualizar atributos de chave e marcações

Use o comando az keyvault key show para visualizar os atributos, as versões e as marcações de uma chave.

az keyvault key show --hsm-name ContosoHSM --name myrsakey

## OR
# Note the key name (myaeskey) in the URI

az keyvault key show --id https://ContosoMHSM.managedhsm.azure.net/keys/myrsakey

Listar chaves

Use o comando az keyvault key list para listar todas as chaves dentro de um HSM Gerenciado.

az keyvault key list --hsm-name ContosoHSM

## OR
# use full URI

az keyvault key list --id https://ContosoMHSM.managedhsm.azure.net/

Excluir uma chave

Use o comando az keyvault key delete para excluir uma chave de um HSM Gerenciado. Observe que a exclusão reversível está sempre ativada. Portanto, uma chave excluída permanecerá no estado de exclusão e poderá ser recuperada até expirar o número de dias de retenção, quando a chave será limpa (excluída permanentemente) e não haverá mais a possibilidade de recuperação.

az keyvault key delete --hsm-name ContosoHSM --name myrsakey

## OR
# Note the key name (myaeskey) in the URI

az keyvault key delete --id https://ContosoMHSM.managedhsm.azure.net/keys/myrsakey

Listar chaves excluídas

Use o comando az keyvault key list-deleted para listar todas as chaves em estado de exclusão do seu HSM Gerenciado.

az keyvault key list-deleted --hsm-name ContosoHSM

## OR
# use full URI

az keyvault key list-deleted --id https://ContosoMHSM.managedhsm.azure.net/

Recuperar (restaurar) uma chave excluída

Use o comando az keyvault key list-deleted para listar todas as chaves em estado de exclusão do seu HSM Gerenciado. Se você precisar recuperar (restaurar) uma chave usando o parâmetro --id nessa operação, será necessário observar o valor recoveryId da chave excluída, obtido por meio do comando az keyvault key list-deleted.

az keyvault key recover --hsm-name ContosoHSM --name myrsakey

## OR
# Note the key name (myaeskey) in the URI

az keyvault key recover --id https://ContosoMHSM.managedhsm.azure.net/deletedKeys/myrsakey

Limpar (excluir permanentemente) uma chave

Use o comando az keyvault key purge para limpar (excluir permanentemente) uma chave.

Observação

Se o HSM Gerenciado tiver a proteção de limpeza habilitada, a operação de limpeza não será permitida. A chave será limpa automaticamente ao expirar o período de retenção.

az keyvault key purge --hsm-name ContosoHSM --name myrsakey

## OR
# Note the key name (myaeskey) in the URI

az keyvault key purge --id https://ContosoMHSM.managedhsm.azure.net/deletedKeys/myrsakey

Criar um backup de chave individual

Use az keyvault key backup para criar um backup de chave. O arquivo de backup é um blob criptografado ligado criptograficamente ao Domínio de Segurança do HSM de origem. Ele só pode ser restaurado em HSMs que compartilham o mesmo Domínio de Segurança. Leia mais sobre Domínios de Segurança.

az keyvault key backup --hsm-name ContosoHSM --name myrsakey --file myrsakey.backup

## OR
# Note the key name (myaeskey) in the URI

az keyvault key backup --id https://ContosoMHSM.managedhsm.azure.net/deletedKeys/myrsakey  --file myrsakey.backup

Restaurar uma chave individual do backup

Use az keyvault key restore para restaurar uma chave individual. O HSM de origem em que o backup foi criado deve compartilhar o mesmo Domínio de Segurança que o HSM de destino em que a chave está sendo restaurada.

Observação

A restauração não será bem sucedida se já houver uma chave com o mesmo nome em estado ativo ou excluído.

az keyvault key restore --hsm-name ContosoHSM --name myrsakey --file myrsakey.backup

## OR
# Note the key name (myaeskey) in the URI

az keyvault key restore --id https://ContosoMHSM.managedhsm.azure.net/deletedKeys/myrsakey --file myrsakey.backup

Importar uma chave de um arquivo

Use o comando az keyvault key import para importar uma chave (somente RSA e EC) de um arquivo. O arquivo de certificado deve ter uma chave privada e deve usar a codificação PEM (conforme definido nas RFCs 1421, 1422, 1423 e 1424).

az keyvault key import --hsm-name ContosoHSM --name myrsakey --pem-file mycert.key --pem-password 'mypassword'

## OR
# Note the key name (myaeskey) in the URI

az keyvault key recover --id https://ContosoMHSM.managedhsm.azure.net/deletedKeys/myrsakey --pem-file mycert.key --password 'mypassword'

Para importar uma chave do HSM local para o HSM gerenciado, confira Importar chaves protegidas por HSM para o HSM Gerenciado (BYOK)

Próximas etapas

Para obter a referência completa da CLI do Azure de comandos do cofre de chaves, consulte referência da CLI do Key Vault.
Para referências de programação, veja o Guia do desenvolvedor do Azure Key Vault
Saiba mais sobre o gerenciamento de funções do HSM Gerenciado
Saiba mais sobre as melhores práticas do HSM Gerenciado

Compartilhar via

Gerenciar um HSM Gerenciado usando a CLI do Azure

Pré-requisitos

Azure Cloud Shell

Criar uma chave HSM

Criar uma chave RSA

Criar uma chave do EC

Criar uma chave simétrica de 256 bits

Visualizar atributos de chave e marcações

Listar chaves

Excluir uma chave

Listar chaves excluídas

Recuperar (restaurar) uma chave excluída

Limpar (excluir permanentemente) uma chave

Criar um backup de chave individual

Restaurar uma chave individual do backup

Importar uma chave de um arquivo

Próximas etapas

Comentários

Recursos adicionais

Compartilhar via

Gerenciar um HSM Gerenciado usando a CLI do Azure

Pré-requisitos

Azure Cloud Shell

Entrar no Azure

Criar uma chave HSM

Criar uma chave RSA

Criar uma chave do EC

Criar uma chave simétrica de 256 bits

Visualizar atributos de chave e marcações

Listar chaves

Excluir uma chave

Listar chaves excluídas

Recuperar (restaurar) uma chave excluída

Limpar (excluir permanentemente) uma chave

Criar um backup de chave individual

Restaurar uma chave individual do backup

Importar uma chave de um arquivo

Próximas etapas

Comentários

Recursos adicionais