Avvio rapido: libreria client di HSM gestito di Azure Key Vault per JavaScript

Inizia a utilizzare la libreria client Azure Key Vault Managed HSM per JavaScript. Il modulo di protezione hardware gestito è un servizio cloud completamente gestito, a disponibilità elevata, a tenant singolo e conforme agli standard che consente di proteggere le chiavi crittografiche per le applicazioni cloud, usando moduli di protezione hardware convalidati FIPS 140-3 di livello 3 . Per ulteriori informazioni sull'HSM gestito, consultare la Panoramica.

In questa guida introduttiva si apprenderà come accedere ed eseguire operazioni di crittografia sulle chiavi in un modulo di protezione hardware gestito usando la libreria client JavaScript.

Risorse della libreria client dell'HSM gestito:

documentazione di riferimento API | Codice sorgente della libreria | Package (npm)

Prerequisiti

• Sottoscrizione Azure. Creane uno gratis.
• Un modulo HSM gestito, approvvigionato e attivato. Vedere Avvio rapido: Effettuare il provisioning di un HSM gestito tramite l'interfaccia della riga di comando di Azure.
• Una chiave creata nel tuo HSM gestito. Consultare Gestione delle chiavi in un Hardware Security Module (HSM) gestito.
• Una risorsa Azure con un'identità gestita (ad esempio una macchina virtuale, un servizio app o una funzione Azure) o interfaccia della riga di comando di Azure per lo sviluppo locale.
• All'identità gestita deve essere assegnato il ruolo RBAC locale appropriato di HSM gestito. See Proteggere l'accesso ai moduli di protezione hardware gestiti.

• Node.js 18 LTS o versioni successive

Configurare l'ambiente locale

Questa guida introduttiva usa la libreria di identità Azure con interfaccia della riga di comando di Azure per eseguire l'autenticazione ai servizi di Azure. Gli sviluppatori possono anche usare Visual Studio Code per autenticare le chiamate. Per altre informazioni, vedere Authenticate the client with Azure Identity client library.

Accedere a Azure

Eseguire il az login comando per accedere:

az login

Creare una cartella del progetto e inizializzare

1. Creare una cartella progetto e accedervi.

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

2. Inizializzare il progetto:

   npm init -y
   

Installare i pacchetti

Installare le librerie client di identità di Azure e delle chiavi di Key Vault.

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

Creare il codice di esempio

Creare un file denominato index.js con il codice seguente. Sostituisci <hsm-name> con il nome del tuo HSM gestito e <key-name> con un nome di chiave esistente.

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);
});

Eseguire l'applicazione

Eseguire l'applicazione:

node index.js

L'output dovrebbe essere simile al seguente:

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!

Informazioni sul codice

Autenticazione con DefaultAzureCredential

DefaultAzureCredential seleziona automaticamente le credenziali appropriate in base all'ambiente:

La verifica delle credenziali controlla queste fonti in ordine:

1. Variabili di ambiente
2. Identità del carico di lavoro
3. Identità gestita
4. interfaccia della riga di comando di Azure
5. Azure PowerShell
6. credenziali di Visual Studio/VS Code

Per i carichi di lavoro di produzione in Azure, le identità gestite sono fortemente consigliate perché eliminano completamente la gestione delle credenziali.

Operazioni chiave

La KeyClient classe fornisce metodi per:

• Creare, ottenere, aggiornare ed eliminare chiavi
• Elencare le chiavi e le versioni delle chiavi
• Eseguire il backup e il ripristino delle chiavi

La CryptographyClient classe fornisce operazioni di crittografia:

• Crittografare e decrittografare i dati
• Firmare e verificare le firme
• Eseguire e annullare il wrapping delle chiavi

Assegnare ruoli di HSM gestito

Per consentire all'applicazione di accedere alle chiavi, assegnare il ruolo di Controllo degli accessi in base al ruolo locale di HSM gestito corretto alla propria identità gestita. Sostituire <vm-name>, <resource-group>e <hsm-name> con i valori effettivi.

# 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

Per altre informazioni su ruoli e autorizzazioni, vedere Ruoli predefiniti RBAC locali di HSM gestito.

Pulire le risorse

Quando non sono più necessari, eliminare il gruppo di risorse e tutte le risorse correlate:

az group delete --name <resource-group>

Passaggi successivi

• Informazioni su Accesso sicuro ai moduli di sicurezza hardware gestiti
• Configurare la rotazione automatica delle chiavi
• Rivedere le migliori prassi per il Managed HSM
• Informazioni sui ruoli predefiniti RBAC locali di HSM gestito