Gerenciar um HSM gerenciado usando a CLI do Azure
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:
- Uma subscrição do Microsoft Azure. Se não tiver uma, pode inscrever-se numa avaliação gratuita.
- A CLI do Azure versão 2.25.0 ou posterior. Executar
az --version
para localizar a versão. Se precisar de instalar ou atualizar, veja Instalar a CLI do Azure. - Um HSM gerenciado em sua assinatura. Consulte Guia de início rápido: provisionar e ativar um HSM gerenciado usando a CLI do Azure para provisionar e ativar um HSM gerenciado.
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. | |
Aceda a https://shell.azure.com ou selecione o botão Iniciar Cloud Shell para abrir o Cloud Shell no browser. | |
Selecione o botão Cloud Shell na barra de menus, na parte direita 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 comando.
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.
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 --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, consulte Importar chaves protegidas por HSM para o HSM gerenciado (BYOK)
Próximos passos
- Para obter a referência completa da CLI do Azure para comandos do cofre de chaves, consulte Referência da CLI do Cofre da Chave.
- Para obter referências de programação, consulte o guia do desenvolvedor do Azure Key Vault
- Saiba mais sobre o gerenciamento de funções do HSM gerenciado
- Saiba mais sobre as práticas recomendadas de HSM gerenciado