Gerenciar um HSM Gerenciado usando a CLI do Azure

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:

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. Screenshot that shows an example of Try It for Azure Cloud Shell.
Acesse https://shell.azure.com ou selecione o botão Iniciar o Cloud Shell para abri-lo no navegador. Button to launch Azure Cloud Shell.
Selecione o botão Cloud Shell na barra de menus no canto superior direito do portal do Azure. Screenshot that shows the Cloud Shell button in the Azure portal

Para usar o Azure Cloud Shell:

  1. Inicie o Cloud Shell.

  2. Selecione o botão Copiar em um bloco de código (ou bloco de comando) para copiar o código ou o comando.

  3. 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.

  4. Pressione Enter para executar o código ou comando.

Entrar no Azure

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 --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