Compartilhar via

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 saber como gerenciar um cofre, consulte Gerenciar o Key Vault usando a CLI do Azure.

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

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 você pode usar por meio do navegador. Você pode usar o Bash ou o PowerShell com o Cloud Shell para trabalhar com os serviços do Azure. Você pode usar os comandos pré-instalados do Cloud Shell para executar o código neste artigo, sem precisar instalar nada em seu ambiente local.

Para iniciar o Azure Cloud Shell:

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

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 o comando na sessão do Cloud Shell selecionando Ctrl+Shift+V no Windows e Linux ou selecionando Cmd+Shift+V no macOS.

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

Entrar no Azure

Entre no Azure usando a CLI digitando:

az login

Para obter mais informações sobre as opções de entrada por meio da CLI, consulte entrar com a CLI do Azure

Observação

Todos os comandos a seguir mostram dois métodos de uso. Um usando o parâmetro --hsm-name e --name (para o nome da chave) e um usando o parâmetro --id, onde você pode especificar a URL inteira, incluindo o nome da chave, onde 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

Não é possível exportar uma chave gerada ou importada para o HSM Gerenciado. A única exceção à regra de não exportação é quando você cria uma chave com uma política de liberação de chave específica. Essa política permite que a chave seja exportada apenas para ambientes de computação confidenciais confiáveis (enclaves seguros) definidos explicitamente. Essa funcionalidade de exportação limitada foi projetada para cenários de computação segura específicos e não é igual a uma exportação de chave de uso geral. 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

Este exemplo mostra como criar uma chave RSA de 3072 bits que é usada apenas para operações wrapKey, 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 (se uma chave assimétrica) ou o material da chave (se uma 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

Este exemplo mostra como criar uma chave simétrica de 256 bits que será usada apenas para criptografar e descriptografar operações (--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 az keyvault key show o comando para exibir atributos, versões e marcas para 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. A exclusão reversível está sempre ativada. Portanto, uma chave excluída permanece no estado excluído e pode ser recuperada até que o número de dias de retenção tenha passado, momento em que a chave é limpa (excluída permanentemente) sem nenhuma recuperação possível.

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 restaurar uma chave usando o parâmetro --id durante a recuperação de uma chave excluída, deverá observar o valor recoveryId da chave excluída obtida 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 é limpa automaticamente quando o período de retenção é passado.

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