Rychlý start: klientská knihovna pro JavaScript pro spravované HSM služby Azure Key Vault

Začněte s klientskou knihovnou spravovaného HSM Azure Key Vault pro JavaScript. Spravovaný HSM je plně spravovaná, vysoce dostupná cloudová služba určená pro jednoho nájemce, která umožňuje chránit kryptografické klíče pro cloudové aplikace s využitím ověřených HSM splňujících standard FIPS 140-3 úroveň 3. Další informace o spravovaném HSM najdete v přehledu.

V tomto rychlém startu se dozvíte, jak přistupovat ke klíčům spravovaného HSM a provádět kryptografické operace pomocí klientské knihovny JavaScriptu.

Spravované prostředky klientské knihovny HSM:

Referenční dokumentace k API | Zdrojový kód knihovny | Balíček (npm)

Předpoklady

Nastavení místního prostředí

Tento rychlý start používá knihovnu identit Azure s Azure CLI k ověření ve službách Azure. Vývojáři také můžou k ověření volání použít Visual Studio Code. Další informace najdete v tématu Ověření klienta pomocí klientské knihovny Azure Identity.

Přihlášení k Azure

Spuštěním az login příkazu se přihlaste:

az login

Vytvoření složky projektu a inicializace

  1. Vytvořte složku projektu a přejděte na ni:

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

  2. Inicializace projektu:

    npm init -y

Instalace balíčků

Nainstalujte klientské knihovny Azure Identity a Azure Key Vault Keys.

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

Vytvoření ukázkového kódu

Vytvořte soubor s názvem index.js s následujícím kódem. Nahraďte <hsm-name> názvem spravovaného HSM a <key-name> názvem existujícího klíče.

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

Spuštění aplikace

Spusťte aplikaci:

node index.js

Měl by se zobrazit výstup podobný následujícímu:

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!

Vysvětlení kódu

Ověřování pomocí DefaultAzureCredential

DefaultAzureCredential automaticky vybere příslušné přihlašovací údaje na základě vašeho prostředí:

Životní prostředí Použité přihlašovací údaje
Virtuální počítače Azure, App Service, Azure Functions Spravovaná identita přiřazená systémem nebo přiřazená uživatelem
Azure Kubernetes Service Identita úloh
Místní vývoj Azure CLI, Visual Studio nebo přihlašovací údaje VS Code
Kanály CI/CD Federace identit pracovního zatížení nebo objekt služby

Kontrola přihlašovacích údajů využívá tyto zdroje v pořadí:

  1. Proměnné prostředí
  2. Identita úloh
  3. Spravovaná identita
  4. Azure CLI
  5. Azure PowerShell
  6. Visual Studio / přihlašovací údaje VS Code

Pro produkční úlohy v Azure se důrazně doporučují spravované identity, protože zcela eliminují správu přihlašovacích údajů.

Klíčové operace

Třída KeyClient poskytuje metody pro:

  • Vytvoření, získání, aktualizace a odstranění klíčů
  • Výpis klíčů a verzí klíčů
  • Zálohování a obnovení klíčů

Třída CryptographyClient poskytuje kryptografické operace:

  • Šifrování a dešifrování dat
  • Podepsání a ověření podpisů
  • Zabalení a rozbalení klíčů

Přiřazení rolí ve spravovaném HSM

Aby vaše aplikace mohla přistupovat ke klíčům, přiřaďte správnou místní roli RBAC Managed HSM k vaší spravované identitě. Nahraďte hodnoty <vm-name>, <resource-group> a <hsm-name> skutečnými hodnotami.

# 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

Další informace o rolích a oprávněních naleznete v vestavěné role místního RBAC pro spravované HSM.

Vyčistěte zdroje

Pokud už ji nepotřebujete, odstraňte skupinu prostředků a všechny související prostředky:

az group delete --name <resource-group>

Výstraha

Odstraněním skupiny prostředků se spravovaný HSM umístí do stavu měkkého odstranění. Spravovaný HSM bude nadále účtován, dokud se neodstraní. Viz Ochrana proti měkkému odstranění a zneužití spravovaného HSM

Další kroky

  • Last updated on