Compartilhar via

Início Rápido: biblioteca de clientes do HSM gerenciado Azure Key Vault para JavaScript

Comece a usar a biblioteca de clientes do Azure Key Vault Managed HSM para JavaScript. O HSM Gerenciado é um serviço de nuvem de gerenciamento completo, altamente disponível, de locatário único e compatível com padrões que permite proteger chaves criptográficas para seus aplicativos de nuvem, com HSMs validados pelo FIPS 140-3 Nível 3. Para obter mais informações sobre hsm gerenciado, examine a visão geral.

Neste início rápido, você aprenderá a acessar e executar operações criptográficas em chaves em um HSM gerenciado usando a biblioteca de clientes JavaScript.

Recursos gerenciados da biblioteca de clientes HSM:

API reference documentation | Library source code | Package (npm)

Pré-requisitos

Configurar o ambiente local

Este início rápido usa a biblioteca Azure Identity com CLI do Azure para se autenticar em serviços de Azure. Os desenvolvedores também podem usar Visual Studio Code para autenticar suas chamadas. Para obter mais informações, consulte Authenticate the client with Azure Identity client library.

Entrar no Azure

Execute o az login comando para entrar:

az login

Criar uma pasta de projeto e inicializar

  1. Crie uma pasta de projeto e navegue até ela:

    mkdir mhsm-js-app && cd mhsm-js-app

  2. Inicialize o projeto:

    npm init -y

Instalar os pacotes

Instale as bibliotecas de cliente Azure Identity e Key Vault Keys:

npm install @azure/identity @azure/keyvault-keys

Criar o código de exemplo

Crie um arquivo nomeado index.js com o código a seguir. Substitua <hsm-name> pelo nome do HSM Gerenciado e <key-name> por um nome de chave existente.

const { DefaultAzureCredential } = require("@azure/identity");
const { KeyClient, CryptographyClient } = require("@azure/keyvault-keys");

async function main() {
    // Use DefaultAzureCredential for automatic credential selection
    const credential = new DefaultAzureCredential();

    // Connect to Managed HSM - replace with your HSM URI
    const hsmUri = "https://<hsm-name>.managedhsm.azure.net";
    const keyClient = new KeyClient(hsmUri, credential);

    // Get a key reference
    const keyName = "<key-name>";
    console.log(`Retrieving key '${keyName}' from Managed HSM...`);
    const key = await keyClient.getKey(keyName);
    console.log(`Key retrieved. Key type: ${key.keyType}`);

    // Perform cryptographic operations
    const cryptoClient = new CryptographyClient(key, credential);

    // Encrypt data
    const plaintext = Buffer.from("Hello, Managed HSM!");
    console.log(`\nOriginal text: ${plaintext.toString()}`);

    const encryptResult = await cryptoClient.encrypt("RSA-OAEP-256", plaintext);
    console.log(`Encrypted (base64): ${encryptResult.result.toString("base64").substring(0, 64)}...`);

    // Decrypt data
    const decryptResult = await cryptoClient.decrypt("RSA-OAEP-256", encryptResult.result);
    console.log(`Decrypted text: ${decryptResult.result.toString()}`);

    console.log("\nDone!");
}

main().catch((error) => {
    console.error("An error occurred:", error);
    process.exit(1);
});

Executar o aplicativo

Execute o aplicativo:

node index.js

Você deverá ver uma saída semelhante a:

Retrieving key 'myrsakey' from Managed HSM...
Key retrieved. Key type: RSA-HSM

Original text: Hello, Managed HSM!
Encrypted (base64): NWE4ZjNiMmMxZDRlNWY2YTdiOGM5ZDBlMWYyYTNiNGM...
Decrypted text: Hello, Managed HSM!

Done!

Compreender o código

Autenticação com DefaultAzureCredential

DefaultAzureCredential seleciona automaticamente a credencial apropriada com base em seu ambiente:

Ambiente Credencial usada
Azure VMs, Serviço de Aplicativo, Funções Identidade gerenciada atribuída pelo sistema ou pelo usuário
Serviço de Kubernetes do Azure Identidade da carga de trabalho
Desenvolvimento local credenciais de CLI do Azure, Visual Studio ou VS Code
Pipelines de CI/CD Entidade de serviço ou federação de identidade da carga de trabalho

A credencial verifica essas fontes na ordem:

  1. Variáveis de ambiente
  2. Identidade da carga de trabalho
  3. Identidade gerenciada
  4. CLI do Azure
  5. Azure PowerShell
  6. credenciais de Visual Studio/VS Code

Para cargas de trabalho de produção em Azure, as identidades gerenciadas são altamente recomendadas porque eliminam totalmente o gerenciamento de credenciais.

Operações principais

A KeyClient classe fornece métodos para:

  • Criar, obter, atualizar e excluir chaves
  • Listar chaves e versões das chaves
  • Chaves de backup e restauração

A CryptographyClient classe fornece operações criptográficas:

  • Criptografar e descriptografar dados
  • Assinar e verificar assinaturas
  • Empacotar e desempacotar as chaves

Atribuir as funções do HSM gerenciado

Para que seu aplicativo acesse chaves, atribua a função RBAC local do HSM gerenciado apropriada à sua identidade gerenciada. Substitua <vm-name>, <resource-group>e <hsm-name> com seus valores reais.

# Get the principal ID of your managed identity
principalId=$(az vm identity show --name <vm-name> --resource-group <resource-group> --query principalId -o tsv)

# Assign the Crypto User role for key operations
az keyvault role assignment create \
    --hsm-name <hsm-name> \
    --role "Managed HSM Crypto User" \
    --assignee $principalId \
    --scope /keys

Para obter mais informações sobre as funções e as permissões, consulte Funções internas do RBAC local do HSM gerenciado.

Limpar os recursos

Quando não for mais necessário, exclua o grupo de recursos e todos os recursos relacionados:

az group delete --name <resource-group>

Aviso

Excluir o grupo de recursos coloca o HSM gerenciado em um estado de exclusão reversível. O HSM gerenciado continuará sendo cobrado até ser purgado. Consulte Exclusão reversível e proteção contra limpeza do HSM gerenciado

Próximas Etapas 

  • Last updated on