Gerenciar um HSM gerenciado usando a CLI do Azure

  • Artigo

Nota

O Key Vault suporta dois tipos de recursos: cofres e HSMs geridos. Este artigo é sobre HSM gerenciado. Se você quiser saber como gerenciar um cofre, consulte Gerenciar cofre de chaves usando a CLI do Azure.

Para obter uma visão geral do HSM gerenciado, consulte O que é o HSM gerenciado?

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

Pré-requisitos

Para concluir as etapas neste artigo, você deve ter os seguintes itens:

Azure Cloud Shell

O Azure aloja o Azure Cloud Shell, um ambiente de shell interativo que pode utilizar através do seu browser. Pode utilizar 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/Ligação
Selecione Experimentar no canto superior direito de um código ou bloco de comandos. Selecionar Experimentar não copia automaticamente o código ou comando para o Cloud Shell. Screenshot that shows an example of Try It for Azure Cloud Shell.
Aceda a https://shell.azure.com ou selecione o botão Iniciar Cloud Shell para abrir o Cloud Shell no browser. Button to launch Azure Cloud Shell.
Selecione o botão Cloud Shell na barra de menus, na parte direita 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 comando.

  3. Cole o código ou comando na sessão do Cloud Shell selecionando Ctrl+Shift+V no Windows e Linux ou selecionando Cmd+Shift+V no macOS.

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

Iniciar sessão 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, consulte Entrar com a CLI do Azure

Nota

Todos os comandos abaixo mostram dois métodos de uso. Um usando os parâmetros --hsm-name e --name (para nome da chave) e outro usando o parâmetro --id onde você pode especificar a url inteira, incluindo o nome da chave, quando apropriado. Este último método é útil quando o chamador (um usuário ou um aplicativo) não tem acesso de leitura no plano de controle e apenas acesso restrito no plano de dados.

Nota

Algumas interações com material chave exigem permissões RBAC locais específicas. Para obter uma lista completa das funções e permissões internas do RBAC local, consulte Funções internas do RBAC local do HSM gerenciado. Para atribuir essas permissões a um usuário, consulte Acesso seguro aos HSMs gerenciados

Criar uma chave HSM

Nota

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

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

Criar uma chave RSA

O exemplo abaixo mostra como criar uma chave RSA de 3072 bits que será 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 get operação retorna apenas a chave pública e os atributos de chave. Ele não retorna a chave privada (no caso de chave assimétrica, ou o material da chave (no caso de chave simétrica).

Criar uma chave EC

O exemplo abaixo mostra como criar uma chave EC com curva P-256 que será usada apenas para operações de sinal e verificação (--ops) e tem duas tags, usage e appname. As tags ajudam a adicionar metadados adicionais à chave para rastreamento 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 abaixo 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

Ver principais atributos e etiquetas

Use az keyvault key show o comando para exibir atributos, versões e tags 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 az keyvault key list o comando 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/

Eliminar uma chave

Use az keyvault key delete o comando para excluir uma chave de um HSM gerenciado. Observe que o soft-delete está sempre ativado. Portanto, uma chave excluída permanecerá no estado excluído e poderá ser recuperada até que o número de dias de retenção tenha passado, quando a chave será limpa (excluída permanentemente) sem 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 az keyvault key list-deleted o comando para listar todas as chaves no estado excluído no 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 (anular eliminação de) uma chave eliminada

Use az keyvault key list-deleted o comando para listar todas as chaves no estado excluído no HSM gerenciado. Se você precisar recuperar (cancelar a exclusão) de uma chave usando o parâmetro --id durante a recuperação de uma chave excluída, deverá anotar o recoveryId valor da chave excluída obtida do az keyvault key list-deleted comando.

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 az keyvault key purge o comando para limpar (excluir permanentemente) uma chave.

Nota

Se o HSM gerenciado tiver a proteção de limpeza habilitada, a operação de limpeza não será permitida. A chave será automaticamente limpa quando o período de retenção tiver 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 única

Use az keyvault key backup para criar um backup de chave. O arquivo de backup é um blob criptografado criptograficamente vinculado 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ínio 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 única chave a partir do backup

Use az keyvault key restore para restaurar uma única chave. O HSM de origem onde o backup foi criado deve compartilhar o mesmo domínio de segurança que o HSM de destino onde a chave está sendo restaurada.

Nota

A restauração não terá êxito se uma chave com o mesmo nome existir no 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 ficheiro

Use az keyvault key import o comando para importar uma chave (somente RSA e EC) de um arquivo. O arquivo de certificado deve ter chave privada e deve usar a codificação PEM (conforme definido nas RFCs 1421, 1422, 1423, 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, consulte Importar chaves protegidas por HSM para o HSM gerenciado (BYOK)

Próximos passos